rest-query
Advanced tools
Weekly downloads
Readme
Work in progress, early alpha.
/!\ This documentation is still a work in progress! /!\
A hook is a registered function that is triggered when some event occurs.
There are few differences between a classical event (i.e.: the observer pattern) and a Rest Query hook:
Whatever the hook, they are always functions of the form: function( context )
returning a Promise
that resolve once completed.
App hooks are executed when the Rest Query app is at different stage of execution.
The hook is a function of the form: function( appContext )
, appContext
being an object, where:
App
the running App instanceNote that appContext
here IS NOT a Context instance, because there are for request to the service.
The current Rest Query stage will wait for the Promise
's hook to resolve to continue, if it rejects the Rest Query app will be aborted.
This hook is executed once, when Rest Query is starting up, after the config is fully loaded, after any built-in initialization are finished and just before Rest Query starts accepting request.
This hook is executed once, when Rest Query is shutting down, before the HTTP module shutdown.
Document hooks are executed when a user issue a request on a document.
NEW: It is now possible to specify an array of hook in the schema, they will be called one after the other (in a serial fashion).
If one hook call context.done()
, it will prevent default behavior as well as subsequent hooks.
There are two type of hooks, normal or before hooks and after hooks. When a normal hook throw or reject, all the request is aborted, after hooks are run after the default behavior, and thus do not change the final outcome of the request, if it throws or rejects, it does not change the HTTP status, but subsequent after hook will not run.
The hook is a function of the form: function( context )
, where:
Context
an object containing various information on the current request to be processed, see ContextThe request processing will wait for the Promise
's hook to resolve to continue.
When:
The context.hook.incomingDocument
contains the document about to be created: it can be altered by the hook.
The context.hook.existingDocument
contains the document about to be replaced, it is only set for PUT request overwriting an existing document.
The context.parentObjectNode
is the parent objectNode of the resource about to be created (e.g. PUT, POST on a collection).
The context.objectNode
is more contextual, for PUT overwriting a document, it is the existing objectNode about to be overwritten,
for POST or PUT creating a new document, this is the same than context.parentObjectNode
.
In fact context.objectNode
is always the last existing objectNode during the URL traversal.
It is often recommended not to use context.objectNode
which is more for Rest Query internal stuff.
If context.linkerObjectNode
is set, then the resource about to be created is linked by that objectNode (e.g. PUT on a link).
When:
The context.document
contains the freshly created document.
The context.objectNode
contains the freshly created objectNode.
If context.hook.deletedDocument
is set, this is the document that have been deleted (this is the same document as context.hook.existingDocument
in the beforeCreate hook).
If context.linkerObjectNode
is set, then the freshly created resource is linked by that objectNode (e.g. PUT on a link).
When:
The context.hook.incomingPatch
contains the patch about to be issued: it can be altered by the hook.
The context.hook.existingDocument
is always set, and contains the document that will be patched (before the patch).
The context.objectNode
contains the objectNode about to be patched.
When:
The context.hook.appliedPatch
contains the patch that have been applied, it could be different from context.hook.incomingPatch
of the beforeModify hook because it was sanitized before being applied.
The context.document
contains the document in its final state (after the patch is applied).
The context.objectNode
contains the patched objectNode.
When:
The context.hook.existingDocument
is always set, and contains the document about to be deleted.
The context.objectNode
contains the objectNode about to be deleted.
When:
The context.hook.deletedDocument
contains the removed document.
The context.objectNode
contains the removed objectNode, it can be useful to retrieve some data, but it should not be used
to modify or traverse it (e.g. access its children).
When:
The context.input.query.search
contains the text search.
The context.input.query.filter
contains the already checked and fixed filters.
If context.input.query.search
is removed, the default search behavior is prevented, so it is possible to replace that
by custom CORRECT query filter (those new filters will not be checked/fixed by Rest Query).
Specific hooks are for special collections like Users
.
For documents of collection: Users.
When:
The context.hook.incomingDocument
contains the connection document: it can be altered by the hook.
BETA, not well specified yet.
For documents of collection: Users.
When:
The context.document
contains the user for which the token is created.
The context.hook.token
contains the token data.
BETA, not well specified yet.
For documents of collection: Users.
When:
BETA, not well specified yet.
For documents of collection: Users.
When:
The context.document
contains the user for which a new token is created.
The context.hook.token
contains the token.
BETA, not well specified yet.
For documents of collection: Users.
When:
The context.hook.incomingDocument
contains the incoming document: it can be altered by the hook.
BETA, not well specified yet.
For documents of collection: Users.
When:
The context.document
contains the user for which the API key is created.
The context.hook.apiKey
contains the API key.
BETA, not well specified yet.
All hooks, collection methods and object methods receive a Context
instance as their unique argument.
A context contains all data relative to the request in-progress, and is used internally as well.
It is of utmost importance to know how work a context, because it's the only input and output for userland code.
This is the data structure of a context:
App
the app instanceObject
contains data that have been passed as input (e.g. by a HTTP client), where:
string
the original method used (i.e. the lower-cased HTTP method)Array
the fully parsed path to the resourceObject
particular query (filters, populate, etc...) to apply on the resourceObject
(optional) the given document, if any (e.g. the body of a HTTP PUT request)Object
(optional) the given binary stream, if any (e.g. a part of a multipart body of a HTTP PUT request)Object
contains data that goes alongside with the main resource about to be sent (e.g. to a HTTP client or to a hook, etc), where:
object
or Stream
the data that is the response of the requestobject
(optional) extra data result of before-type of hook that further processing may include in the final data object (only few rare methods care)number
a particular HTTP status that may overide the default oneObject
(optional) meta-data of the document, common meta data:
string
the type of the content, default to application/json
string
if binary data is about to be sent, this is the name of the fileFunction
(optional) the serializer to use, default to JSON.stringify()Performer
it represents the entity performing the action, it can retrieve a user (if connected and if it's not a system performer)
as well as its group, and is mainly used for rights/access managementsArray
the remaining and fully parsed path to the resource, different from .input.pathParts
, since it only contains the remaining partsObject
contains current schema's alterationCollectionNode
hold current collectionNodeObjectNode
(optional) hold current objectNodeObjectNode
(optional) hold the parent objectNode of the current objectNode, or the parent objectNode of the current collectionNodeCollectionNode
(optional) internal usage onlyArray
internal usage onlyArray
(optional) internal usage onlyObjectNode
(optional) the objectNode that is linking to the current nodeDocument
(optional) the targeted/created/related document in its final state, for object methods it is the same as .objectNode.object
Object
(optional) a patch to apply to a documentboolean
true if there is nothing more to do for this request (however, no hook or methods will be called with isDone: true
)Object
hook-specific data, may change from one hook to another, so see the hook documentation for details.
Some non-exhaustive common properties:
Object
(optional) a whole document to create or that will overwrite another.Object
(optional) a patch to apply on a existing document.Object
(optional) a patch that have been applied on a existing document (afterModify)Object
(optional) if set, it is an existing document about to be patched or overwritten.Object
(optional) if set, it is a document that have been deleted or replaced.Object
userland-specific data, can be used to communicate informations from upstream hooks to downstream hooksFurthermore, the context object has this public methods:
A Job Runner is a function of the form: function( jobData , job , app )
.
any
the data to be processed by the job runner, this is pure userlandScheduler.Job
it is the Job instance calling this runner, it can be used to call the Job's APIApp
it is App instance running the SchedulerThe Scheduler await for this function, so it MUST be async or return a Promise
.
After awaiting, the job is considered done and no more actions should be hanging.
If it throws, the job is considered failed and may be retried later.
If it is a permanent error, the job runner should throw an Error having a fatal
property set to true.
FAQs
The Awesome REST Framework!
The npm package rest-query receives a total of 684 weekly downloads. As such, rest-query popularity was classified as not popular.
We found that rest-query demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket installs a Github app to automatically flag issues on every pull request and report the health of your dependencies. Find out what is inside your node modules and prevent malicious activity before you update the dependencies.