+ 
+
+
+
+
+ - -Verifying or parsing the token on the client usually isn't necessary since the server does that on JWT authentication and returns with the token information but it can still be done manually with the [jwt-decode](https://www.npmjs.com/package/jwt-decode) package. - -- -## app.reAuthenticate([force]) - -`app.reAuthenticate() -> Promise` will try to authenticate using the access token from the storage or the window location (e.g. after a successful [OAuth](./oauth.md) login). This is normally called to either show your application (when successful) or showing a login page or redirecting to the appropriate OAuth link. - -```js -try { - await app.reAuthenticate() - showDashboard() -} catch (error) { - showLoginPage() -} -``` - -
- -`app.reAuthenticate()` has to be called when you want to use the token from storage. **There is no need to call it more than once**, so you’d typically only do it once when the application initializes. When successful, all subsequent requests will send their authentication information automatically. - -- -In some rare cases, for example making sure the user object returned by `app.get('authentication')` is up-to-date after it was changed on the server, you may force reauthentication via `app.reAuthenticate(true)`. - -## app.authenticate(data) - -`app.authenticate(data) -> Promise` will try to authenticate with a Feathers server by passing a `strategy` and other properties as credentials. - -```ts -try { - // Authenticate with the local email/password strategy - await app.authenticate({ - strategy: 'local', - email: 'my@email.com', - password: 'my-password' - }) - // Show e.g. logged in dashboard page -} catch (error: any) { - // Show login page (potentially with `e.message`) - console.error('Authentication error', e) -} -``` - -- `data {Object}` - of the format `{strategy [, ...otherProps]}` - - `strategy {String}` - the name of the strategy to be used to authenticate. Required. - - `...otherProps {Properties} ` vary depending on the chosen strategy. Above is an example of using the `local` strategy. - -## app.logout() - -Removes the access token from storage on the client. It also calls the `remove` method of the [authentication service](./service.md). - -## app.get('authentication') - -`app.get('authentication') -> Promise` is a Promise that resolves with the current authentication information. For most strategies this is the best place to **get the currently authenticated user**: - -```js -// Returns the authenticated user -const { user } = await app.get('authentication') -// Gets the authenticated accessToken (JWT) -const { accessToken } = await app.get('authentication') -``` - -## app.authentication - -Returns the instance of the [AuthenticationClient](#authenticationclient). - -## AuthenticationClient - -### service - -`app.authentication.service` returns an instance of the authentication client service, normally `app.service('authentication')`. - -### storage - -`app.authentication.storage` returns the storage instance (e.g. window.LocalStorage, React Native AsyncStorage or an in-memory store). - -### handleSocket(socket) - -`app.authentication.handleSocket(socket) -> void` makes sure that a websocket real-time connection is always re-authenticated before making any other request. - -### getFromLocation(location) - -`app.authentication.getFromLocation(location) -> Promise` tries to retrieve an access token from `window.location`. This usually means the `access_token` in the hash set by the [OAuth authentication strategy](./oauth.md). - -### setAccessToken(token) - -`app.authentication.setAccessToken(token) -> Promise` sets the access token in the storage (normally `feathers-jwt` in `window.localStorage`). - -### getAccessToken() - -`app.authentication.getAccessToken() -> Promise` returns the access token from `storage`. If not found it will try to get the access token via [getFromLocation()]() or return `null` if neither was successful. - -### removeAccessToken() - -`app.authentication.removeAccessToken() -> Promise` removes the access token from the storage. - -### reset() - -`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, strategy?) - -`app.authentication.reAuthenticate(force = false, strategy) -> Promise` will re-authenticate with the current access token from [app.authentication.getAccessToken()](). If `force` is set to `true` it will always re-authenticate, with the default `false` only when not already authenticated. - -`strategy` is an optional parameter which defaults to the configured `jwtStrategy`. - -### authenticate() - -The internal method called when using [app.authenticate()](#app-authenticate-data). - -### logout() - -The internal method called when using [app.logout()](#app-logout). - -## Customization - -The [AuthenticationClient]() can be extended to provide custom functionality and then passed during initialization: - -```ts -import { feathers } from '@feathersjs/feathers' -import socketio from '@feathersjs/socketio-client' -import io from 'socket.io-client' -import authentication, { AuthenticationClient } from '@feathersjs/authentication-client' - -const socket = io('http://api.feathersjs.com') -const app = feathers() - -class MyAuthenticationClient extends AuthenticationClient { - getFromLocation(location) { - // Do custom location things here - return super.getFromLocation(location) - } -} - -// Setup the transport (Rest, Socket, etc.) here -app.configure(socketio(socket)) - -// Pass the custom authentication client class as the `Authentication` option -app.configure( - authentication({ - Authentication: MyAuthenticationClient - }) -) -``` - -## Hooks - -The following hooks are added to the client side application automatically (when calling `app.configure(authentication())`). - -### authentication - -Hook that ensures for every request that authentication is completed and successful. It also makes the authentication information available in the client side `params` (e.g. `params.user`). - -### populateHeader - -Adds the appropriate `Authorization` header for any REST request. diff --git a/docs/api/authentication/hook.md b/docs/api/authentication/hook.md deleted file mode 100644 index 4c75e1ec79..0000000000 --- a/docs/api/authentication/hook.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -outline: deep ---- - -# Authenticate Hook - -The `authenticate` hook will use `params.authentication` of the service method call and run [authenticationService.authenticate()](./service.md#authenticate-data-params-strategies). - -The hook will - -- Throw an error if the strategy fails -- Throw an error if no authentication information is set and it is an external call (`params.provider` is set) or do nothing if it is an internal call (`params.provider` is `undefined`) -- If successful, merge `params` with the return value of the authentication strategy - -For example, a successful [JWT strategy](./jwt.md) authentication will set: - -```js -params.authentication.payload // The decoded payload -params.authentication.strategy === 'jwt' // The strategy name -params.user // or params[entity] if entity is not `null` -``` - -In the following hooks and for the service method call. It can be used as a `before` or `around` [hook](../hooks.md). - -## authenticate(...strategies) - -Check `params.authentication` against a list of authentication strategy names. - -```ts -import { authenticate } from '@feathersjs/authentication' - -// Authenticate with `jwt` and `api-key` strategy -// using app.service('authentication') as the authentication service -app.service('messages').hooks({ - around: { - all: [authenticate('jwt', 'api-key')] - } -}) -``` - -## authenticate(options) - -Check `params.authentication` against a list of strategies and specific authentication service. Available `options` are: - -- `service` - The path to the authentication service -- `strategies` - A list of strategy names - -```js -import { authenticate } from '@feathersjs/authentication' - -// Authenticate with `jwt` and `api-key` strategy -// using app.service('v1/authentication') as the authentication service -app.service('messages').hooks({ - before: { - all: [ - authenticate({ - service: 'v1/authentication', - strategies: ['jwt', 'api-key'] - }) - ] - } -}) -``` diff --git a/docs/api/authentication/index.md b/docs/api/authentication/index.md deleted file mode 100644 index ed354470fe..0000000000 --- a/docs/api/authentication/index.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -outline: deep ---- - -# Authentication Overview - -The `@feathersjs/authentication` plugins provide a collection of tools for username/password, JWT and OAuth (GitHub, Facebook etc.) authentication as well as custom authentication mechanisms. - -It consists of the following core modules: - -- `@feathersjs/authentication` which includes - - The [AuthenticationService](./service.md) that allows to register [authentication strategies](./strategy.md) and create and manage access tokens - - The [JWTStrategy](./jwt.md) to use JWTs to make authenticated requests - - The [authenticate hook](./hook.md) to limit service calls to an authentication strategy. -- [Local authentication](./local.md) for local username/password authentication -- [OAuth authentication](./oauth.md) for Google, GitHub, Facebook etc. authentication -- [The authentication client](./client.md) to use Feathers authentication on the client. - -
- -`@feathersjs/authentication` is an abstraction for different authentication mechanisms. It does not handle things like user verification or password reset functionality etc. This can be implemented manually, with the help of libraries like [feathers-authentication-management](https://github.com/feathers-plus/feathers-authentication-management) or a platform like [Auth0](https://auth0.com/). - -diff --git a/docs/api/authentication/jwt.md b/docs/api/authentication/jwt.md deleted file mode 100644 index 88d562bbb8..0000000000 --- a/docs/api/authentication/jwt.md +++ /dev/null @@ -1,157 +0,0 @@ ---- -outline: deep ---- - -# JWT Authentication - -
- -Since the default options are what most clients expect for JWT authentication they usually don't need to be customized. - -- -To change the settings for generating and validating a JWT see the [authentication service configuration](./service.md#configuration) - -## JwtStrategy - -### getEntity(id, params) - -`jwtStrategy.getEntity(id, params)` returns the entity instance for `id`, usually `entityService.get(id, params)`. It will _not_ be called if `entity` in the [authentication configuration](./service.md#configuration) is set to `null`. - -### authenticate(data, params) - -`jwtStrategy.authenticate(data, params)` will try to verify `data.accessToken` by calling the strategies [authenticationService.verifyAccessToken](./service.md). - -Returns a promise that resolves with the following format: - -```js -{ - [entity], - accessToken, - authentication: { - strategy: 'jwt', - payload - } -} -``` - -
- -Since the JWT strategy returns an `accessToken` property (the same as the token sent to this strategy), that access token will also be returned by [authenticationService.create](./service.md#create-data-params) instead of creating a new one. - -- -### getEntityQuery(params) - -Returns the `query` to use when calling `entityService.get` (default: `{}`). - -### parse(req, res) - -Parse the HTTP request headers for JWT authentication information. By default in the `Authorization` header. Returns a promise that resolves with either `null` or data in the form of: - -```js -{ - strategy: '
- -The methods described in this section are intended for [customization](#customization) purposes and internal calls. They usually do not need to be called directly. - -- -### getEntityQuery(query, params) - -`localStrategy.getEntityQuery(query, params) -> Promise` returns the query for finding the entity. `query` includes the `usernameField` or `entityUsernameField` as `{ [field]: username }` and by default returns a promise that resolves with `{ $limit: 1 }` combined with `query`. - -### findEntity(username, params) - -`localStrategy.findEntity(username, params) -> Promise` return the entity for a given username and service call parameters. It will use the query returned by `getEntityQuery` and call `.find` on the entity (usually `/users`) service. It will return a promise that resolves with the first result of the `.find` call or throw an error if nothing was found. - -### getEntity(entity, params) - -`localStrategy.getEntity(authResult, params) -> Promise` returns the external representation for `entity` that will be sent back to the client. - -### hashPassword(password) - -`localStrategy.hashPassword(password) -> Promise` creates a safe one-way hash of the given plain `password` string. By default [bCryptJS](https://www.npmjs.com/package/bcryptjs) is used. - -### comparePassword(entity, password) - -`localStrategy.comparePassword(entity, password) -> Promise` compares a plain text `password` with the hashed password of the `entity` returned by `findEntity`. Returns the `entity` or throws an error if the passwords don't match. - -### authenticate(authentication, params) - -`localStrategy.authenticate(authentication, params)` is the main endpoint implemented by any [authentication strategy](./strategy.md). It is usually called for authentication requests for this strategy by the [AuthenticationService](./service.md). - -## Customization - -The `LocalStrategy` can be customized like any ES6 class and then registered on the [AuthenticationService](./service.md): - -```ts -import type { Application, Params, Query } from '@feathersjs/feathers' -import { AuthenticationService, JWTStrategy } from '@feathersjs/authentication' -import { LocalStrategy } from '@feathersjs/authentication-local' - -class MyLocalStrategy extends LocalStrategy { - async getEntityQuery(query: Query, params: Params) { - // Query for use but only include `active` users - return { - ...query, - active: true, - $limit: 1 - } - } -} - -export default (app: Application) => { - const authService = new AuthenticationService(app) - - authService.register('local', new MyLocalStrategy()) - - // ... - app.use('/authentication', authService) -} -``` - -## Helpers - -### Protecting fields - -As of Feathers v5, external [resolvers](../schema/resolvers.md) using the `schemaHooks.resolveExternal` hook are the preferred method to hide or change fields for external requests. The following will always hide the user password for external responses and events: - -```ts -import { resolve, schemaHooks } from '@feathersjs/schema' - -export const userExternalResolver = resolve
- -If you are attempting to authenticate using an existing oAuth access token, ensure that you have added the strategy (e.g. 'facebook') to the allowed [authStrategies](./service.md#configuration) configuration. - -- -### OAuth URLs - -There are two URLs and redirects that are important for OAuth authentication: - -- `http(s)://
- -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. You can force query based redirect by adding a `?` to the end of the `redirect` option. - -- -If the `redirect` option is not set and no origin is available the authentication result data will be sent as JSON instead. - -Dynamic redirects to the same URL are possible by setting the `redirect` query parameter in the OAuth flow. For example, the following OAuth link: - -```html - Login with GitHub -``` - -With the above configuration will redirect to `https://app.mydomain.com/dashboard` after the OAuth flow. - -## Options - -Options are usually set under the registered name via [Feathers configuration](../configuration.md) in `config/default.json` or `config/
- -Removing the `redirect` option allows to troubleshoot troubleshoot OAuth authentication errors as a JSON response by opening the oAuth URL directly in the browser. - -- -```json -{ - "authentication": { - "origins": ["localhost:3030"], - "oauth": { - "redirect": "/frontend", - "google": { - "key": "...", - "secret": "...", - "custom_params": { "access_type": "offline" } - }, - "twitter": { - "key": "...", - "secret": "..." - } - } - } -} -``` - -
- -All OAuth strategies will by default always look for configuration under `authentication.oauth.- -Here is a [list of all Grant configuration options](https://github.com/simov/grant#all-available-options) that are available: - -| Key | Location | Description | -| :------------------------- | :------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------- | -| request_url | [oauth.json](https://github.com/simov/grant/blob/master/config/oauth.json) | OAuth1/step1 | -| authorize_url | [oauth.json](https://github.com/simov/grant/blob/master/config/oauth.json) | OAuth1/step2 or OAuth2/step1 | -| access_url | [oauth.json](https://github.com/simov/grant/blob/master/config/oauth.json) | OAuth1/step3 or OAuth2/step2 | -| oauth | [oauth.json](https://github.com/simov/grant/blob/master/config/oauth.json) | OAuth version number | -| scope_delimiter | [oauth.json](https://github.com/simov/grant/blob/master/config/oauth.json) | string delimiter used for concatenating multiple scopes | -| protocol, host, path | `defaults` | used to generate `redirect_uri` | -| transport | `defaults` | [transport](#response-data-transport) to use to deliver the response data in your final `callback` route | -| state | `defaults` | toggle random `state` string generation for OAuth2 | -| key | `[provider]` | OAuth app key, reserved aliases: `consumer_key` and `client_id` | -| secret | `[provider]` | OAuth app secret, reserved aliases: `consumer_secret` and `client_secret` | -| scope | `[provider]` | list of scopes to request | -| custom_params | `[provider]` | custom authorization [parameters](#custom-parameters) and their values | -| subdomain | `[provider]` | string to be [embedded](#subdomain-urls) in `request_url`, `authorize_url` and `access_url` | -| nonce | `[provider]` | toggle random `nonce` string generation for [OpenID Connect](#openid-connect) providers | -| callback | `[provider]` | final callback route on your server to receive the [response data](#response-data) | -| dynamic | `[provider]` | allow [dynamic override](#dynamic-override) of configuration | -| overrides | `[provider]` | [static overrides](#static-overrides) for a provider | -| response | `[provider]` | [limit](#limit-response-data) the response data | -| token_endpoint_auth_method | `[provider]` | authentication method for the [token endpoint](#token-endpoint-auth-method) | -| name | generated | provider's [name](#grant), used to generate `redirect_uri` | -| profile_url | [grant-profile](https://github.com/simov/grant-profile) | The URL to retrieve the user profile from | -| [provider] | generated | provider's [name](#grant) as key | -| redirect_uri | generated | OAuth app [redirect URI](#redirect-uri), generated using `protocol`, `host`, `path` and `name` | - -## OAuthStrategy - -### entityId - -`oauthStrategy.entityId -> string` returns the name of the id property of the entity. - -### getEntityQuery(profile, params) - -`oauthStrategy.getEntityQuery(profile, params) -> Promise` returns the entity lookup query to find the entity for a profile. By default returns - -```js -{ - [`${this.name}Id`]: profile.sub || profile.id -} -``` - -### getEntityData(profile, entity, params) - -`oauthStrategy.getEntityData(profile, existing, params) -> Promise` returns the data to either create a new or update an existing entity. `entity` is either the existing entity or `null` when creating a new entity. - -### getProfile(data, params) - -`oauthStrategy.getProfile(data, params) -> Promise` returns the user profile information from the OAuth provider that was used for the login. `data` is the OAuth callback information which normally contains e.g. the OAuth access token. - -### getRedirect (data) - -`oauthStrategy.getRedirect(data) -> Promise` returns the URL to redirect to after a successful OAuth login and entity lookup or creation. By default it redirects to `authentication.oauth.redirect` from the configuration with `#access_token=`. If `authentication.oauth` is not set in the configuration, OAuth authentication will be disabled. - -
- -The authentication service can also be configured dynamically or without Feathers configuration by using [app.set](../application.md#set-name-value), e.g. `app.set('authentication', config)`. - -- -The following options are available: - -- `secret`: The JWT signing secret. -- `service`: The path of the entity service -- `authStrategies`: A list of authentication strategy names to allow on this authentication service to create access tokens. -- `parseStrategies`: A list of authentication strategies that should be used to parse HTTP requests. Defaults to the same as `authStrategies`. -- `entity`: The name of the field that will contain the entity after successful authentication. Will also be used to set `params[entity]` (usually `params.user`) when using the [authenticate hook](./hook). Can be `null` if no entity is used (see [stateless tokens](../../cookbook/authentication/stateless.md)). -- `entityId`: The id property of an entity object. Only necessary if the entity service does not have an `id` property (e.g. when using a custom entity service). -- `jwtOptions`: All options available for the [node-jsonwebtoken package](https://github.com/auth0/node-jsonwebtoken). - -An authentication service configuration in `config/default.json` can look like this: - -```json -{ - "authentication": { - "secret": "CHANGE_ME", - "entity": "user", - "service": "users", - "authStrategies": ["jwt", "local"], - "jwtOptions": { - "header": { "typ": "access" }, - "audience": "https://yourdomain.com", - "issuer": "feathers", - "algorithm": "HS256", - "expiresIn": "1d" - } - } -} -``` - -
- -`typ` in the `header` options is not a typo, it is part of the [JWT JOSE header specification](https://tools.ietf.org/html/rfc7519#section-5). - -- -Additionally to the above configuration, most [strategies](./strategy.md) will look for their own configuration under the name it was registered. An example can be found in the [local strategy configuration](./local.md#configuration). - -## Authentication flows - -Below are the flows how the authentication service can be used. - -### To _create a new JWT_ - -For any strategy allowed in `authStrategies`, a user can call `app.service('/authentication').create(data)` or `POST /authentication` with `data` as `{ strategy: name, ...loginData }`. Internally authentication will then - -- Call the strategy `.authenticate` method with `data` -- Create a JWT for the entity returned by the strategy -- Return the JWT (`accessToken`) and the additional information from the strategy - -For `local` strategy, the user has to be created before doing auth, otherwise, a 401 `NotAuthenticated` error will be sent. - -### To _authenticate an external request_ - -For any HTTP request and strategy allowed in `parseStrategies` or - if not set - `authStrategies` authentication will: - -- Call [strategy.parse](./strategy.md#parse-req-res) and set the return value of the first strategy that does not return `null` as `params.authentication` -- Verify `params.authentication` using the [authenticate hook](./hook.md) which calls the strategy `.authenticate` method with `params.authentication` as the data -- Merge the return value of the strategy with `params` (e.g. setting `params.user`) - -### To authenticate _your own service request_ - -For any service that uses the [authenticate hook](./hook.md) called internally you can set `params.authentication` in the service call which will then: - -- Verify `params.authentication` using the [authenticate hook](./hook.md) which calls the strategy `.authenticate` method with `params.authentication` as the data -- Merge the return value of the strategy with `params` (e.g. setting `params.user`) - -
- -You can set `params.authentication` for internal requests on the server but usually setting the entity (`params.user` in most cases) if you already have it available should be preferred. This will avoid the overhead of running authentication again if it has already been done. - -- -## AuthenticationService - -### constructor(app [, configKey]) - -`const authService = new AuthenticationService(app, configKey = 'authentication')` initializes a new authentication service with the [Feathers application](../application.md) instance and a `configKey` which is the name of the configuration property to use via [app.get()](../application.md#get-name) (default: `app.get('authentication')`). Upon initialization it will also update the configuration with the [default settings](#configuration). - -### authenticate(data, params, ...strategies) - -`authService.authenticate(data, params, ...strategies) -> Promise` is the main authentication method and authenticates `data` and `params` against a list of strategies in `strategies`. - -`data` _must_ always contain a `strategy` property indicating the name of the strategy. If `data.strategy` is not available or not allowed (included in the `strategies` list) a `NotAuthenticated` error will be thrown. Otherwise the result of [strategy.authenticate()](./strategy.md#authenticate-authentication-params) will be returned. - -### create(data, params) - -`authService.create(data, params) -> Promise` runs `authService.authenticate` with `data`, `params` and the list of `strategies` from `authStrategies` in the [configuration](#configuration). As with any other [Feathers service](../services.md), this method will be available to clients, e.g. running a `POST /authentication`. - -If successful it will create a JWT with the payload taken from [authService.getPayload](#getpayload-authresult-params) and the options from [authService.getTokenOptions](#gettokenoptions-authresult-params). `data` _must_ always contain a valid and allowed `strategy` name. Will emit the [`login` event](#app-on-login). - -### remove(id, params) - -`authService.remove(id, params) -> Promise` should be called with `id` set to `null` or to the authenticated access token. Will verify `params.authentication` and emit the [`logout` event](#app-on-logout) if successful. - -### configuration - -`authService.configuration` returns a copy of current value of `app.get(configKey)` (default: `app.get('authentication')`). This is a deep copy of the configuration and is not intended to be modified. In order to change the configuration, [app.set(configKey)](../application.md#set-name-value) should be used: - -```ts -const config = app.get('authentication') - -// Update configuration with a new entity -app.set('authentication', { - ...config, - entity: 'some other entity name' -}) -``` - -### register(name, strategy) - -`authService.register(name, strategy)` registers an [authentication strategy](./strategy.md) under `name` and calls the strategy methods `setName`, `setApplication`, `setAuthentication` and `verifyConfiguration` if they are implemented. - -### getStrategy(name) - -`service.getStrategy(name)` returns the authentication strategy registered under `name`. Usually authentication strategies do not need to be used directly. - -### getStrategies(...names) - -`service.getStrategies(...names) -> AuthenticationStrategy[]` returns the [authentication strategies](./strategy.md) that exist for a list of names. The returned array may include `undefined` values if the strategy does not exist. Usually authentication strategies do not need to be used directly. - -```js -const [localStrategy] = authService.getStrategies('local') -``` - -### createAccessToken(payload) - -`authService.createAccessToken(payload, [options, secret]) -> Promise` creates a new access token. By default it is a [JWT](https://jwt.io/) with `payload`, using [configuration.jwtOptions](#configuration) merged with `options` (optional). It will either use `authService.configuration.secret` or the optional `secret` to sign the JWT. Throws an error if the access token can not be created. - -```ts -const token = await app.service('authentication').createAccessToken({ - permission: 'admin' -}) -``` - -
- -Normally, it is not necessary to call this method directly. Calling [authService.create(data, params)](#create-data-params) using an authentication strategy will take care of creating the correct access token. - -- -### verifyAccessToken(accessToken) - -`authService.verifyAccessToken(accessToken, [options, secret]) -> Promise` verifies the access token. By default it will try to verify a JWT using `configuration.jwtOptions` merged with `options` (optional). Will either use `configuration.secret` or the optional `secret` to verify the JWT. Returns the encoded payload or throws an error. - -### getTokenOptions(authResult, params) - -`authService.getTokenOptions(authResult, params) -> Promise` returns the options for creating a new access token based on the return value from calling [authService.authenticate()](#authenticate-data-params-strategies). Called internally on [authService.create()](#create-data-params). It will try to set the JWT `subject` to the entity (user) id if it is available which will then be used by the [JWT strategy](./jwt.md) to populate `params[entity]` (usually `params.user`). - -### getPayload(authResult, params) - -`authService.getPayload(authResult, params) -> Promise` returns the access token payload for an authentication result (the return value of [authService.create()](#create-data-params)) and [service call parameters](../services.md#params). Called internally on [.create](#create-data-params). Returns either `params.payload` or an empty object (`{}`). - -### parse(req, res, ...strategies) - -`authService.parse(req, res, ...strategies) -> Promise` parses a [NodeJS HTTP request](https://nodejs.org/api/http.html#http_class_http_incomingmessage) and [HTTP response](https://nodejs.org/api/http.html#http_class_http_serverresponse) for authentication information using `strategies` calling [each strategies `.parse()` method](./strategy.md#parse-req-res) if it is implemented. Will return the value of the first strategy that didn't return `null`. This does _not_ authenticate the request, it will only return authentication information that can be used by `authService.authenticate` or `authService.create`. - -### setup(path, app) - -`authService.setup(path, app)` verifies the [configuration](#configuration) and makes sure that - -- A `secret` has been set -- If `entity` is not `null`, check if the entity service is available and make sure that either the `entityId` configuration or the `entityService.id` property is set. -- Register internal hooks to send events and keep real-time connections up to date. All custom hooks should be registered at this time. - -## app.get('defaultAuthentication') - -After registering an authentication service, it will set the `defaultAuthentication` property on the application to its configuration name (`configKey` set in the constructor) if it does not exist. `app.get('defaultAuthentication')` will be used by other parts of Feathers authentication to access the authentication service if it is not otherwise specified. Usually this will be `'authentication'`. - -## Customization - -The `AuthenticationService` can be customized like any other class: - -```ts -import type { Params } from '@feathersjs/feathers' -import type { AuthenticationResult } from '@feathersjs/authentication' -import { AuthenticationService } from '@feathersjs/authentication' - -class MyAuthService extends AuthenticationService { - async getPayload(authResult: AuthenticationResult, params: Params) { - // Call original `getPayload` first - const payload = await super.getPayload(authResult, params) - const { user } = authResult - - if (user && user.permissions) { - payload.permissions = user.permissions - } - - return payload - } -} - -app.use('/authentication', new MyAuthService(app)) -``` - -Things to be aware of when extending the authentication service: - -- When implementing your own `constructor`, always call `super(app, configKey)` -- When overriding a method, calling `super.method` and working with its return value is recommended unless you are certain your custom method behaves exactly the same way, otherwise things may no longer work as expected. -- When extending `setup`, `super.setup(path, app)` should always be called, otherwise events and real-time connection authentication will no longer work. - -## Events - -For both, `login` and `logout` the event data is `(authenticationResult, params, context) => {}` as follows: - -- `authResult` is the return value of the `authService.create` or `authService.remove` call. It usually contains the user and access token. -- `params` is the service call parameters -- `context` is the service methods [hook context](../hooks.md#hook-context) - -### app.on('login') - -`app.on('login', (authenticationResult, params, context) => {})` will be sent after a user logs in. This means, after any successful external call to [authService.create](#create-data-params). - -
- -The `login` event is also sent for e.g. reconnections of websockets and may not always have a corresponding `logout` event. Use the [`disconnect` event](../channels.md#app-on-disconnect) for handling disconnection. - -- -### app.on('logout') - -`app.on('logout', (authenticationResult, params, context) => {})` will be sent after a user explicitly logs out. This means after any successful external call to [authService.remove](#remove-id-params). diff --git a/docs/api/authentication/strategy.md b/docs/api/authentication/strategy.md deleted file mode 100644 index d001de5404..0000000000 --- a/docs/api/authentication/strategy.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -outline: deep ---- - -# Authentication Strategies - -An authentication strategy is any object or class that implements at least an [authenticate(data, params)]() method. They can be registered with the AuthenticationService to authenticate service calls and other requests. The following strategies already come with Feathers: - -- [JWTStrategy](./jwt.md) in `@feathersjs/authentication` -- [LocalStrategy](./local.md) in `@feathersjs/authentication-local` -- [OAuthStrategy](./oauth.md) in `@feathersjs/authentication-oauth` - -More details on how to customize existing strategies can be found in their API documentation. This section describes the common methods for all authentication strategies and how a custom authentication strategy can be implemented. - -## setName(name) - -Will be called with the `name` under which the strategy has been [registered on the authentication service](./service.md#register-name-strategy). Does not have to be implemented. - -## setApplication(app) - -Will be called with the [Feathers application](../application.md) instance. Does not have to be implemented. - -## setAuthentication(service) - -Will be called with the [Authentication service](./service.md) this strategy has been registered on. Does not have to be implemented. - -## verifyConfiguration() - -Synchronously verify the configuration for this strategy and throw an error if e.g. required fields are not set. Does not have to be implemented. - -## authenticate(authentication, params) - -Authenticate `authentication` data with additional `params`. `authenticate` should throw a `NotAuthenticated` if it failed or return an authentication result object. - -## parse(req, res) - -Parse a given plain Node HTTP request and response and return `null` or the authentication information it provides. Does not have to be implemented. - -This is called by the authentication service. See [AuthService.parse](https://dove.feathersjs.com/api/authentication/service.html#parse-req-res-strategies) - -## AuthenticationBaseStrategy - -The `AuthenticationBaseStrategy` class provides a base class that already implements some of the strategy methods below with some common functionality: - -- [setName](#setname-name) sets `this.name` -- [setApplication](#setapplication-app) sets `this.app` -- [setAuthentication](#setauthentication-service) sets `this.authentication` -- `configuration` getter returns `this.authentication.configuration[this.name]` -- `entityService` getter returns the entity (usually `/users`) service from `this.app` - -## Examples - -Examples for authentication strategies can be found in the [Cookbook](../../cookbook/): - -- [Anonymous strategy](../../cookbook/authentication/anonymous.md) diff --git a/docs/api/configuration.md b/docs/api/configuration.md deleted file mode 100644 index c4e2890d5a..0000000000 --- a/docs/api/configuration.md +++ /dev/null @@ -1,114 +0,0 @@ ---- -outline: deep ---- - -# Configuration - -
- -Direct access to nested config properties is not supported via `app.get()`. To access a nested config property (e.g. `Customer.dbConfig.host`, use `app.get('Customer').dbConfig.host`. - -- -## Configuration validation - -`app.configure(configuration(validator))` loads the configuration from `node-config`, makes it available via `app.get()` and validates the original configuration against a [Feathers schema](./schema/) validator when [app.setup](./application.md#setup-server) (or [app.listen](./application.md#listen-port)) is called. - -```ts -import { feathers } from '@feathersjs/feathers' -import { Ajv } from '@feathersjs/schema' -import { Type, getValidator } from '@feathersjs/typebox' -import type { Static } from '@feathersjs/typebox' -import configuration from '@feathersjs/configuration' - -const configurationSchema = Type.Object( - { - port: Type.Number(), - host: Type.String() - }, - { $id: 'Configuration', additionalProperties: false } -) - -const configurationValidator = getValidator(configurationSchema, new Ajv()) - -type ServiceTypes = {} -// Use the schema type for typed `app.get` and `app.set` calls -type Configuration = Static
- -The NODE_CONFIG_DIR environment variable isn’t used directly by @feathersjs/configuration but by the [node-config](https://github.com/lorenwest/node-config) module that it uses. For more information on configuring node-config settings, see the [Configuration Files Wiki page](https://github.com/lorenwest/node-config/wiki/Configuration-Files). - -diff --git a/docs/api/databases/adapters.md b/docs/api/databases/adapters.md deleted file mode 100644 index e92781e4d7..0000000000 --- a/docs/api/databases/adapters.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -outline: deep ---- - -# Overview - -Feathers database adapters are modules that provide [services](../services.md) that implement standard [CRUD](https://en.wikipedia.org/wiki/Create,_read,_update_and_delete) functionality for a specific database. They use a [common API](./common.md) for initialization and settings, and they provide a [common query syntax](./querying.md). - -
- -[Services](../services.md) allow to implement access to _any_ database or API. The database adapters listed here are just convenience wrappers with a common API. See the community adapters section for support for other datastores. - -- -## Core Adapters - -The following data storage adapters are available in Feathers core - -| Core Package | Supported Data Stores | -| -------------------- | -------------------------------------------------------------------------------------------------------------- | -| [Memory](./memory) | Memory | -| [MongoDB](./mongodb) | MongoDB | -| [SQL (Knex)](./knex) | MySQL
- -Every database adapter is an implementation of the [Feathers service interface](../services.md). If there is no adapter available for your database of choice, you can still use it directly in a [custom service](../services.md). We recommend being familiar with Feathers services, service events and hooks and the database before using a database adapter. - -- -## Initialization - -### `new
- -Disabling or changing the default pagination is not available in the client. Only `params.query` is passed to the server (also see a [workaround here](https://github.com/feathersjs/feathers/issues/382#issuecomment-288125825)) - -- -## params.adapter - -Setting the `adapter` in the [service method `params`](../services.md#params) allows do dynamically modify the database adapter options based on the request. This e.g. allows to temporarily allow multiple entry creation/changes or the pagination settings. - -```ts -const messages = [ - { - text: 'message 1' - }, - { - text: 'message 2' - } -] - -// Enable multiple entry insertion for this request -app.service('messages').create(messages, { - adapter: { - multi: true - } -}) -``` - -
- -If the adapter has a `Model` option, `params.adapter.Model` can be used to point to different databases based on the request to e.g. allow multi-tenant systems. This is usually done by setting `context.params.adapter` in a [hook](../hooks.md). - -- -## params.paginate - -Setting `paginate` in the [service method `params`](../services.md#params) allows to change or disable the default pagination for a single request: - -```ts -// Get all messages as an array -const allMessages = await app.service('messages').find({ - paginate: false -}) -``` - -## Extending Adapters - -There are two ways to extend existing database adapters. Either by extending the base class or by adding functionality through hooks. - -### Classes - -All modules also export an [ES6 class](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Classes) as `
- -These methods are only available internally on the server, not on the client side and only for the Feathers database adapters. They do _not_ send any events. - -- -### adapter.find(params) - -`adapter.find(params) -> Promise` returns a list of all records matching the query in `params.query` using the [common querying mechanism](./querying.md). Will either return an array with the results or a page object if [pagination is enabled](#pagination). - -```ts -// Find all messages for user with id 1 -const messages = await app.service('messages').find({ - query: { - userId: 1 - } -}) - -console.log(messages) - -// Find all messages belonging to room 1 or 3 -const roomMessages = await app.service('messages').find({ - query: { - roomId: { - $in: [1, 3] - } - } -}) - -console.log(roomMessages) -``` - -Find all messages for user with id 1 - -``` -GET /messages?userId=1 -``` - -Find all messages belonging to room 1 or 3 - -``` -GET /messages?roomId[$in]=1&roomId[$in]=3 -``` - -### adapter.get(id, params) - -`adapter.get(id, params) -> Promise` retrieves a single record by its unique identifier (the field set in the `id` option during initialization). - -```ts -const message = await app.service('messages').get(1) - -console.log(message) -``` - -``` -GET /messages/1 -``` - -### adapter.create(data, params) - -`adapter.create(data, params) -> Promise` creates a new record with `data`. `data` can also be an array to create multiple records. - -```ts -const message = await app.service('messages').create({ - text: 'A test message' -}) - -console.log(message) - -const messages = await app.service('messages').create([ - { - text: 'Hi' - }, - { - text: 'How are you' - } -]) - -console.log(messages) -``` - -``` -POST /messages -{ - "text": "A test message" -} -``` - -### adapter.update(id, data, params) - -`adapter.update(id, data, params) -> Promise` completely replaces a single record identified by `id` with `data`. Does not allow replacing multiple records (`id` can't be `null`). `id` can not be changed. - -```ts -const updatedMessage = await app.service('messages').update(1, { - text: 'Updates message' -}) - -console.log(updatedMessage) -``` - -``` -PUT /messages/1 -{ "text": "Updated message" } -``` - -### adapter.patch(id, data, params) - -`adapter.patch(id, data, params) -> Promise` merges a record identified by `id` with `data`. `id` can be `null` to allow replacing multiple records (all records that match `params.query` the same as in `.find`). `id` can not be changed. - -```ts -const patchedMessage = await app.service('messages').patch(1, { - text: 'A patched message' -}) - -console.log(patchedMessage) - -const params = { - query: { read: false } -} - -// Mark all unread messages as read -const multiPatchedMessages = await app.service('messages').patch( - null, - { - read: true - }, - params -) -``` - -``` -PATCH /messages/1 -{ "text": "A patched message" } -``` - -Mark all unread messages as read - -``` -PATCH /messages?read=false -{ "read": true } -``` - -### adapter.remove(id, params) - -`adapter.remove(id, params) -> Promise` removes a record identified by `id`. `id` can be `null` to allow removing multiple records (all records that match `params.query` the same as in `.find`). - -```ts -const removedMessage = await app.service('messages').remove(1) - -console.log(removedMessage) - -const params = { - query: { read: true } -} - -// Remove all read messages -const removedMessages = await app.service('messages').remove(null, params) -``` - -``` -DELETE /messages/1 -``` - -Remove all read messages - -``` -DELETE /messages?read=true -``` diff --git a/docs/api/databases/knex.md b/docs/api/databases/knex.md deleted file mode 100644 index fc57770c75..0000000000 --- a/docs/api/databases/knex.md +++ /dev/null @@ -1,565 +0,0 @@ ---- -outline: deep ---- - -# SQL Databases - -
- -The Knex adapter implements the [common database adapter API](./common) and [querying syntax](./querying). - -- -## API - -### KnexService(options) - -`new KnexService(options)` returns a new service instance initialized with the given options. The following example extends the `KnexService` and then uses the `sqliteClient` (or relevant client for your SQL database type) from the app configuration and provides it to the `Model` option, which is passed to the new `MessagesService`. - -```ts -import type { Params } from '@feathersjs/feathers' -import { KnexService } from '@feathersjs/knex' -import type { KnexAdapterParams, KnexAdapterOptions } from '@feathersjs/knex' - -import type { Application } from '../../declarations' -import type { Messages, MessagesData, MessagesQuery } from './messages.schema' - -export interface MessagesParams extends KnexAdapterParams
- -Since SQL does not have a concept of nested objects, joined properties will be dot separated strings, **not nested objects**. Conversion can be done by e.g. using Lodash `_.set` in a [resolver converter](../schema/resolvers.md#options). - -- -This works well for individual properties, however if you require the complete (and safe) representation of the entire related data, use a [resolver](../schema/resolvers.md) instead. - -## Transactions - -The Knex adapter comes with three hooks that allows to run service method calls in a transaction. They can be used as application wide hooks or per service. - -To use the transactions feature, you must ensure that the three hooks (start, end and rollback) are being used. - -At the start of any request, a new transaction will be started. All the changes made during the request to the services that are using knex will use the transaction. At the end of the request, if successful, the changes will be commited. If an error occurs, the changes will be forfeit, all the `creates`, `patches`, `updates` and `deletes` are not going to be commited. - -The object that contains `transaction` is stored in the `params.transaction` of each request. - -
- -If you call another Knex service within a hook and want to share the transaction you will have to pass `context.params.transaction` in the parameters of the service call. - -- -Sometimes it can be important to know when the transaction has been completed (committed or rolled back). For example, we might want to wait for transaction to complete before we send out any realtime events. This can be done by awaiting on the `transaction.committed` promise which will always resolve to either `true` in case the transaction has been committed, or `false` in case the transaction has been rejected. - -```ts -app.service('messages').publish(async (data, context) => { - const { transaction } = context.params - - if (transaction) { - const success = await transaction.committed - - if (!success) { - return [] - } - } - - return app.channel(`rooms/${data.roomId}`) -}) -``` - -This also works with nested service calls and nested transactions. For example, if a service calls `transaction.start()` and passes the transaction param to a nested service call, which also calls `transaction.start()` in it's own hooks, they will share the top most `committed` promise that will resolve once all of the transactions have successfully committed. - - -### Example Transaction Setup - -We will be using TypeBox schemas throughout, but that is not a requirement. - -We will have two services `Order` and `ShippingOrder` - -When we create an `Order` we want to automatically create a `ShippingOrder`, but if `Order` or `ShippingOrder` fail to be created we want to roll everything back and not save either. - -#### Order Schema - -```ts -export const orderSchema = Type.Object( - { - id: Type.String({ format: 'uuid' }), - item: Type.String(), - address: Type.String(), - quantity: Type.Number() - }, - { $id: 'Order', additionalProperties: false } -) -``` - -#### Shipping Order Schema - -```ts -export const shippingOrderSchema = Type.Object( - { - id: Type.String({ format: 'uuid' }), - order_id: Type.String({ format: 'uuid', $schema: 'Order' }), - expedited: Type.Boolean(), - shipped: Type.Boolean() - }, - { $id: 'ShippingOrder', additionalProperties: false } -) -``` - -#### After hook - -Let's start by adding our logic to automatically create our `ShippingOrder`. - -In our `order.ts` file we can add this hook - -```ts -after: { - create: [ - async (context: HookContext
- -You can emulate an error by throwing an error in the before create hook of your `shipping-order.ts` file - -```ts -create: [ - async () => { - throw new Error('Fail') - }, - schemaHooks.validateData(shippingOrderDataValidator), - schemaHooks.resolveData(shippingOrderDataResolver) -] -``` - -- -#### Application wide wrapping transaction - -Using the global hooks in `src/app.ts` we are able to wrap all of our `create`, `update`, and `patch` hooks. - -```ts -import { transaction } from '@feathersjs/knex' - -const transactionHandler = async (context: HookContext
-We have to use await here otherwise the transaction will close before the creation is finished. For something like sending an email, you can opt to not await. - -```ts -context.params.transaction?.committed.then((success: any) => { - if (!success) return - //Send Email -}) -``` - -- -### Service wide wrapping transaction - -The simplest way of doing this is - -- Add `transaction.start()` in the before create hook. -- Add `transaction.end()` in the after create hook. -- Add `transaction.rollback()` in the error all hook. - -```ts -app.service(orderPath).hooks({ - around: { - // ... - }, - before: { - // ... - create: [ - schemaHooks.validateData(orderDataValidator), - schemaHooks.resolveData(orderDataResolver), - transaction.start() - ] - }, - after: { - create: [ - async (context: HookContext
- -The memory adapter implements the [common database adapter API](./common) and [querying syntax](./querying). - -- -## API - -### Usage - -```ts -import { MemoryService } from '@feathersjs/memory' - -type Message = { - id: number - text: string -} - -type MessageData = Pick
- -The MongoDB adapter implements the [common database adapter API](./common) and [querying syntax](./querying). - -- -## API - -### `MongoDBService(options)` - -`new MongoDBService(options)` returns a new service instance initialized with the given options. The following example extends the `MongoDBService` and then uses the `mongodbClient` from the app configuration and provides it to the `Model` option, which is passed to the new `MessagesService`. - -```ts -import type { Params } from '@feathersjs/feathers' -import { MongoDBService } from '@feathersjs/mongodb' -import type { MongoDBAdapterParams, MongoDBAdapterOptions } from '@feathersjs/mongodb' - -import type { Application } from '../../declarations' -import type { Messages, MessagesData, MessagesQuery } from './messages.schema' - -export interface MessagesParams extends MongoDBAdapterParams
- -Note that creating indexes for an existing collection with many entries should be done as a separate operation instead. See the [MongoDB createIndex documentation](https://www.mongodb.com/docs/manual/reference/method/db.collection.createIndex/) for more information. - -- -## Querying - -Additionally to the [common querying mechanism](./querying.md) this adapter also supports [MongoDB's query syntax](https://www.mongodb.com/docs/manual/tutorial/query-documents/) and the `update` method also supports MongoDB [update operators](https://www.mongodb.com/docs/manual/reference/operator/update/). - -## Search - -
- -Note that in a normal application all MongoDB specific operators have to explicitly be added to the [TypeBox query schema](../schema/typebox.md#query-schemas) or [JSON query schema](../schema/schema.md#querysyntax). - -- -There are two ways to perform search queries with MongoDB: - -- Perform basic Regular Expression matches using the `$regex` filter. -- Perform full-text search using the `$search` filter. - -### Basic Regex Search - -You can perform basic search using regular expressions with the `$regex` operator. Here's an example query. - -```js -{ - text: { $regex: 'feathersjs', $options: 'igm' }, -} -``` - -### Full-Text Search - -See the MongoDB documentation for instructions on performing full-text search using the `$search` operator: - -- Perform [full-text queries on self-hosted MongoDB](https://www.mongodb.com/docs/manual/core/link-text-indexes/). -- Perform [full-text queries on MongoDB Atlas](https://www.mongodb.com/docs/atlas/atlas-search/) (MongoDB's first-party hosted database). -- Perform [full-text queries with the MongoDB Pipeline](https://www.mongodb.com/docs/manual/tutorial/text-search-in-aggregation/) - -## Aggregation Pipeline - -In Feathers v5 Dove, we added support for the full power of MongoDB's Aggregation Framework and blends it seamlessly with the familiar Feathers Query syntax. The `find` method automatically uses the aggregation pipeline when `params.pipeline` is set. - -The Aggregation Framework is accessed through the mongoClient's `model.aggregate` method, which accepts an array of "stages". Each stage contains an operator which describes an operation to apply to the previous step's data. Each stage applies the operation to the results of the previous step. It’s now possible to perform any of the [Aggregation Stages](https://www.mongodb.com/docs/upcoming/reference/operator/aggregation-pipeline/) like `$lookup` and `$unwind`, integration with the normal Feathers queries. - -Here's how it works with the operators that match the Feathers Query syntax. Let's convert the following Feathers query: - -```ts -const query = { - text: { $regex: 'feathersjs', $options: 'igm' }, - $sort: { createdAt: -1 }, - $skip: 20, - $limit: 10 -} -``` - -The above query looks like this when converted to aggregation pipeline stages: - -```ts -;[ - // returns the set of records containing the word "feathersjs" - { $match: { text: { $regex: 'feathersjs', $options: 'igm' } } }, - // Sorts the results of the previous step by newest messages, first. - { $sort: { createdAt: -1 } }, - // Skips the first 20 records of the previous step - { $skip: 20 }, - // returns the next 10 records - { $limit: 10 } -] -``` - -### Pipeline Queries - -You can use the `params.pipeline` array to append additional stages to the query. This next example uses the `$lookup` operator together with the `$unwind` operator to populate a `user` attribute onto each message based on the message's `userId` property. - -```ts -const result = await app.service('messages').find({ - query: { $sort: { name: 1 } }, - pipeline: [ - { - $lookup: { - from: 'users', - localField: 'userId', - foreignField: '_id', - as: 'user' - } - }, - { $unwind: { path: '$user' } } - ], - paginate: false -}) -``` - -### Aggregation Stages - -In the example, above, the `query` is added to the pipeline, first. Then additional stages are added in the `pipeline` option: - -- The `$lookup` stage creates an array called `user` which contains any matches in `message.userId`, so if `userId` were an array of ids, any matches would be in the `users` array. However, in this example, the `userId` is a single id, so... -- The `$unwind` stage turns the array into a single `user` object. - -The above is like doing a join, but without the data transforming overhead like you'd get with an SQL JOIN. If you have properly applied index to your MongoDB collections, the operation will typically execute extremely fast for a reasonable amount of data. - -A couple of other notable query stages: - -- `$graphLookup` lets you recursively pull in a tree of data from a single collection. -- `$search` lets you do full-text search on fields - -All stages of the pipeline happen directly on the MongoDB server. - -Read through the full list of supported stages [in the MongoDB documentation](https://www.mongodb.com/docs/upcoming/reference/operator/aggregation-pipeline/). - -### The `$feathers` Stage - -The previous section showed how to append stages to a query using `params.pipeline`. Well, `params.pipeline` also supports a custom `$feathers` operator/stage which allows you to specify exactly where in the pipeline the Feathers Query gets injected. - -### Example: Proxy Permissions - -Imagine a scenario where you want to query the `pages` a user can edit by referencing a `permissions` collection to find out which pages the user can actually edit. Each record in the `permissions` record has a `userId` and a `pageId`. So we need to find and return only the pages to which the user has access by calling `GET /pages` from the client. - -We could put the following query in a hook to pull the correct `pages` from the database in a single query THROUGH the permissions collection. Remember, the request is coming in on the `pages` service, but we're going to query for pages `through` the permissions collection. Assume we've already authenticated the user, so the user will be found at `context.params.user`. - -```ts -// Assume this query on the client -const pages = await app.service('pages').find({ query: {} }) - -// And put this query in a hook to populate pages "through" the permissions collection -const result = await app.service('permissions').find({ - query: {}, - pipeline: [ - // query all permissions records which apply to the current user - { - $match: { userId: context.params.user._id } - }, - // populate the pageId onto each `permission` record, as an array containing one page - { - $lookup: { - from: 'pages', - localField: 'pageId', - foreignField: '_id', - as: 'page' - } - }, - // convert the `page` array into an object, so now we have an array of permissions with permission.page on each. - { - $unwind: { path: '$page' } - }, - // Add a permissionId to each page - { - $addFields: { - 'page.permissionId': '$_id' - } - }, - // discard the permission and only keep the populated `page`, and bring it top level in the array - { - $replaceRoot: { newRoot: '$page' } - }, - // apply the feathers query stages to the aggregation pipeline. - // now the query will apply to the pages, since we made the pages top level in the previous step. - { - $feathers: {} - } - ], - paginate: false -}) -``` - -Notice the `$feathers` stage in the above example. It will apply the query to that stage in the pipeline, which allows the query to apply to pages even though we had to make the query through the `permissions` service. - -If we were to express the above query with JavaScript, the final result would the same as with the following example: - -```ts -// perform a db query to get the permissions -const permissions = await context.app.service('permissions').find({ - query: { - userId: context.params.user._id - }, - paginate: false -}) -// make a list of pageIds -const pageIds = permissions.map((permission) => permission.pageId) -// perform a db query to get the pages with matching `_id` -const pages = await context.app.service('pages').find({ - query: { - _id: { - $in: pageIds - } - }, - paginate: false -}) -// key the permissions by pageId for easy lookup -const permissionsByPageId = permissions.reduce((byId, current) => { - byId[current.pageId] = current - return byId -}, {}) -// Add the permissionId to each `page` record. -const pagesWithPermissionId = pages.map((page) => { - page.permissionId = permissionByPageId[page._id]._id - return page -}) -// And now apply the original query, whatever the client may have sent, to the pages. -// It might require another database query -``` - -Both examples look a bit complex, but te one using aggregation stages will be much quicker because all stages run in the database server. It will also be quicker because it all happens in a single database query! - -One more obstacle for using JavaScript this way is that if the user's query changed (from the front end), we would likely be required to edit multiple different parts of the JS logic in order to correctly display results. With the pipeline example, above, the query is very cleanly applied. - -## Collation - -This adapter includes support for [collation and case insensitive indexes available in MongoDB v3.4](https://docs.mongodb.com/manual/release-notes/3.4/#collation-and-case-insensitive-indexes). Collation parameters may be passed using the special `collation` parameter to the `find()`, `remove()` and `patch()` methods. - -**Example: Patch records with case-insensitive alphabetical ordering** - -The example below would patch all student records with grades of `'c'` or `'C'` and above (a natural language ordering). Without collations this would not be as simple, since the comparison `{ $gt: 'c' }` would not include uppercase grades of `'C'` because the code point of `'C'` is less than that of `'c'`. - -```ts -const patch = { shouldStudyMore: true } -const query = { grade: { $gte: 'c' } } -const collation = { locale: 'en', strength: 1 } -const patchedStudent = await students.patch(null, patch, { query, collation }) -``` - -**Example: Find records with a case-insensitive search** - -Similar to the above example, this would find students with a grade of `'c'` or greater, in a case-insensitive manner. - -```ts -const query = { grade: { $gte: 'c' } } -const collation = { locale: 'en', strength: 1 } - -const collatedStudents = await students.find({ query, collation }) -``` - -For more information on MongoDB's collation feature, visit the [collation reference page](https://docs.mongodb.com/manual/reference/collation/). - -## ObjectIds - -MongoDB uses [ObjectId](https://www.mongodb.com/docs/manual/reference/method/ObjectId/) object as primary keys. To store them in the right format they have to be converted from and to strings. - -### AJV keyword - -To validate and convert strings to an object id using AJV, the `keywordObjectId` [AJV keyword](https://ajv.js.org/api.html#ajv-addkeyword-definition-string-object-ajv) helper can be used. It is set up automatically in a generated application using MongoDB. - -```ts -import { keywordObjectId } from '@feathersjs/mongodb' - -const validator = new Ajv() - -validator.addKeyword(keywordObjectId) -``` - -### ObjectIdSchema - -Both, `@feathersjs/typebox` and `@feathersjs/schema` export an `ObjectIdSchema` helper that creates a schema which can be both, a MongoDB ObjectId or a string that will be converted with the `objectid` keyword: - -```ts -import { ObjectIdSchema } from '@feathersjs/typebox' // or '@feathersjs/schema' - -const typeboxSchema = Type.Object({ - userId: ObjectIdSchema() -}) - -const jsonSchema = { - type: 'object', - properties: { - userId: ObjectIdSchema() - } -} -``` - -
- -The `ObjectIdSchema` helper will only work when the [`objectid` AJV keyword](#ajv-keyword) is registered. - -- -### ObjectId resolvers - -While the AJV format checks if an object id is valid, it still needs to be converted to the right type. An alternative the the [AJV converter](#ajv-converter) is to use [Feathers resolvers](../schema/resolvers.md). The following [property resolver](../schema/resolvers.md) helpers can be used. - -
- -ObjectId resolvers do not need to be used when using the [AJV keyword](#ajv-keyword). They are useful however when using another JSON schema validation library. - -- -#### resolveObjectId - -`resolveObjectId` resolves a property as an object id. It can be used as a direct property resolver or called with the original value. - -```ts -import { resolveObjectId } from '@feathersjs/mongodb' - -export const messageDataResolver = resolve
- -When used via REST URLs all query values are strings and may need to be converted to the correct type. In a v5 application this is done automatically using [schemas](../schema/index.md). - -- -## Filters - -Filters are special properties (starting with a `$`) added at the top level of a query. They can determine page settings, the properties to select and more. - -### $limit - -`$limit` will return only the number of results you specify: - -```js -// Retrieves the first two unread messages -app.service('messages').find({ - query: { - $limit: 2, - read: false - } -}) -``` - -``` -GET /messages?$limit=2&read=false -``` - -
- -With [pagination enabled](common.md#pagination), to just get the number of available records set `$limit` to `0`. This will only run a (fast) counting query against the database and return a page object with the `total` and an empty `data` array. - -- -### $skip - -`$skip` will skip the specified number of results: - -```js -// Retrieves the next two unread messages -app.service('messages').find({ - query: { - $limit: 2, - $skip: 2, - read: false - } -}) -``` - -``` -GET /messages?$limit=2&$skip=2&read=false -``` - -### $sort - -`$sort` will sort based on the object you provide. It can contain a list of properties by which to sort mapped to the order (`1` ascending, `-1` descending). - -```js -// Find the 10 newest messages -app.service('messages').find({ - query: { - $limit: 10, - $sort: { - createdAt: -1 - } - } -}) -``` - -``` -/messages?$limit=10&$sort[createdAt]=-1 -``` - -### $select - -`$select` allows to pick which fields to include in the result. This will work for any service method. - -```js -// Only return the `text` and `userId` field in a message -app.service('messages').find({ - query: { - $select: ['text', 'userId'] - } -}) - -app.service('messages').get(1, { - query: { - $select: ['text'] - } -}) -``` - -``` -GET /messages?$select[]=text&$select[]=userId -GET /messages/1?$select[]=text -``` - -### $or - -Find all records that match any of the given criteria. - -```js -// Find all messages that are not marked as archived -// or any message from room 2 -app.service('messages').find({ - query: { - $or: [{ archived: { $ne: true } }, { roomId: 2 }] - } -}) -``` - -``` -GET /messages?$or[0][archived][$ne]=true&$or[1][roomId]=2 -``` - -### $and - -Find all records that match all of the given criteria. - -```js -// Find all messages that are not marked as archived and in room 2 -app.service('messages').find({ - query: { - $and: [{ archived: { $ne: true } }, { roomId: 2 }] - } -}) -``` - -``` -GET /messages?$and[0][archived][$ne]=true&$and[1][roomId]=2 -``` - -## Operators - -Operators either query a property for a specific value or determine nested special properties (starting with a `$`) that allow querying the property for certain conditions. When multiple operators are set, all conditions have to apply for a property to match. - -### Equality - -All fields that do not contain special query parameters are compared directly for equality. - -```js -// Find all unread messages in room #2 -app.service('messages').find({ - query: { - read: false, - roomId: 2 - } -}) -``` - -``` -GET /messages?read=false&roomId=2 -``` - -### $in, $nin - -Find all records where the property does (`$in`) or does not (`$nin`) match any of the given values. - -```js -// Find all messages in room 2 or 5 -app.service('messages').find({ - query: { - roomId: { - $in: [2, 5] - } - } -}) -``` - -``` -GET /messages?roomId[$in][]=2&roomId[$in][]=5 -``` - -### $lt, $lte - -Find all records where the value is less (`$lt`) or less and equal (`$lte`) to a given value. - -```js -// Find all messages older than a day -const DAY_MS = 24 * 60 * 60 * 1000 - -app.service('messages').find({ - query: { - createdAt: { - $lt: new Date().getTime() - DAY_MS - } - } -}) -``` - -``` -GET /messages?createdAt[$lt]=1479664146607 -``` - -### $gt, $gte - -Find all records where the value is more (`$gt`) or more and equal (`$gte`) to a given value. - -```js -// Find all messages within the last day -const DAY_MS = 24 * 60 * 60 * 1000 - -app.service('messages').find({ - query: { - createdAt: { - $gt: new Date().getTime() - DAY_MS - } - } -}) -``` - -``` -GET /messages?createdAt[$gt]=1479664146607 -``` - -### $ne - -Find all records that do not equal the given property value. - -```js -// Find all messages that are not marked as archived -app.service('messages').find({ - query: { - archived: { - $ne: true - } - } -}) -``` - -``` -GET /messages?archived[$ne]=true -``` - -## Search - -Searching is not part of the common querying syntax since it is very specific to the database you are using. For built in databases, see the [SQL search](./knex.md#search) and [MongoDb search](./mongodb.md#search) documentation. If you are using [a community supported adapter](/ecosystem/?cat=Database&sort=lastPublish) their documentation may contain additional information on how to implement search functionality. diff --git a/docs/api/express.md b/docs/api/express.md deleted file mode 100644 index b5a59a1521..0000000000 --- a/docs/api/express.md +++ /dev/null @@ -1,617 +0,0 @@ ---- -outline: deep ---- - -# Express - -
- -As of Feathers v5, [Koa](./koa.md) is the recommended framework integration since it is more modern, faster and easier to use. When chosen explicitly, you should already be familiar with [Express](http://expressjs.com/en/guide/routing.html). - -- -## express(app) - -`express(app) -> app` is a function that turns a [Feathers application](./application.md) into a fully Express (4+) compatible application that additionally to Feathers functionality also lets you use the [Express API](http://expressjs.com/en/4x/api.html). - -```ts -import { feathers } from '@feathersjs/feathers' -import express from '@feathersjs/express' - -const app = express(feathers()) -``` - -Note that `@feathersjs/express` also exposes the Express [built-in middleware](#built-ins) - -## express(app, expressApp) - -`express(app, expressApp) -> app` allows to extend an existing Express application with the Feathers application `app`. - -## express() - -If no Feathers application is passed, `express() -> app` returns a plain Express application just like a normal call to Express would. - -## app.use(path, service|mw|\[mw\]) - -`app.use(path, service|mw|[mw]) -> app` registers either a [service object](./services.md), an [Express middleware](http://expressjs.com/en/guide/writing-middleware.html) or an array of [Express middleware](http://expressjs.com/en/guide/writing-middleware.html) on the given path. If [a service object](./services.md) is passed it will use Feathers registration mechanism, for a middleware function Express. - -```ts -// Register a service -app.use('todos', { - async get(id) { - return { id } - } -}) - -// Register an Express middleware -app.use('/test', (req, res) => { - res.json({ - message: 'Hello world from Express middleware' - }) -}) - -// Register multiple Express middleware functions -app.use( - '/test', - (req, res, next) => { - res.data = 'Step 1 worked' - next() - }, - (req, res) => { - res.json({ - message: `Hello world from Express middleware ${res.data}` - }) - } -) -``` - -## app.listen(port) - -`app.listen(port) -> Promise
- -The `json` and `urlencoded` body parser and [params middleware](#params) has to be registered **before** any service. - -- -### app.configure(rest(formatter)) - -The default REST response formatter is a middleware that formats the data retrieved by the service as JSON. If you would like to configure your own `formatter` middleware pass a `formatter(req, res)` function. This middleware will have access to `res.data` which is the data returned by the service. [res.format](http://expressjs.com/en/4x/api.html#res.format) can be used for content negotiation. - -```ts -import { feathers } from '@feathersjs/feathers' -import express, { json, urlencoded, rest } from '@feathersjs/express' - -const app = express(feathers()) - -// Turn on JSON parser for REST services -app.use(json()) -// Turn on URL-encoded parser for REST services -app.use(urlencoded({ extended: true })) -// Set up REST transport -app.configure( - rest(function (req, res) { - // Format the message as text/plain - res.format({ - 'text/plain': function () { - res.end(`The Message is: "${res.data.text}"`) - } - }) - }) -) -``` - -## Custom service middleware - -Custom Express middleware that only should run before or after a specific service can be passed to `app.use` in the order it should run: - -```ts -const todoService = { - async get(id: Id) { - return { - id, - description: `You have to do ${id}!` - } - } -} - -app.use('todos', logRequest, todoService, updateData) -``` - -
- -Custom middleware will only run for REST requests and not when used with other transports (like Socket.io). If possible try to avoid custom middleware and use [hooks](hooks.md) or customized services instead which will work for all transports. - -- -Middleware that runs after the service has the service call information available as - -- `res.data` - The data that will be sent -- `res.hook` - The [hook](./hooks.md) context of the service method call - -For example `updateData` could look like this: - -```js -function updateData(req, res, next) { - res.data.updateData = true - next() -} -``` - -If you run `res.send` in a custom middleware after the service and don't call `next`, other middleware (like the REST formatter) will be skipped. This can be used to e.g. render different views for certain service method calls, for example to export a file as CSV: - -```ts -import json2csv from 'json2csv' - -const fields = ['done', 'description'] - -app.use('todos', todoService, function (req, res) { - const result = res.data - const data = result.data // will be either `result` as an array or `data` if it is paginated - const csv = json2csv({ data, fields }) - - res.type('csv') - res.end(csv) -}) -``` - -## params - -All Express middleware will have access to the `req.feathers` object to set properties on the service method `params`: - -```ts -import { feathers } from '@feathersjs/feathers' -import type { Id, Params } from '@feathersjs/feathers' -import express, { json, urlencoded, rest } from '@feathersjs/express' - -const app = express(feathers()) - -app.use(json()) -app.use(urlencoded({ extended: true })) -app.use(function (req, res, next) { - req.feathers.fromMiddleware = 'Hello world' - next() -}) -app.configure(rest()) - -app.use('todos', { - async get(id: Id, params: Params) { - console.log(params.provider) // -> 'rest' - console.log(params.fromMiddleware) // -> 'Hello world' - - return { - id, - params, - description: `You have to do ${id}!` - } - } -}) - -app.listen(3030) -``` - -Avoid setting `req.feathers = something` directly since it may already contain information that other Feathers plugins rely on. Adding individual properties or using `{ ...req.feathers, something }` is the more reliable option. - -
- -Since the order of Express middleware matters, any middleware that sets service parameters has to be registered **before** `app.configure(rest())` or as a [custom service middleware](#custom-service-middleware) - -- -
- -Although it may be convenient to set `req.feathers.req = req` to have access to the request object in the service, we recommend keeping your services as provider independent as possible. There usually is a way to pre-process your data in a middleware so that the service does not need to know about the HTTP request or response. - -- -### params.query - -`params.query` will contain the URL query parameters sent from the client. For the REST transport the query string is parsed using the [qs](https://github.com/ljharb/qs) module. For some query string examples see the [database querying](./databases/querying.md) chapter. - -
- -Only `params.query` is passed between the server and the client, other parts of `params` are not. This is for security reasons so that a client can't set things like `params.user` or the database options. You can always map from `params.query` to other `params` properties in a [hook](./hooks.md). - -- -For example: - -``` -GET /messages?read=true&$sort[createdAt]=-1 -``` - -Will set `params.query` to - -```json -{ - "read": "true", - "$sort": { "createdAt": "-1" } -} -``` - -
- -Note that the URL is a string so type conversion may be necessary. This is usually done with [query schemas and resolvers](./schema/index.md). - -- -
- -If an array in your request consists of more than 20 items, the [qs](https://www.npmjs.com/package/qs) parser implicitly [converts](https://github.com/ljharb/qs#parsing-arrays) it to an object with indices as keys. To extend this limit, you can set a custom query parser: `app.set('query parser', str => qs.parse(str, {arrayLimit: 1000}))` - -- -### params.provider - -For any [service method call](./services.md) made through REST `params.provider` will be set to `rest`. In a [hook](./hooks.md) this can for example be used to prevent external users from making a service method call: - -```ts -import { HookContext } from 'declarations' - -app.service('users').hooks({ - before: { - remove: [ - async (context: HookContext) => { - // check for if(context.params.provider) to prevent any external call - if (context.params.provider === 'rest') { - throw new Error('You can not delete a user via REST') - } - } - ] - } -}) -``` - -### params.headers - -`params.headers` will contain the original service request headers. - -### params.route - -Express route placeholders in a service URL will be added to the services `params.route`. See the [FAQ entry on nested routes](../help/faq.md#how-do-i-do-nested-or-custom-routes) for more details on when and when not to use nested routes. - -```ts -import { feathers } from '@feathersjs/feathers' -import express, { rest } from '@feathersjs/express' - -const app = express(feathers()) - -app.configure(rest()) -app.use(function (req, res, next) { - req.feathers.fromMiddleware = 'Hello world' - next() -}) - -app.use('users/:userId/messages', { - async get(id, params) { - console.log(params.query) // -> ?query - console.log(params.provider) // -> 'rest' - console.log(params.fromMiddleware) // -> 'Hello world' - console.log(params.route.userId) // will be `1` for GET /users/1/messages - - return { - id, - params, - read: false, - text: `Feathers is great!`, - createdAt: new Date().getTime() - } - } -}) - -app.listen(3030) -``` - -## Middleware - -`@feathersjs/express` comes with the following middleware - -### notFound(options) - -`notFound()` returns middleware that returns a `NotFound` (404) [Feathers error](./errors.md). It should be used as the last middleware **before** the error handler. The following options are available: - -- `verbose`: Set to `true` if the URL should be included in the error message (default: `false`) - -```ts -import { notFound, errorHandler } from '@feathersjs/express' - -// Return errors that include the URL -app.use(notFound({ verbose: true })) -app.use(errorHandler()) -``` - -### errorHandler() - -`errorHandler` is an [Express error handler](https://expressjs.com/en/guide/error-handling.html) middleware that formats any error response to a REST call as JSON (or HTML if e.g. someone hits our API directly in the browser) and sets the appropriate error code. - -
- -You can still use any other Express compatible [error middleware](http://expressjs.com/en/guide/error-handling.html) with Feathers. - -- -
- -Just like in Express, the error handler has to be registered _after_ all middleware and services. - -- -#### app.use(errorHandler()) - -Set up the error handler with the default configuration. - -```ts -import { feathers } from '@feathersjs/feathers' -import express from '@feathersjs/express' - -const app = express(feathers()) - -// before starting the app -app.use(express.errorHandler()) -``` - -#### app.use(errorHandler(options)) - -```ts -import { feathers } from '@feathersjs/feathers' -import express from '@feathersjs/express' - -const app = express(feathers()) - -// Just like Express your error middleware needs to be -// set up last in your middleware chain. -app.use( - express.errorHandler({ - html: function (error, req, res, next) { - // render your error view with the error object - res.render('error', error) - } - }) -) - -app.use( - errorHandler({ - html: { - 404: 'path/to/notFound.html', - 500: 'there/will/be/robots.html' - } - }) -) -``` - -
- -If you want to have the response in json format be sure to set the `Accept` header in your request to `application/json` otherwise the default error handler will return HTML. - -- -The following options can be passed when creating a new error handler: - -- `html` (Function|Object) [optional] - A custom formatter function or an object that contains the path to your custom html error pages. Can also be set to `false` to disable html error pages altogether so that only JSON is returned. -- `logger` (Function|false) (default: `console`) - Set a logger object to log the error (it will be logger with `logger.error(error)` - -### authenticate() - -`express.authenticate(...strategies)` allows to protect an Express middleware with an [authentication service](./authentication/service.md) that has [strategies](./authentication/strategy.md) registered that can parse HTTP headers. It will set the authentication information on the `req.feathers` object (e.g. `req.feathers.user`). The following example protects the `/hello` endpoint with the JWT strategy (so the `Authorization: Bearer
- -When using HTTPS URLs are safely encrypted but when using this method you have to make sure that access tokens are not logged through any of your logging mechanisms. - -- -### parseAuthentication - -The `parseAuthentication` middleware is registered automatically and will use the strategies of the default [authentication service](./authentication/service.md) to parse headers for authentication information. If you want to additionally parse authentication with a different authentication service this middleware can be registered again with that service configured. - -```ts -import { parseAuthentication } from '@feathersjs/express' - -app.use( - parseAuthentication({ - service: 'api/v1/authentication', - strategies: ['jwt', 'local'] - }) -) -``` - -### cors - -A reference to the [cors](https://github.com/expressjs/cors) module. - -### compression - -A reference to the [compression](https://github.com/expressjs/compression) module. - -### Built ins - -Note that `@feathersjs/express` also exposes the standard [Express middleware](http://expressjs.com/en/4x/api.html#express): - -- `json` - A JSON body parser -- `urlencoded` - A URL encoded form body parser -- `serveStatic` - To statically host files in a folder -- `Router` - Creates an Express router object diff --git a/docs/api/index.md b/docs/api/index.md deleted file mode 100644 index c18c197b13..0000000000 --- a/docs/api/index.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -outline: deep ---- - -# API - -This section describes all the individual modules and APIs of Feathers. - -## 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 - -- [HTTP](./http.md) - Web Standard HTTP handler for Deno, Bun, Cloudflare Workers, and Node.js -- [Koa](./koa.md) - Feathers KoaJS framework bindings, REST API provider and error middleware. -- [Express](./express.md) - Feathers Express framework bindings, REST API provider and error middleware. -- [Socket.io](./socketio.md) - The Socket.io real-time transport provider -- [Channels](./channels.md) - Channels are used to send real-time events to clients -- [Configuration](./configuration.md) - A node-config wrapper to initialize configuration of a server side application. - -## Authentication - -Feathers authentication mechanism - -- [Service](./authentication/service.md) - The main authentication service configuration -- [Hook](./authentication/hook.md) - The hook used to authenticate service method calls -- [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 - -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 -- [Authentication](authentication/client) - A client for Feathers authentication - -## Schema - -Model definitions for validating and resolving data. - -- [TypeBox](./schema/typebox.md) - Integration for TypeBox, a JSON schema type builder -- [JSON schema](./schema/schema.md) - JSON schema integration -- [Validators](./schema/validators.md) - Schema validators and validation hooks -- [Resolvers](./schema/resolvers.md) - Dynamic data resolvers - -## 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 -- [MongoDB](./databases/querying.md) - The adapter for MongoDB databases -- [SQL](./databases/knex.md) - The adapter for SQL databases using KnexJS -- [Memory](./databases/memory.md) - The adapter for in-memory data storage diff --git a/docs/api/koa.md b/docs/api/koa.md deleted file mode 100644 index e1ca7772b8..0000000000 --- a/docs/api/koa.md +++ /dev/null @@ -1,276 +0,0 @@ ---- -outline: deep ---- - -# Koa - -
- -Note that `app.configure(rest())` has to happen **after** any custom middleware. - -- -### params.query - -`params.query` will contain the URL query parameters sent from the client parsed using [koa-qs](https://github.com/koajs/qs). - -
- -Only `params.query` is passed between the server and the client, other parts of `params` are not. This is for security reasons so that a client can't set things like `params.user` or the database options. You can always map from `params.query` to other `params` properties in a [hook](./hooks.md). - -- -To increase the array limit in query strings, `koa-qs` can be reinitalized with the options for the [qs](https://www.npmjs.com/package/qs) module: - -```ts -// app.ts -import koaQs from 'koa-qs' - -// ... -koaQs(app, 'extended', { - arrayLimit: 200 -}) -``` - -### params.provider - -For any [service method call](./services.md) made through REST `params.provider` will be set to `rest`. - -### params.route - -Route placeholders in a service URL will be added to the services `params.route`. See the [FAQ entry on nested routes](../help/faq.md#how-do-i-do-nested-or-custom-routes) for more details on when and when not to use nested routes. - -```ts -import { feathers } from '@feathersjs/feathers' -import { koa, errorHandler, bodyParser, rest } from '@feathersjs/koa' - -const app = koa(feathers()) - -app.use('users/:userId/messages', { - async get(id, params) { - console.log(params.query) // -> ?query - console.log(params.provider) // -> 'rest' - console.log(params.fromMiddleware) // -> 'Hello world' - console.log(params.route) // will be `{ userId: '1' }` for GET /users/1/messages - - return { - id, - params, - read: false, - text: `Feathers is great!`, - createdAt: new Date().getTime() - } - } -}) - -app.listen(3030) -``` - -## Service middleware - -When registering a service, it is also possible to pass custom Koa middleware that should run `before` the specific service method in the `koa` [service option](./application.md#usepath-service--options): - -```ts -app.use('/todos', new TodoService(), { - koa: { - before: [ - async (ctx, next) => { - ctx.feathers // data that will be merged into sevice `params` - - // This will run all subsequent middleware and the service call - await next() - - // Then we have additional properties available on the context - ctx.hook // the hook context from the method call - ctx.body // the return value - } - ] - } -}) -``` - -Note that the order of middleware will be `[...before, serviceMethod]`. - -## Middleware - -### rest - -```ts -import { rest } from '@feathersjs/koa' - -app.configure(rest()) -``` - -Configures the middleware for handling service calls via HTTP. It will also register authentication header parsing. The following (optional) options are available: - -- `formatter` - A middleware that formats the response body -- `authentication` - The authentication `service` and `strategies` to use for parsing authentication information - -### errorHandler - -```ts -import { errorHandler } from '@feathersjs/koa' - -app.use(errorHandler()) -``` - -A middleware that formats errors as a Feathers error and sets the proper status code. Needs to be the first middleware registered in order to catch all other errors. - -### authenticate - -A middleware that allows to authenticate a user (or other authentication entity) using the [authentication service](./authentication/service.md) setting `ctx.feathers.user`. Not necessary for use with services but can be used in custom middleware. - -```ts -import { authenticate } from '@feathersjs/koa' - -// Authenticate other middleware with the JWT strategy -app.use(authenticate('jwt')) - -// Authenticate a non default service -app.use( - authenticate({ - service: 'api/v1', - strategies: ['jwt'] - }) -) -``` - -### parseAuthentication - -The `parseAuthentication` middleware is registered automatically and will use the strategies of the default [authentication service](./authentication/service.md) to parse headers for authentication information. If you want to additionally parse authentication with a different authentication service this middleware can be registered again with that service configured. - -```ts -import { parseAuthentication } from '@feathersjs/koa' - -app.use( - parseAuthentication({ - service: 'api/v1/authentication', - strategies: ['jwt', 'local'] - }) -) -``` - -### bodyParser - -A reference to the [koa-body](https://github.com/koajs/koa-body) module. - -### cors - -A reference to the [@koa/cors](https://github.com/koajs/cors) module. - -### serveStatic - -A reference to the [koa-static](https://github.com/koajs/static) module. diff --git a/docs/api/schema/index.md b/docs/api/schema/index.md deleted file mode 100644 index ef7898899f..0000000000 --- a/docs/api/schema/index.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -outline: deep ---- - -# Schema Overview - -
- -Property resolver functions should only return a value and not have side effects. This means a property resolver **should not** do things like create new data or modify the `data` or `context` object. [Hooks](../hooks.md) should be used for side effects. - -- -## Virtual property resolvers - -Virtual resolvers are property resolvers that do not use the `value` but instead always return a value of their own. The parameters are (`(data, context, status)`). The above example can be written like this: - -```ts -import { resolve, virtual } from '@feathersjs/schema' - -const userResolver = resolve
- -Virtual resolvers should always be used when combined with a [database adapter](../databases/adapters.md) in order to make valid [$select queries](../databases/querying.md#select). Otherwise queries could try to select fields that do not exist in the database which will throw an error. - -- -## Options - -A resolver takes the following options as the second parameter: - -- `converter` (optional): A `(data, context) => {}` or `async (data, context) => {}` function that can return a completely new representation of the data. A `converter` runs before `properties` resolvers. - -```ts -const userResolver = resolve
- -`schemaHooks.resolveResult` must be used as an `around` hook. This is to ensure that the database adapters will be able to handle [$select queries](../databases/querying.md#select) properly when using [virtual properties](#virtual-property-resolvers). - -- -```ts -import { hooks as schemaHooks, resolve, virtual } from '@feathersjs/schema' -import { Type } from '@feathersjs/typebox' -import type { Static } from '@feathersjs/typebox' -import type { HookContext } from '../declarations' - -const userSchema = Type.Object( - { - id: Type.Number(), - email: Type.String(), - password: Type.String(), - avatar: Type.Optional(Type.String()) - }, - { $id: 'User', additionalProperties: false } -) -type User = Static
- -In order to get the safe data from resolved associations **all services** involved need the `schemaHooks.resolveExternal` hook registered even if it does not need a resolver (`schemaHooks.resolveExternal()`). - -`schemaHooks.resolveExternal` should be registered first when used as an `around` hook or last when used as an `after` hook so that it gets the final result data. - -- -### resolveQuery - -Query resolvers use the `hooks.resolveQuery(...resolvers)` hook to modify `params.query`. This is often used to set default values or limit the query so a user can only request data they are allowed to see. It is possible to pass multiple resolvers which will run in the order they are passed, using the previous data. `schemaHooks.resolveQuery` can be used as an `around` or `before` hook. - -In this example for a `User` schema we are first checking if a user is available in our request. In the case a user is available we are returning the user's ID. Otherwise we return whatever value was provided for `id`. - -`context.params.user` would only be set if the request contains a user. This is usually the case when an external request is made. In the case of an internal request we may not have a specific user we are dealing with, and we will just return `value`. - -If we were to receive an internal request, such as `app.service('users').get(123)`, `context.params.user` would be `undefined` and we would just return the `value` which is `123`. - -```ts -import { hooks as schemaHooks, resolve } from '@feathersjs/schema' -import { Type } from '@feathersjs/typebox' -import type { Static } from '@feathersjs/typebox' -import type { HookContext } from '../declarations' - -const userSchema = Type.Object( - { - id: Type.Number(), - email: Type.String(), - password: Type.String(), - avatar: Type.Optional(Type.String()) - }, - { $id: 'User', additionalProperties: false } -) -type User = Static
- -You can find an introduction in the [JSON schema official getting started guide](https://json-schema.org/learn/getting-started-step-by-step) and a lot of type-specific JSON Schema examples in the [json-schema-to-ts docs](https://github.com/ThomasAribart/json-schema-to-ts). - -- -## Creating Schemas - -### Definitions - -If you are not familiar with JSON schema have a look at the [official getting started guide](https://json-schema.org/learn/getting-started-step-by-step). Here is an example for a possible user schema: - -```ts -import type { FromSchema } from '@feathersjs/schema' - -export const userSchema = { - $id: 'User', - type: 'object', - additionalProperties: false, - required: ['email', 'password'], - properties: { - id: { type: 'number' }, - email: { type: 'string' }, - password: { type: 'string' } - } -} as const - -export type User = FromSchema
- -See the [validators](./validators.md) chapter for more information on validators and validator functions. - -- -### getDataValidator - -`getDataValidator(definition, validator)` returns validators for the data of `create`, `update` and `patch` service methods. You can either pass a single definition in which case all properties of the `patch` schema will be optional or individual validators for `create`, `update` and `patch`. - -```ts -import { getDataValidator, Ajv } from '@feathersjs/schema' -import type { FromSchema } from '@feathersjs/schema' - -const userDataSchema = { - $id: 'User', - type: 'object', - additionalProperties: false, - required: ['email', 'password'], - properties: { - email: { type: 'string' }, - password: { type: 'string' } - } -} as const - -type UserData = FromSchema
- -For additional information also see the [TypeBox documentation](https://github.com/sinclairzx81/typebox/blob/master/readme.md#contents). - -- -## Usage - -The module exports all of TypeBox functionality with additional support for [query schemas](#query-schemas) and [validators](#validators). The following is an example for defining the message schema [from the guide](../../guides/basics/schemas.md#handling-messages) using TypeBox: - -```ts -import { Type } from '@feathersjs/typebox' -import type { Static } from '@feathersjs/typebox' - -const messageSchema = Type.Object( - { - id: Type.Number(), - text: Type.String(), - createdAt: Type.Number(), - userId: Type.Number() - }, - { $id: 'Message', additionalProperties: false } -) - -type Message = Static
- -See the [validators](./validators.md) chapter for more information on validators and validator functions. - -- -### getDataValidator - -`getDataValidator(definition, validator)` returns validators for the data of `create`, `update` and `patch` service methods. You can either pass a single definition in which case all properties of the `patch` schema will be optional or individual validators for `create`, `update` and `patch`. - -```ts -import { Ajv } from '@feathersjs/schema' -import { Type, getDataValidator } from '@feathersjs/typebox' -import type { Static } from '@feathersjs/typebox' - -const userSchema = Type.Object( - { - id: Type.Number(), - email: Type.String(), - password: Type.String(), - avatar: Type.Optional(Type.String()) - }, - { $id: 'User', additionalProperties: false } -) -type User = Static
- -For string values, use [StringEnum](#stringenum). - -- -```js -enum Foo { - A, - B, -} -const T = Type.Enum(Foo) -``` - -```js -enum Foo { - A, - B, -} -type T = Foo -``` - -```js -const T = { - anyOf: [ - { type: 'number', const: 0 }, - { type: 'number', const: 1 } - ] -} -``` - -#### Utility Types - -The utility types create types which are derived from other types. - -##### KeyOf - -Creates a schema for a string that can be any of the keys of a provided `Type.Object`. It's similar to TypeScript's [KeyOf](https://www.typescriptlang.org/docs/handbook/2/keyof-types.html#handbook-content) operator. - -```js -const T = Type.KeyOf( - Type.Object({ - x: Type.Number(), - y: Type.Number() - }) -) -``` - -```js -type T = keyof { - x: number, - y: number, -} -``` - -```js -const T = { - anyOf: [ - { type: 'string', const: 'x' }, - { type: 'string', const: 'y' } - ] -} -``` - -##### Union - -Creates a type which can be one of the types in the provided array. It's the equivalent to using `|` to form a TypeScript [Union](https://www.typescriptlang.org/docs/handbook/typescript-in-5-minutes-func.html#unions). - -```js -const T = Type.Union([Type.String(), Type.Number()]) -``` - -```js -type T = string | number -``` - -```js -const T = { - anyOf: [{ type: 'string' }, { type: 'number' }] -} -``` - -##### Intersect - -Creates an object type by combining two or more other object types. - -```js -const T = Type.Intersect([ - Type.Object({ - x: Type.Number() - }), - Type.Object({ - y: Type.Number() - }) -]) -``` - -```js -type T = { x: number } & { y: number } -``` - -```js -const T = { - type: 'object', - properties: { - x: { type: 'number' }, - y: { type: 'number' } - }, - required: ['x', 'y'] -} -``` - -##### Never - -Creates a type that will never validate if the attribute is present. This is useful if you are allowing [additionalProperties](#additionalproperties) but need to prevent using specific keys. - -```js -const T = Type.Never() -``` - -```js -type T = never -``` - -```js -const T = { - allOf: [ - { type: 'boolean', const: false }, - { type: 'boolean', const: true } - ] -} -``` - -##### Record - -Creates the JSON Schema equivalent of TypeScript's [Record](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type) utility type. - -```js -const T = Type.Record(Type.String(), Type.Number()) -``` - -```js -type T = Record
- -Ajv and most other validation libraries are only used for ensuring data is valid and are not designed to convert data to different types. Type conversions and populating data can be done using [resolvers](./resolvers.md). This ensures a clean separation of concern between validating and populating data. - -- -## Usage - -The following is the standard `validators.ts` file that sets up a validator for data and queries (for which string types will be coerced automatically). It also sets up a collection of additional formats using [ajv-formats](https://ajv.js.org/packages/ajv-formats.html). The validators in this file can be customized according to the [Ajv documentation](https://ajv.js.org/) and [its plugins](https://ajv.js.org/packages/). You can find the available Ajv options in the [Ajv class API docs](https://ajv.js.org/options.html). - -```ts -import { Ajv, addFormats } from '@feathersjs/schema' -import type { FormatsPluginOptions } from '@feathersjs/schema' - -const formats: FormatsPluginOptions = [ - 'date-time', - 'time', - 'date', - 'email', - 'hostname', - 'ipv4', - 'ipv6', - 'uri', - 'uri-reference', - 'uuid', - 'uri-template', - 'json-pointer', - 'relative-json-pointer', - 'regex' -] - -export const dataValidator = addFormats(new Ajv({}), formats) - -export const queryValidator = addFormats( - new Ajv({ - coerceTypes: true - }), - formats -) -``` - -## Validation functions - -A validation function takes data and validates them against a schema using a validator. They can be used with any validation library. Currently the `getValidator` functions are available for: - -- [TypeBox schema](./typebox.md#validators) to validate a TypeBox definition using an Ajv validator instance -- [JSON schema](./schema.md#validators) to validate a JSON schema object using an Ajv validator instance - -## Hooks - -The following hooks take a [validation function](#validation-functions) and validate parts of the [hook context](../hooks.md#hook-context). - -### validateData - -`schemaHooks.validateData` takes a [validation function](#validation-functions) and allows to validate the `data` in a `create`, `update` and `patch` request as well as [custom service methods](../services.md#custom-methods). It can be used as an `around` or `before` hook. - -```ts -import { Ajv, hooks as schemaHooks } from '@feathersjs/schema' -import { Type, getValidator } from '@feathersjs/typebox' -import type { Static } from '@feathersjs/typebox' -import { dataValidator } from '../validators' - -const userSchema = Type.Object( - { - id: Type.Number(), - email: Type.String(), - password: Type.String(), - avatar: Type.Optional(Type.String()) - }, - { $id: 'User', additionalProperties: false } -) -type User = Static
- -This page describes how to set up a Socket.io server. The [Socket.io client chapter](./client/socketio.md) shows how to connect to this server on the client and the message format for service calls and real-time events. - -- -## Configuration - -`@feathersjs/socketio` can be used standalone or together with a Feathers framework integration like [Express](./express.md). - -### socketio() - -`app.configure(socketio())` sets up the Socket.io transport with the default configuration using either the server provided by [app.listen](./application.md#listenport) or passed in [app.setup(server)](./application.md#setupserver). - -```ts -import { feathers } from '@feathersjs/feathers' -import socketio from '@feathersjs/socketio' - -const app = feathers() - -app.configure(socketio()) - -app.listen(3030) -``` - -
- -Once the server has been started with `app.listen()` or `app.setup(server)` the Socket.io object is available as `app.io`. Usually you should not have to send or listen to events on `app.io` directly. - -- -### socketio(callback) - -`app.configure(socketio(callback))` sets up the Socket.io transport with the default configuration and call `callback` with the [Socket.io server object](http://socket.io/docs/server-api/). - -```ts -import { feathers } from '@feathersjs/feathers' -import socketio from '@feathersjs/socketio' - -const app = feathers() - -app.configure( - socketio((io) => { - io.on('connection', (socket) => { - // Do something here - }) - - // Registering Socket.io middleware - io.use(function (socket, next) { - // Exposing a request property to services and hooks - socket.feathers.referrer = socket.request.referrer - next() - }) - }) -) - -app.listen(3030) -``` - -
- -Try to avoid listening and sending events on the `socket` directly since it circumvents Feathers secure dispatch mechanisms available through [channels](./channels.md) and [hooks](./hooks.md). - -- -#### Using uWebSockets.js - -uWS can be used as a drop in replacement for socket handling. -As a result you'll see lower latencies, a better memory footprint and even slightly less overall resource usage. -You will on the other hand need to install the following extra package to get things working. - -``` -npm install uNetworking/uWebSockets.js#20.31.0 --save -``` - -Now you can use the `io.attachApp` function to attach uWS as a replacement. - -```ts -import { feathers } from '@feathersjs/feathers' -import socketio from '@feathersjs/socketio' -import { App } from 'uWebSockets.js' - -const app = feathers() - -app.configure( - socketio((io) => { - io.attachApp(App()) - }) -) - -app.listen(3030) -``` - -### socketio(options [, callback]) - -`app.configure(socketio(options [, callback]))` sets up the Socket.io transport with the given [Socket.io options object](https://github.com/socketio/engine.io#methods-1) and optionally calls the callback described above. - -This can be used to e.g. configure the path where Socket.io is initialize (`socket.io/` by default). The following changes the path to `ws/`: - -```ts -import { feathers } from '@feathersjs/feathers' -import socketio from '@feathersjs/socketio' - -const app = feathers() - -app.configure( - socketio( - { - path: '/ws/' - }, - (io) => { - // Do something here - // This function is optional - } - ) -) - -app.listen(3030) -``` - -### socketio(port, [options], [callback]) - -`app.configure(socketio(port, [options], [callback]))` creates a new Socket.io server on a separate port. Options and a callback are optional and work as described above. - -```ts -import { feathers } from '@feathersjs/feathers' -import socketio from '@feathersjs/socketio' - -const app = feathers() - -app.configure(socketio(3031)) -app.listen(3030) -``` - -## params - -[Socket.io middleware](https://socket.io/docs/v4/middlewares/) can modify the `feathers` property on the `socket` which will then be used as the service call `params`: - -```ts -app.configure( - socketio((io) => { - io.use((socket, next) => { - socket.feathers.user = { name: 'David' } - next() - }) - }) -) - -app.use('messages', { - async create(data, params, callback) { - // When called via SocketIO: - params.provider // -> socketio - params.user // -> { name: 'David' } - return data - } -}) -``` - -
- -`socket.feathers` is the same object as the `connection` in a [channel](./channels.md). `socket.request` and `socket.handshake` contains information the HTTP request that initiated the connection (see the [Socket.io documentation](https://socket.io/docs/server-api/#socket-request)). - -- -### params.provider - -For any [service method call](./services.md) made through Socket.io `params.provider` will be set to `socketio`. In a [hook](./hooks.md) this can for example be used to prevent external users from making a service method call: - -```js -app.service('users').hooks({ - before: { - remove(context) { - // check for if(context.params.provider) to prevent any external call - if (context.params.provider === 'socketio') { - throw new Error('You can not delete a user via Socket.io') - } - } - } -}) -``` - -### params.query - -`params.query` will contain the query parameters sent from the client. - -
- -Only `params.query` is passed between the server and the client, other parts of `params` are not. This is for security reasons so that a client can't set things like `params.user` or the database options. You can always map from `params.query` to `params` in a before [hook](./hooks.md). - -- -### params.connection - -`params.connection` is the connection object that can be used with [channels](./channels.md). It is the same object as `socket.feathers` in a Socket.io middleware as [shown in the `params` section](#params). - -### params.headers - -`params.headers` contains the headers from the original handshake. This is usually sent with the `extraHeaders` option when initialising the connection on the client: - -```ts -const socket = io('http://localhost:9777', { - extraHeaders: { - MyHeader: 'somevalue' - } -}) -``` diff --git a/docs/auto-imports.d.ts b/docs/auto-imports.d.ts deleted file mode 100644 index 9d2400790b..0000000000 --- a/docs/auto-imports.d.ts +++ /dev/null @@ -1,10 +0,0 @@ -/* eslint-disable */ -/* prettier-ignore */ -// @ts-nocheck -// noinspection JSUnusedGlobalSymbols -// Generated by unplugin-auto-import -// biome-ignore lint: disable -export {} -declare global { - -} diff --git a/docs/comparison.md b/docs/comparison.md deleted file mode 100644 index 61774b7022..0000000000 --- a/docs/comparison.md +++ /dev/null @@ -1,9 +0,0 @@ -# Feathers vs others - -The following sections compare Feathers to other software choices that seem similar or may overlap with the use cases of Feathers. Due to the bias of these comparisons being on the Feathers website, we attempt to only use facts. Below you can find a feature comparison table and in each section you can get more detailed comparisons. If you find something invalid or out of date in the comparisons, please create an issue and we'll address it as soon as possible. - -- [Feathers vs Firebase](/feathers-vs-firebase) -- [Feathers vs Meteor](/feathers-vs-meteor) -- [Feathers vs Sails](/feathers-vs-sails) -- [Feathers vs Loopback](/feathers-vs-loopback) -- [Feathers vs Nest](/feathers-vs-nest) diff --git a/docs/components/CTAButton.vue b/docs/components/CTAButton.vue deleted file mode 100644 index 91d75fb879..0000000000 --- a/docs/components/CTAButton.vue +++ /dev/null @@ -1,58 +0,0 @@ - - - - -
- Check out the docs to learn more about Feathers.
-- Feel free say hello on Discord. -
-
- - Feathers is a full-stack web-framework for creating APIs and real-time applications with TypeScript or JavaScript. -
-- Feathers can interact with any backend technology, supports many databases out of the box - and works with any frontend technology like React, VueJS, Angular, React Native, - Android or iOS. -
-
- Build prototypes in minutes and production-ready apps in days.
-Seriously.
-{{ title }}
- -
- 
- 
- 
- 
- 
- - For TypeScript and JavaScript in Node.js, React Native and the browser -
-- Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed diam nonummy nibh - euismod tincidunt ut laoreet dolore magna aliquam erat volutpat. -
- -- -Keep in mind that the order in which configure functions are called might matter, e.g. if it is using a service, that service has to be registered first. Configure functions are not asynchronous. Any asynchronous operations should be done in [application setup hooks](#application-hooks). - -- -## Application hooks - -The application file also includes a section to set up [application hooks](../../api/hooks.md#application-hooks) which are hooks that run for every service. In our case, the `logErrorHook` to log any service errors has already been registered: - -```ts -// Register hooks that run on all service methods -app.hooks({ - around: { - all: [logErrorHook] - }, - before: {}, - after: {}, - error: {} -}) -``` - -Following that is the special [setup and teardown](../../api/hooks.md#setup-and-teardown) hook section to register hooks that run once when the application starts or shuts down. This can be used to e.g. set dynamic configuration values. - -```ts -// Register application setup and teardown hooks here -app.hooks({ - setup: [], - teardown: [] -}) -``` - -## Tests, jobs and SSR - -The `app` file can be imported like any other Node module. This means it can be used directly in tests, scheduled jobs or server side rendering without having to start a separate server instance. For example, the unit tests import the application like this: - -```ts -import assert from 'assert' -import { app } from '../../src/app' - -describe('messages service', () => { - it('registered the service', () => { - const service = app.service('messages') - - assert.ok(service, 'Registered the service') - }) -}) -``` diff --git a/docs/guides/cli/app.test.md b/docs/guides/cli/app.test.md deleted file mode 100644 index c3149f59f6..0000000000 --- a/docs/guides/cli/app.test.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -outline: deep ---- - -# Application tests - -The `app.test` file starts the server and then tests that it shows the index page and that 404 (Not Found) JSON errors are being returned. It uses the [Axios HTTP](https://axios-http.com/) library to make the calls. - -This file can e.g. be used to test application [setup](../../api/application.md#setupserver) and [teardown](../../api/application.md#teardownserver). - -All tests are using [MochaJS](https://mochajs.org/) but will be moving to the [NodeJS test runner](https://nodejs.org/api/test.html) in the future. diff --git a/docs/guides/cli/authentication.md b/docs/guides/cli/authentication.md deleted file mode 100644 index bc80718815..0000000000 --- a/docs/guides/cli/authentication.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -outline: deep ---- - -# Authentication - -The file in `src/authentication.ts` sets up an [authentication service](../../api/authentication/service.md) and registers [authentication strategies](../../api/authentication/strategy.md). Depending on the strategies you selected it looks similar to this: - -```ts -import { AuthenticationService, JWTStrategy } from '@feathersjs/authentication' -import { LocalStrategy } from '@feathersjs/authentication-local' - -import type { Application } from './declarations' - -declare module './declarations' { - interface ServiceTypes { - authentication: AuthenticationService - } -} - -export const authentication = (app: Application) => { - const authentication = new AuthenticationService(app) - - authentication.register('jwt', new JWTStrategy()) - authentication.register('local', new LocalStrategy()) - - app.use('authentication', authentication) -} -``` - -## oAuth - -Note that when selecting oAuth logins (Google, Facebook, GitHub etc.), the standard registered oAuth strategy only uses the `
- -Note that you can use `client` for client side interactions and the server side [application](./app.md#application) `app` object for server side calls in the same file. For example, if the user required an email verification but you don't want to test sending out emails you can call something like `app.service('users').patch(user.id, { isVerified: true })` to enable the new user on the server. - -diff --git a/docs/guides/cli/configuration.md b/docs/guides/cli/configuration.md deleted file mode 100644 index 20356d5484..0000000000 --- a/docs/guides/cli/configuration.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -outline: deep ---- - -### Configuration Schemas - -A generated application comes with a schema that validates the initial configuration when the application is started. This makes it much easier to catch configuration errors early which can otherwise be especially difficult to debug in remote environments. - -The configuration [schema definition](../../api/schema/index.md) can be found in `configuration.ts`. It is used as a [configuration schema](../../api/configuration.md#configuration-validation) and loads some default schemas for authentication and database connection configuration and adds values for `host`, `port` and the `public` hosted file folder. The types of this schema are also used for `app.get()` and `app.set()` [typings](./declarations.md). The initial configuration schema will be validated on application startup when calling [`app.listen()`](../../api/application.md#listenport) or [`app.setup()`](../../api/application.md#setupserver). diff --git a/docs/guides/cli/custom-environment-variables.md b/docs/guides/cli/custom-environment-variables.md deleted file mode 100644 index 0100d8456b..0000000000 --- a/docs/guides/cli/custom-environment-variables.md +++ /dev/null @@ -1,52 +0,0 @@ -# Custom Environment Variables - -While `node-config` used for [application configuration](./default.json.md) recommends to pass environment based configuration as a JSON string in a single `NODE_CONFIG` environment variable, it is also possible to use other environment variables via the `config/custom-environment-variables.json` file which looks like this by default: - -```json -{ - "port": { - "__name": "PORT", - "__format": "number" - }, - "host": "HOSTNAME", - "authentication": { - "secret": "FEATHERS_SECRET" - } -} -``` - -This sets `app.get('port')` using the `PORT` environment variable (if it is available) parsing it as a number and `app.get('host')` from the `HOSTNAME` environment variable and the authentication secret to the `FEATHERS_SECRET` environment variable. - -
- -See the [node-config custom environment variable](https://github.com/node-config/node-config/wiki/Environment-Variables#custom-environment-variables) documentation for more information. - -- -## Dotenv - -To add support for [dotenv](https://www.dotenv.org/) `.env` files run - -``` -npm install dotenv --save -``` - -And update `src/app.ts` as follows: - -```ts -// dotenv replaces all environmental variables from ~/.env in ~/config/custom-environment-variables.json -import * as dotenv from 'dotenv' -dotenv.config() - -// or for ES6 - -import 'dotenv/config'; - -import configuration from '@feathersjs/configuration' -``` - -
- -`dotenv.config()` needs to run _before_ `import configuration from '@feathersjs/configuration'` - -diff --git a/docs/guides/cli/databases.md b/docs/guides/cli/databases.md deleted file mode 100644 index eb90f7f442..0000000000 --- a/docs/guides/cli/databases.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -outline: deep ---- - -# Databases - -
- -To get the latest types in the [client](./client.md) and any time before `npm start`, `npm run compile` needs to run. - -- -## Configuration Types - -The `Configuration` interface defines the types for [app.get](../../api/application.md#getname) and [app.set](../../api/application.md#setname-value). It is extended from the type inferred from the [configuration schema](./configuration.md#configuration-schemas). Since you can store anything global to the application in `app.get` and `app.set`, you can add additional types that are not part of the initial application configuration here. - -```ts -// The types for app.get(name) and app.set(name) -// eslint-disable-next-line @typescript-eslint/no-empty-interface -export interface Configuration extends ApplicationConfiguration { - startupTime: Date -} -``` - -
- -Both `Configuration` and `ServiceTypes` need to be declared as an `interface` (even if it is empty) so they can be extended via `declare module` in other files. Do not remove the `eslint-disable-next-line` comments. - -- -## Service Types - -The `ServiceTypes` interface contains a mapping of all service paths to their service type so that [app.use](../../api/application.md#usepath-service--options) and [app.service](../../api/application.md#servicepath) use the correct type. - -```ts -// A mapping of service names to types. Will be extended in service files. -// eslint-disable-next-line @typescript-eslint/no-empty-interface -export interface ServiceTypes {} -``` - -Usually the `ServiceTypes` interface is not modified directly in this file but instead extended via `declare module` in the files where the services are registered. This usually looks like this: - -```ts -// Add this service to the service type index -declare module '../../declarations' { - interface ServiceTypes { - users: UserService - } -} -``` - -## Application - -The `Application` interface is the type for the main [app object](./app.md) using the [ServiceTypes](#service-types) interface as the service index and [ConfigurationTypes](#configuration-types) for `app.get` and `app.set`. - -```ts -// The application instance type that will be used everywhere else -export type Application = FeathersApplication
- -Always use `import { Application } from './declarations'` to get the proper service and configuration typings. You normally do **not** need to use `import { Application } from '@feathersjs/feathers'` directly. - -- -## Hook Context - -The `HookContext` type exports a [hook context](../../api/hooks.md) type with the `Application` and a generic service type `S`. - -```ts -// The context for hook functions - can be typed with a service class -export type HookContext
- -Please pick **TypeScript** as the Code language in the main menu dropdown. - -- -
- -For more information on application configuration and schemas see the [configuration API documentation](../../api/configuration.md). - -- -## Environments - -The `NODE_ENV` environment variable determines which configuration file is used. For example, setting `NODE_ENV=development` (in a single command e.g. as `NODE_ENV=development npm run dev`) will first load `config/default.json` and then merge it with `config/development.json`. If no environment is set, `config/default.json` will be used. - -## Default configuration - -The application uses the following configuration values. - -### host, port, public - -These options are used directly in the generated application - -- `host` - Is the hostname of the API server -- `port` - The port it listens on -- `public` - The name of the folder static assets are hosted in - -### paginate - -`paginate` sets the default and maximum page size when using [pagination](../../api/databases/common.md#pagination) with a [database service](../../api/databases/adapters.md). - -```json -{ - "paginate": { - "default": 10, - "max": 100 - } -} -``` - -### origins - -`origins` contains a list of frontend URLs that requests can be made from. This is used to configure cross origin (CORS) policies and oAuth (Twitter, Facebook etc.) login redirects. For example to develop locally with a [create-react-app](https://create-react-app.dev/) frontend and deploy to `app.feathersjs.com`: - -```json -{ - "origins": ["http://localhost:3030", "http://localhost:5000", "https://app.feathersjs.com"] -} -``` - -### authentication - -`authentication` contains the configuration for the authentication service and strategies. See the [authentication service configuration](../../api/authentication/service.md#configuration) for more information. For strategy specific settings refer to the [jwt](../../api/authentication/jwt.md#options), [local](../../api/authentication/local.md#options) and [oAuth](../../api/authentication/oauth.md#options) API documentation. - -### Databases - -
- -For more information see the [hooks API documentation](../../api/hooks.md). - -- -### Around hooks - -[Around hooks](../../api/hooks.md#around) allow to control the entire `before`, `after` and `error` flow in a single function. An `around` hook is an `async` function that accepts two arguments: - -- The [hook context](../../api/hooks.md#hook-context) -- An asynchronous `next` function. Somewhere in the body of the hook function, there is a call to `await next()`, which calls the `next` hooks OR the original function if all other hooks have run. - -```ts -import type { HookContext, NextFunction } from '../declarations' - -export const myFancyHook = async (context: HookContext, next: NextFunction) => { - console.log(`Running hook ${name} on ${context.path}.${context.method}`) - await next() - // Do things after here -} -``` - -You can wrap the `await next()` in a `try/catch` block to also handle errors. - -### Before, after, error - -[Before, after or error hooks](../../api/hooks.md#before-after-and-error) are `async` functions that take the [hook context](#hook-context) as the parameter. - -```ts -import type { HookContext } from '../declarations' - -export const myFancyHook = async (context: HookContext) => { - console.log(`Running hook ${name} on ${context.path}.${context.method}`) -} -``` - -## Context types - -If the hook is for a specific service, you can pass the service as a generic to the [HookContext](./declarations.md#hook-context) type which will give you the correct types for [context.data](../../api/hooks.md#contextdata), [context.result](../../api/hooks.md#contextresult) and [context.params](../../api/hooks.md#contextparams): - -```ts -import type { UserService } from '../services/users/users' -import type { HookContext } from '../declarations' - -export const myFancyUserHook = async (context: HookContext
- -For more information on what is available in migration files, see the [Knex migrations documentation](https://knexjs.org/guide/migrations.html). - -diff --git a/docs/guides/cli/log-error.md b/docs/guides/cli/log-error.md deleted file mode 100644 index af5d63b009..0000000000 --- a/docs/guides/cli/log-error.md +++ /dev/null @@ -1,3 +0,0 @@ -# Error logging hook - -The `src/hooks/log-error.ts` file exports a `logError` hook that uses the [logger](./logger.md) to log any error for a service method, including validation error details (when they are available). It is registered as an [application hook](./app.md#application-hooks) `all` hook, meaning it will log errors for any service method. diff --git a/docs/guides/cli/logger.md b/docs/guides/cli/logger.md deleted file mode 100644 index f1a00fbf0c..0000000000 --- a/docs/guides/cli/logger.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -outline: deep ---- - -# Logging - -## Logger - -The `src/logger.ts` file initialises the widely used [Winston logger](https://github.com/winstonjs/winston) library, by default with the `info` log level, logging to the console. - -```ts -import { createLogger, format, transports } from 'winston' - -// Configure the Winston logger. For the complete documentation see https://github.com/winstonjs/winston -export const logger = createLogger({ - // To see more detailed errors, change this to 'debug' - level: 'info', - format: format.combine(format.splat(), format.simple()), - transports: [new transports.Console()] -}) -``` - -You can import the logger directly in any file where you want to add logging information. - -```ts -import { logger } from './logger' - -logger.info('Log some information here') -``` diff --git a/docs/guides/cli/package.md b/docs/guides/cli/package.md deleted file mode 100644 index 3392c75ceb..0000000000 --- a/docs/guides/cli/package.md +++ /dev/null @@ -1,14 +0,0 @@ -# package.json - -## Folders - -The source and test folders to which files are generated is set in the `package.json`. To change them, rename the `src/` or `test/` folder to what you want it to and then update `package.json` `directories` section accordingly: - -```json -{ - "directories": { - "lib": "api/src", - "test": "api/test" - } -} -``` diff --git a/docs/guides/cli/prettierrc.md b/docs/guides/cli/prettierrc.md deleted file mode 100644 index e1ce9ef800..0000000000 --- a/docs/guides/cli/prettierrc.md +++ /dev/null @@ -1,9 +0,0 @@ -# Prettier - -The Feathers CLI uses [Prettier](https://prettier.io/) for code formatting and generates a configuration for it in a new application. To change the options, like the use of semicolons, quotes etc, edit the `.prettierrc` file with the [options available](https://prettier.io/docs/en/options.html). To update all existing source files with the new code style run - -``` -npm run prettier -``` - -When new files are generated, they will use the current Prettier configuration. See the [Prettier Integration with Linters](https://prettier.io/docs/en/integrating-with-linters.html) documentation for how to integrate with tools like ESLint. diff --git a/docs/guides/cli/service.class.md b/docs/guides/cli/service.class.md deleted file mode 100644 index 998127ef36..0000000000 --- a/docs/guides/cli/service.class.md +++ /dev/null @@ -1,318 +0,0 @@ ---- -outline: deep ---- - -# Service classes - -The `