@microcode/request-schema NPM

Installation

    npm install --save @microcode/request-schema

API

new Schema(methods) - Create a new schema, supporting a set of methods.

methods - What methods to support registration on.

Example:

    new Schema(['create','read','update','delete']);

Creates a new schema supporting CRUD.

schema.on(method, path, filters, func) - Register a function on a specific method and path in the schema.

method - What method to register on
path - What path to register on
filters - Optional list of filters to run before the function
func - Function to execute

The function arguments are dynamic (determined when registered), and supports all extracted parameters in the path, along with two special parameters data and context.

For normal functions, context is used as the context for the function call.
Arrow functions requires context as a parameter since the context is already overridden.

You can register multiple functions on the same path. If a filter on a function fails (due to e.g. missing authorization), the next function will attempt to run.

Example:

    schema.on('read', '/objects/:object_id/attributes', new AuthCheckFilter(), (object_id, data, context) => { ... });

schema.run(method, path, data, context) - Run a registered method

Example:

    schema.run('read', '/objects/1234/attributes', {}, { user_id: 5763 });

Filters

Filters allow for sharing common functionality to verify and or modify a request. Example use cases could be authentication or request caching.

A filter inherits from the Filter class, and implements the method run. This method may return a promise.

The data passed into the filter method is a FilterData object, and it exposes the following attributes and methods.

method - Method type being called
data - Data being passed into the function
context - Context used in this call
resolve(value) - Call to resolve early (without calling function)
reject(err) - Call to reject filter (same as throwing an error)
on_resolve(func) - Register a callback that runs after the function has successfully executed. Parameters are:
- result - Result returned from function
- context - Context used in function

Resolve callbacks execute in the order they are registered, and will execute even if a filters resolves early. If a callback throws an exception, the following functions will NOT be executed.

Resolve callbacks may return a promise.

Results

Calling a function will generate a Result (unless an error occurs). This result contains the resulting value and also a map of meta values as registered by the different filters. This allows you to decorate results, if you e.g. want to keep track of a specific action taken by a filter.

Paths

Paths are separated by forward slashes. Example: /this/is/a/path
Parameters are supported by prefixing a path component with a colon. Example: /this/is/a/:parameter. Parameters are made available to the registered function.