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

api/readme.md

@@ -158,17 +158,23 @@ app.use('/messages', {
 
 > **Important:** A successful `create` method call emits the [`created` service event](./events.md#created).
 
+> **Note:** With a [database adapters](./databases/adapters.md) `data` can be an array but the [`multi` option](./databases/common.md) has to be set.
+
 
 ### .update(id, data, params)
 
 `service.update(id, data, params) -> Promise` - Replaces the resource identified by `id` with `data`. The method should return with the complete, updated resource data. `id` can also be `null` when updating multiple records, with `params.query` containing the query criteria.
 
 > **Important:** A successful `update` method call emits the [`updated` service event](./events.md#updated-patched).
 
+> **Note:** The [database adapters](./databases/adapters.md) do not support completely replacing multiple entries. 
+
 ### .patch(id, data, params)
 
 `patch(id, data, params) -> Promise` - Merges the existing data of the resource identified by `id` with the new `data`. `id` can also be `null` indicating that multiple resources should be patched with `params.query` containing the query criteria.
 
+> **Note:** With a [database adapters](./databases/adapters.md) the [`multi` option](./databases/common.md) has to be set explicitly to support patching multiple entries.
+
 The method should return with the complete, updated resource data. Implement `patch` additionally (or instead of) `update` if you want to distinguish between partial and full updates and support the `PATCH` HTTP method.
 
 > **Important:** A successful `patch` method call emits the [`patched` service event](./events.md#updated-patched).
@@ -180,6 +186,8 @@ The method should return with the complete, updated resource data. Implement `pa
 
 > **Important:** A successful `remove` method call emits the [`removed` service event](./events.md#removed).
 
+> **Note:** With a [database adapters](./databases/adapters.md) the [`multi` option](./databases/common.md) has to be set explicitly to support removing multiple entries.
+
 
 ### .setup(app, path)
 

api/services.md

@@ -2,36 +2,101 @@
 
 Anonymous authentication can be allowed by creating a [custom strategy](../../api/authentication/strategy.md) that returns the `params` that you would like to use to identify an authenticated user.
 
+:::: tabs :options="{ useUrlFragment: false }"
+::: tab "JavaScript"
+In `src/authentication.js`:
+
 ```js
 const { AuthenticationBaseStrategy } = require('@feathersjs/authentication');
 
 class AnonymousStrategy extends AuthenticationBaseStrategy {
-  authenticate(authentication, params) {
+  async authenticate(authentication, params) {
+    return {
+      anonymous: true
+    }
+  }
+}
+
+module.exports = app => {
+  // ... authentication service setup
+  authentication.register('anonymous', new AnonymousStrategy());
+}
+```
+:::
+::: tab "TypeScript"
+```ts
+import { Params } from '@feathersjs/feathers';
+import { AuthenticationBaseStrategy, AuthenticationResult } from '@feathersjs/authentication';
+
+class AnonymousStrategy extends AuthenticationBaseStrategy {
+  async authenticate(authentication: AuthenticationResult, params: Params) {
     return {
       anonymous: true
     }
   }
 }
 
-app.service('authentication').register('anonymous', new AnonymousStrategy());
+export default function(app: Application) {
+  // ... authentication service setup
+  authentication.register('anonymous', new AnonymousStrategy());
+}
 ```
+:::
+::::
+
 
-Next, we need to create a hook called `allow-anonymous` that sets [params.authentication]() if it does not exist and if `params.provider` exists (which means it is an external call) to use that `anonymous` strategy:
+Next, we create a hook called `allow-anonymous` that sets `params.authentication` if it does not exist and if `params.provider` exists (which means it is an external call) to use that `anonymous` strategy:
 
+:::: tabs :options="{ useUrlFragment: false }"
+::: tab "JavaScript"
 ```js
-const { params } = context;
+/* eslint-disable require-atomic-updates */
+module.exports = function (options = {}) { // eslint-disable-line no-unused-vars
+  return async context => {
+    const { params } = context;
+
+    if(params.provider && !params.authentication) {
+      context.params = {
+        ...params,
+        authentication: {
+          strategy: 'anonymous'
+        }
+      }
+    }
+
+    return context;
+  };
+};
+```
+:::
+::: tab "TypeScript"
+```ts
+import { Hook, HookContext } from '@feathersjs/feathers';
 
-if(params.provider && !params.authentication) {
-  params.authentication = {
-    strategy: 'anonymous'
+export default (): Hook => {
+  return async (context: HookContext) => {
+    const { params } = context;
+
+    if(params.provider && !params.authentication) {
+      context.params = {
+        ...params,
+        authentication: {
+          strategy: 'anonymous'
+        }
+      }
+    }
+
+    return context;
   }
 }
 ```
+:::
+::::
 
-This hook should be added __before__ the [authenticate hook]() wherever anonymous authentication should be allowed:
+This hook should be added __before__ the [authenticate hook](../api/authentication/hook.md) wherever anonymous authentication should be allowed:
 
-```
-all: [ allowAnonymous(), authenticate('jwt', 'anonymous') ]
+```js
+all: [ allowAnonymous(), authenticate('jwt', 'anonymous') ],
 ```
 
 If an anonymous user now accesses the service externally, the service call will succeed and have `params.anonymous` set to `true`.

cookbook/authentication/anonymous.md

@@ -143,14 +143,16 @@ const login = async () => {
   }
 };
 
-(async () => {
+const main = async () => {
   const auth = await login();
 
   console.log('User is authenticated', auth);
 
   // Log us out again
   await client.logout();
-})();
+};
+
+main();
 ```
 
 If you now open the console and visit [localhost:3030](http://localhost:3030) you will see that our user has been authenticated.