v4 polish (feathersjs-ecosystem#1324)

Author: daffl

.vuepress/config.js

@@ -113,6 +113,9 @@ module.exports = {
         items: [{
           text: 'Awesome Feathersjs',
           link: 'https://github.com/feathersjs/awesome-feathersjs'
+        }, {
+          text: 'YouTube Playlist',
+          link: 'https://www.youtube.com/playlist?list=PLwSdIiqnDlf_lb5y1liQK2OW5daXYgKOe'
         }, {
           text: 'Previous versions',
           items: [{

.vuepress/public/_redirects

@@ -1,4 +1,4 @@
-# https://crow.docs.feathersjs.com/* https://docs.feathersjs.com/:splat 301!
+https://crow.docs.feathersjs.com/* https://docs.feathersjs.com/:splat 301!
 
 # v2 Redirects
 

.vuepress/styles/index.styl

@@ -1,2 +1,3 @@
 @require '~vuepress-plugin-tabs/dist/themes/default.styl'
-@import 'https://fonts.googleapis.com/css?family=Raleway&display=swap.css';
+@import 'https://fonts.googleapis.com/css?family=Raleway&display=swap.css';
+@import 'https://fonts.googleapis.com/css?family=Lato&display=swap.css'

.vuepress/theme/styles/index.styl

@@ -10,7 +10,7 @@ html, body
   background-color #fff
 
 body
-  font-family 'Raleway', 'Helvetica Neue', 'Helvetica', 'Arial', 'Lucida Grande', sans-serif
+  font-family 'Lato', 'Helvetica Neue', 'Helvetica', 'Arial', 'Lucida Grande', sans-serif
   -webkit-font-smoothing antialiased
   -moz-osx-font-smoothing grayscale
   font-size 16px
@@ -20,6 +20,7 @@ body
   padding-left $sidebarWidth
 
 .navbar
+  font-family 'Raleway', 'Helvetica Neue', 'Helvetica', 'Arial', 'Lucida Grande', sans-serif
   position fixed
   z-index 20
   top 0
@@ -40,6 +41,7 @@ body
   display none
 
 .sidebar
+  font-family 'Raleway', 'Helvetica Neue', 'Helvetica', 'Arial', 'Lucida Grande', sans-serif
   font-size 16px
   background-color #fff
   width $sidebarWidth
@@ -104,6 +106,7 @@ strong
   font-weight 600
 
 h1, h2, h3, h4, h5, h6
+  font-family 'Raleway', 'Helvetica Neue', 'Helvetica', 'Arial', 'Lucida Grande', sans-serif
   font-weight 600
   line-height 1.25
   .content:not(.custom) > &

README.md

@@ -11,12 +11,12 @@ Welcome to the FeathersJS documentation! Feathers is a web-framework for creatin
 
 At its core, Feathers is a set of tools and an architecture pattern that make it easy to create scalable REST APIs and real-time applications. You can build prototypes in minutes and production-ready apps in days. To get started, follow one of the following links:
 
-[__Read the guide to learn more and get started with Feathers >__](./guides/readme.md)
+[The Feathers guide >](./guides/readme.md)
 
-[__Dig into the API documentation >__](./api/readme.md)
+[The API documentation >](./api/readme.md)
 
-[__Check out the cookbook for common tasks and patterns >__](./cookbook/readme.md)
+[The cookbook for common tasks and patterns >](./cookbook/readme.md)
 
-[__Have a look at frequently asked questions and other ways to get help >__](./help/readme.md)
+[FAQ and ways to get help >](./help/readme.md)
 
-[__Migrate to the latest version >__](./guides/migrating.md)
+[Migrate to the latest version >](./guides/migrating.md)

api/assets/architecture-overview.svg

@@ -126,6 +126,10 @@ Returns the instance of the [AuthenticationClient](#authenticationclient).
 
 `app.authentication.reset()` resets the authentication state without explicitly logging out. Should not be called directly.
 
+### handleError()
+
+`app.authentication.handleError(error, type: 'authenticate'|'logout') -> Promise` handles any error happening in the `authenticate` or `logout` method. By default it removes the access token if the error is a `NotAuthenticate` error. Otherwise it does nothing.
+
 ### reAuthenticate(force)
 
 `app.authentication.reAuthenticate(force = false) -> Promise` will re-authenticate with the current access token from [app.authentication.getAccessToken()](). If `force` is set to `true` it will always reauthenticate, with the default `false` only when not already authenticated.

api/authentication/client.md

@@ -97,7 +97,11 @@ To _link an existing user_ the current access token can be added the oAuth flow
 </a>
 ```
 
-This will use the user (entity) of that access token to link the oAuth account to.
+This will use the user (entity) of that access token to link the oAuth account to. Using the [authentication client](./client.md) you can get the current access token via `app.get('authentication')`:
+
+```js
+const { accessToken } = await app.get('authentication');
+```
 
 ### Redirects
 
@@ -113,11 +117,11 @@ The `redirect` configuration option is used to redirect back to the frontend app
 }
 ```
 
-Will redirect to `https://app.mydomain.com/#access_token=<user jwt>` or `https://app.mydomain.com/#error=<some error message>`. The [authentication client](./client.md) handles those redirect automatically. It can be customized with the [getRedirect()](#getredirect) method of the oAuth strategy.
+Will redirect to `https://app.mydomain.com/#access_token=<user jwt>` or `https://app.mydomain.com/#error=<some error message>`. Redirects can be customized with the [getRedirect()](#getredirect) method of the oAuth strategy. The [authentication client](./client.md) handles the default redirects automatically already.
 
-> __Note:__ The redirect is using a hash instead of a query string by default because it is not logged server side and can be easily manipulated on the client.
+> __Note:__ The redirect is using a hash instead of a query string by default because it is not logged server side and can be easily read on the client.
 
-If `redirect` option is not set, the authentication result data will be sent as JSON instead.
+If the `redirect` option is not set, the authentication result data will be sent as JSON instead.
 
 ## Setup (Express)
 

api/authentication/oauth.md

@@ -286,6 +286,8 @@ POST /messages
 ]
 ```
 
+> **Note:** With a [database adapters](../databases/adapters.md) the [`multi` option](./databases/common.md) has to be set explicitly to support creating multiple entries.
+
 ### update
 
 Completely replace a single or multiple resources.
@@ -324,6 +326,8 @@ PATCH /messages?complete=false
 
 Will call `messages.patch(null, { complete: true }, { query: { complete: 'false' } })` on the server to change the status for all read messages.
 
+> **Note:** With a [database adapters](../databases/adapters.md) the [`multi` option](./databases/common.md) has to be set to support patching multiple entries.
+
 This is supported out of the box by the Feathers [database adapters](../databases/adapters.md) 
 
 ### remove
@@ -343,3 +347,5 @@ DELETE /messages?read=true
 ```
 
 Will call `messages.remove(null, { query: { read: 'true' } })` to delete all read messages.
+
+> **Note:** With a [database adapters](../databases/adapters.md) the [`multi` option](./databases/common.md) has to be set to support patching multiple entries.

api/client/rest.md

@@ -1,32 +1,58 @@
 # API
 
-This section describes all the APIs of Feathers and its individual modules.
-
-* __Core:__ Feathers core functionality
-  * [Application](application.md) - The main Feathers application API
-  * [Services](services.md) - Service objects and their methods and Feathers specific functionality
-  * [Hooks](hooks.md) - Pluggable middleware for service  methods
-  * [Events](events.md) - Events sent by Feathers service methods
-  * [Errors](errors.md) - A collection of error classes used throughout Feathers
-  * [Configuration](configuration.md) - A node-config wrapper to initialize configuration of a server side application.
-* __Transports:__ Expose a Feathers application as an API server
+This section describes all the individual modules and APIs of Feathers. There are three main sections of the API:
+
+- __Core:__ The Feathers core functionality that can be used on the server and the client
+- __Server:__ Feathers server side modules used with Core when creating an API server in NodeJS
+- __Client:__ Modules used on the client (NodeJS, browser or React Native) together with Core when connecting to a Feathers API server.
+
+ Here is an overview how the individual sections of the API documentation fit together:
+
+![Feathers Architecture overview](./assets/architecture-overview.svg)
+
+## Core
+
+Feathers core functionality that works on the client and the server
+
+* [Application](application.md) - The main Feathers application API
+* [Services](services.md) - Service objects and their methods and Feathers specific functionality
+* [Hooks](hooks.md) - Pluggable middleware for service  methods
+* [Events](events.md) - Events sent by Feathers service methods
+* [Errors](errors.md) - A collection of error classes used throughout Feathers
+
+## Transports
+
+Expose a Feathers application as an API server
   * [Express](express.md) - Feathers Express framework bindings, REST API provider and error middleware.
   * [Socket.io](socketio.md) - The Socket.io real-time transport provider
   * [Primus](primus.md) - The Primus real-time transport provider
+  * [Configuration](configuration.md) - A node-config wrapper to initialize configuration of a server side application.
   * [Channels](channels.md) - Decide what events to send to connected real-time clients
-* __Client:__ More details on how to use Feathers on the client
-  * [Usage](client.md) - Feathers client usage in Node, React Native and the browser (also with Webpack and Browserify)
-  * [REST](client/rest.md) - Feathers client and direct REST API server usage
-  * [Socket.io](client/socketio.md) - Feathers client and direct Socket.io API server usage
-  * [Primus](client/primus.md) - Feathers client and direct Primus API server usage
-* __Authentication:__ Feathers authentication mechanism
-  * [Service](authentication/service.md) - The main authentication service configuration
-  * [Strategies](authentication/strategy.md) - More about authentication strategies
-  * [Local](authentication/local.md) - Local email/password authentication
-  * [JWT](authentication/jwt.md) - JWT authentication
-  * [OAuth](authentication/oauth.md) - Using oAuth logins (Facebook, Twitter etc.)
-  * [Client](authentication/client.md) - A client for a Feathers authentication server
-* __Database:__ Feathers common database adapter API and querying mechanism
-  * [Adapters](databases/adapters.md) - A list of supported database adapters
-  * [Common API](databases/common.md) - Database adapter common initialization and configuration API
-  * [Querying](databases/querying.md) - The common querying mechanism
+
+## Client
+
+More details on how to use Feathers on the client
+
+* [Usage](client.md) - Feathers client usage in Node, React Native and the browser (also with Webpack and Browserify)
+* [REST](client/rest.md) - Feathers client and direct REST API server usage
+* [Socket.io](client/socketio.md) - Feathers client and direct Socket.io API server usage
+* [Primus](client/primus.md) - Feathers client and direct Primus API server usage
+
+## Authentication
+
+Feathers authentication mechanism
+
+* [Service](authentication/service.md) - The main authentication service configuration
+* [Strategies](authentication/strategy.md) - More about authentication strategies
+* [Local](authentication/local.md) - Local email/password authentication
+* [JWT](authentication/jwt.md) - JWT authentication
+* [OAuth](authentication/oauth.md) - Using oAuth logins (Facebook, Twitter etc.)
+* [Client](authentication/client.md) - A client for a Feathers authentication server
+
+## Databases
+
+Feathers common database adapter API and querying mechanism
+
+* [Adapters](databases/adapters.md) - A list of supported database adapters
+* [Common API](databases/common.md) - Database adapter common initialization and configuration API
+* [Querying](databases/querying.md) - The common querying mechanism