@whook/whook
Advanced tools
Build strong and efficient REST web services.
whook allows you to create REST and GraphQL web services by providing its
ingredients and the recipe to make it work altogether.
The recipe is your Open API (version 3.1) definition while ingredients are routes, crons, consumers, wrappers, services, commands and some environment configuration.
npm init @whook
Looks at the repository's main README for more documentation.
Runs the Whook's process
Prepare the Whook process environment
stringPick the first header value if exists
ArrayPick header values
Promise.<Object>Application monitoring service that simply log stringified contents.
Promise.<String>Initialize the BASE_URL service according to the HOST/PORT so that applications fallbacks to that default base URL.
Promise.<Object>Allow to proxy constants directly by serializing it in the build, saving some computing and increasing boot time of the build.
Promise.<Object>Initialize the COMMANDS service gathering the project commands.
Promise.<Object>Initialize the CRONS_DEFINITIONS service gathering the project crons.
Promise.<function()>Initialize the Whook cron handlers used by the router to know which cron to run for a given cron name.
Promise.<function()>A simple passthrough service proxying the CRONS_WRAPPERS.
Promise.<String>Initialize the DEFINITIONS service.
PromiseInitialize an error handler for the HTTP router
Promise.<String>Initialize the HOST service from ENV or auto-detection if none specified in ENV
PromiseInitialize an HTTP router
Promise.<HTTPServer>Initialize an HTTP server
Promise.<WhookHTTPTransaction>Instantiate the httpTransaction service
Promise.<function()>An initializer to build a single Whook route handler.
Promise.<Object>Obfuscate sensible informations.
Promise.<Number>Initialize the PORT service from ENV or auto-detection if none specified in ENV
Promise.<Object>Wrap the ENV service in order to filter ENV vars for the build
Promise.<Object>Initialize the ROUTES_DEFINITIONS service gathering the project routes definitions.
Promise.<function()>Initialize the Whook routes handlers used by the router to know which handler to run for a given route.
Promise.<function()>A simple passthrough service proxying the ROUTES_WRAPPERS.
Promise.<Number>Initialize the schema validator service for application schemas validation. This central place is aimed to compile schemas once and use them many times.
Promise.<string>Resolves the Whook plugins from their names
Runs the Whook's process
Kind: global function
Returns: Object
A promise of the injected services
| Param | Type | Description |
|---|---|---|
| servicesNames | Array.<String> | Root dependencies names to instanciate and return |
| $ | Knifecycle | The Knifecycle instance to use for the run |
Prepare the Whook process environment
Kind: global function
Returns: Promise
A promise of the Knifecycle instance
| Param | Type | Description |
|---|---|---|
| $ | Knifecycle | The Knifecycle instance to set the various services |
stringPick the first header value if exists
Kind: global function
Returns: string - The value if defined.
| Param | Type | Description |
|---|---|---|
| name | string | The header name |
| headers | Object | The headers map |
ArrayPick header values
Kind: global function
Returns: Array - The values in an array.
| Param | Type | Description |
|---|---|---|
| name | string | The header name |
| headers | Object | The headers map |
Promise.<Object>Application monitoring service that simply log stringified contents.
Kind: global function
Returns: Promise.<Object> - A promise of the apm service.
| Param | Type | Description |
|---|---|---|
| services | Object | The services to inject |
| [services.log] | function | A logging function |
Promise.<String>Initialize the BASE_URL service according to the HOST/PORT so that applications fallbacks to that default base URL.
Kind: global function
Returns: Promise.<String> - A promise of a containing the actual host.
| Param | Type | Default | Description |
|---|---|---|---|
| services | Object | The services BASE_URL depends on | |
| services.ENV | Object | The process environment | |
| services.CONFIG | Object | The injected CONFIG value | |
| [services.PROTOCOL] | Object | The injected PROTOCOL value | |
| services.HOST | Object | The injected HOST value | |
| services.PORT | Object | The injected PORT value | |
| [services.log] | Object | noop | An optional logging service |
Promise.<Object>Allow to proxy constants directly by serializing it in the build, saving some computing and increasing boot time of the build.
Kind: global function
Returns: Promise.<Object> - A promise of an object containing the gathered constants.
| Param | Type | Description |
|---|---|---|
| constants | Object | The serializable constants to gather |
Example
import { initBuildConstants } from '@whook/whook';
import { alsoInject } from 'knifecycle';
export default alsoInject(['MY_OWN_CONSTANT'], initBuildConstants);
Promise.<Object>Initialize the COMMANDS service gathering the project commands.
Kind: global function
Returns: Promise.<Object> - A promise of a containing the actual host.
| Param | Type | Default | Description |
|---|---|---|---|
| services | Object | The services COMMANDS depends on | |
| [services.WHOOK_PLUGINS] | Array.<String> | The activated plugins | |
| services.WHOOK_RESOLVED_PLUGINS | Array | The resolved plugins | |
| [services.COMMANDS_DEFINITIONS_OPTIONS] | Object | The options to load the project commands | |
| [services.COMMAND_DEFINITION_FILTER] | Object | A function to filter the project commands per definitions | |
| services.importer | Object | A service allowing to dynamically import ES modules | |
| [services.log] | Object | noop | An optional logging service |
Promise.<Object>Initialize the CRONS_DEFINITIONS service gathering the project crons.
Kind: global function
Returns: Promise.<Object> - A promise of a containing the actual host.
| Param | Type | Default | Description |
|---|---|---|---|
| services | Object | The services CRONS_DEFINITIONS depends on | |
| [services.WHOOK_PLUGINS] | Array.<String> | The activated plugins | |
| services.WHOOK_RESOLVED_PLUGINS | Array | The resolved plugins | |
| [services.CRONS_DEFINITIONS_OPTIONS] | Object | The options to load the project crons | |
| [services.CRON_DEFINITION_FILTER] | Object | A function to filter the project crons per definitions | |
| services.importer | Object | A service allowing to dynamically import ES modules | |
| [services.log] | Object | noop | An optional logging service |
Promise.<function()>Initialize the Whook cron handlers used by the router to know which cron to run for a given cron name.
Kind: global function
Returns: Promise.<function()> - A promise of the CRONS_HANDLERS hash.
| Param | Type | Default | Description |
|---|---|---|---|
| services | Object | The services CRONS_HANDLERS depends on | |
| services.CRONS_WRAPPERS | Array | An optional list of wrappers to inject | |
| [services.log] | Object | noop | An optional logging service |
| services.CRONS_HANDLERS | Object | The rest is a hash of crons handlers mapped by name |
Promise.<function()>A simple passthrough service proxying the CRONS_WRAPPERS.
Kind: global function
Returns: Promise.<function()> - A promise of the CRONS_WRAPPERS hash.
| Param | Type | Default | Description |
|---|---|---|---|
| services | Object | The services CRONS_WRAPPERS depends on | |
| [services.CRONS_WRAPPERS_NAMES] | Array | The global wrappers names to wrap the crons with | |
| [services.log] | Object | noop | An optional logging service |
| services.CRONS_WRAPPERS | Object | The dependencies must all be injected wrappers |
Promise.<String>Initialize the DEFINITIONS service.
Kind: global function
Returns: Promise.<String> - A promise of a containing the actual host.
| Param | Type | Default | Description |
|---|---|---|---|
| services | Object | The services DEFINITIONS depends on | |
| [services.ROUTES_DEFINITIONS] | Object | The API routes modules | |
| [services.COMMANDS_DEFINITIONS] | Object | The commands modules | |
| [services.CRONS_DEFINITIONS] | Object | The crons modules | |
| [services.log] | Object | noop | An optional logging service |
PromiseInitialize an error handler for the HTTP router
Kind: global function
Returns: Promise - A promise of a function to handle errors
| Param | Type | Description |
|---|---|---|
| services | Object | The services the server depends on |
| services.ENV | Object | The app ENV |
| [services.DEBUG_NODE_ENVS] | Array | The environnement that activate debugging (prints stack trace in HTTP errors responses) |
| [services.STRINGIFIERS] | Object | The synchronous body stringifiers |
| [services.ERRORS_DESCRIPTORS] | Object | An hash of the various error descriptors |
| [services.DEFAULT_ERROR_CODE] | Object | A string giving the default error code |
PromiseHandle an HTTP transaction error and map it to a serializable response
Kind: inner method of initErrorHandler
Returns: Promise - A promise resolving when the operation
completes
| Param | Type | Description |
|---|---|---|
| transactionId | String | A raw NodeJS HTTP incoming message |
| responseSpec | Object | The response specification |
| err | YHTTPError | The encountered error |
Promise.<String>Initialize the HOST service from ENV or auto-detection if none specified in ENV
Kind: global function
Returns: Promise.<String> - A promise of a containing the actual host.
| Param | Type | Default | Description |
|---|---|---|---|
| services | Object | The services HOST depends on | |
| [services.ENV] | Object | {} | An optional environment object |
| [services.log] | Object | noop | An optional logging service |
| services.importer | Object | A service allowing to dynamically import ES modules |
PromiseInitialize an HTTP router
Kind: global function
Returns: Promise - A promise of a function to handle HTTP requests.
| Param | Type | Default | Description |
|---|---|---|---|
| services | Object | The services the server depends on | |
| [services.BUFFER_LIMIT] | String | The maximum bufferisation before parsing the request body | |
| [services.BASE_PATH] | String | API base path | |
| services.ROUTES_HANDLERS | Object | The handlers for the operations decribe by the OpenAPI API definition | |
| services.API | Object | The OpenAPI definition of the API | |
| [services.PARSERS] | Object | The synchronous body parsers (for operations that defines a request body schema) | |
| [services.STRINGIFIERS] | Object | The synchronous body stringifiers (for operations that defines a response body schema) | |
| [services.ENCODERS] | Object | A map of encoder stream constructors | |
| [services.DECODERS] | Object | A map of decoder stream constructors | |
| [services.queryParserBuilder] | Object | A query parser builder from OpenAPI parameters | |
| [services.COERCION_OPTIONS] | Object | Options for type coercion of parameters values | |
| [services.log] | function | noop | A logging function |
| services.httpTransaction | function | A function to create a new HTTP transaction |
PromiseHandle an HTTP incoming message
Kind: inner method of initHTTPRouter
Returns: Promise - A promise resolving when the operation
completes
| Param | Type | Description |
|---|---|---|
| req | HTTPRequest | A raw NodeJS HTTP incoming message |
| res | HTTPResponse | A raw NodeJS HTTP response |
Promise.<HTTPServer>Initialize an HTTP server
Kind: global function
Returns: Promise.<HTTPServer> - A promise of an object with a NodeJS HTTP server
in its service property.
| Param | Type | Default | Description |
|---|---|---|---|
| services | Object | The services the server depends on | |
| [services.ENV] | Object | The process environment variables | |
| services.ENV.DESTROY_SOCKETS | String | Whether the server sockets whould be destroyed or if the server should wait while sockets are kept alive | |
| [services.HTTP_SERVER_OPTIONS] | Object | See https://nodejs.org/docs/latest/api/http.html#class-httpserver | |
| services.HOST | String | The server host | |
| services.PORT | Number | The server port | |
| services.httpRouter | function | The function to run with the req/res tuple | |
| [services.log] | function | noop | A logging function |
Promise.<WhookHTTPTransaction>Instantiate the httpTransaction service
Kind: global function
Returns: Promise.<WhookHTTPTransaction> - A promise of the httpTransaction function
| Param | Type | Default | Description |
|---|---|---|---|
| services | Object | The services to inject | |
| [services.TIMEOUT] | Number | 30000 | A number indicating how many ms the transaction should take to complete before being cancelled. |
| [services.TRANSACTIONS] | Object | {} | A hash of every current transactions |
| services.delay | Object | A delaying service | |
| services.obfuscator | Object | A service to avoid logging sensible informations | |
| [services.log] | function | A logging function | |
| [services.apm] | function | An apm function | |
| [services.time] | function | A timing function | |
| [services.uniqueId] | function | A function returning unique identifiers |
Example
import initHTTPTransaction from '@whook/whook';
import { log } from 'node:console';
const httpTransaction = await initHTTPTransaction({
log,
time: Date.now.bind(Date),
});
ArrayCreate a new HTTP transaction
Kind: inner method of initHTTPTransaction
Returns: Array - The normalized request and the HTTP
transaction created in an array.
| Param | Type | Description |
|---|---|---|
| req | HTTPRequest | A raw NodeJS HTTP incoming message |
| res | HTTPResponse | A raw NodeJS HTTP response |
Promise.<function()>An initializer to build a single Whook route handler.
Kind: global function
Returns: Promise.<function()> - A promise of the MAIN_HANDLER service.
| Param | Type | Default | Description |
|---|---|---|---|
| services | Object | The services $autoload depends on | |
| services.WRAPPERS | Array | An optional list of wrappers to inject | |
| services.MAIN_WRAPPER | function | The main route handle wrapper | |
| services.BASE_HANDLER | function | The base handler | |
| [services.log] | function | noop | An optional logging service |
Promise.<Object>Obfuscate sensible informations.
Kind: global function
Returns: Promise.<Object> - A promise of an object containing the gathered constants.
| Param | Type | Description |
|---|---|---|
| services | Object | The service dependend on |
| [services.SHIELD_CHAR] | Object | The char for replacing sensible informations |
| [services.MAX_CLEAR_CHARS] | Object | The maximum clear chars to display |
| [services.MAX_CLEAR_RATIO] | Object | The maximum clear chars ratio to display |
| [services.SENSIBLE_PROPS] | Object | Sensible properties names |
| [services.SENSIBLE_HEADERS] | Object | Sensible headers names |
Example
import { initObfuscator } from '@whook/whook';
import { alsoInject } from 'knifecycle';
import { log } from 'node:console';
const obfuscator = await initObfuscator();
log(obfuscator('my very secret information!));
// my ...on!
Promise.<Number>Initialize the PORT service from ENV or auto-detection if none specified in ENV
Kind: global function
Returns: Promise.<Number> - A promise of a number representing the actual port.
| Param | Type | Default | Description |
|---|---|---|---|
| services | Object | The services PORT depends on | |
| [services.ENV] | Object | {} | An optional environment object |
| [services.log] | Object | noop | An optional logging service |
| services.importer | Object | A service allowing to dynamically import ES modules |
Promise.<Object>Wrap the ENV service in order to filter ENV vars for the build
Kind: global function
Returns: Promise.<Object> - A promise of an object containing the reshaped env vars.
| Param | Type | Default | Description |
|---|---|---|---|
| services | Object | The services ENV depends on | |
| [services.PROXIED_ENV_VARS] | Object | {} | A list of environment variable names to proxy |
| [services.log] | Object | noop | An optional logging service |
Promise.<Object>Initialize the ROUTES_DEFINITIONS service gathering the project routes definitions.
Kind: global function
Returns: Promise.<Object> - A promise of a containing the actual host.
| Param | Type | Default | Description |
|---|---|---|---|
| services | Object | The services ROUTES_DEFINITIONS depends on | |
| [services.WHOOK_PLUGINS] | Array.<String> | The activated plugins | |
| services.WHOOK_RESOLVED_PLUGINS | Array | The resolved plugins | |
| [services.ROUTES_DEFINITIONS_OPTIONS] | Object | The options to load the routes in the file system | |
| [services.ROUTE_DEFINITION_FILTER] | Object | A function to filter the routes per definitions | |
| services.importer | Object | A service allowing to dynamically import ES modules | |
| [services.log] | Object | noop | An optional logging service |
Promise.<function()>Initialize the Whook routes handlers used by the router to know which handler to run for a given route.
Kind: global function
Returns: Promise.<function()> - A promise of the ROUTES_HANDLERS hash.
| Param | Type | Default | Description |
|---|---|---|---|
| services | Object | The services ROUTES_HANDLERS depends on | |
| services.ROUTES_WRAPPERS | Array | An optional list of wrappers to inject | |
| [services.log] | Object | noop | An optional logging service |
| services.ROUTES_HANDLERS | Object | The rest is a hash of routesHandlers mapped by their operation id |
Promise.<function()>A simple passthrough service proxying the ROUTES_WRAPPERS.
Kind: global function
Returns: Promise.<function()> - A promise of the ROUTES_WRAPPERS hash.
| Param | Type | Default | Description |
|---|---|---|---|
| services | Object | The services ROUTES_WRAPPERS depends on | |
| [services.ROUTES_WRAPPERS_NAMES] | Array | The global wrappers names to wrap the routes with | |
| [services.log] | Object | noop | An optional logging service |
| services.ROUTES_WRAPPERS | Object | The dependencies must all be injected wrappers |
Promise.<Number>Initialize the schema validator service for application schemas validation. This central place is aimed to compile schemas once and use them many times.
Kind: global function
Returns: Promise.<Number> - A promise of a schema validators registry
| Param | Type | Default | Description |
|---|---|---|---|
| services | Object | The services it depends on | |
| [services.SCHEMA_VALIDATORS_OPTIONS] | Object | {} | Options for the schema validators registry |
| [services.ENV] | Object | {} | An optional environment object |
| [services.log] | Object | noop | An optional logging service |
| services.API | Object | A valid Open API file |
Promise.<string>Resolves the Whook plugins from their names
Kind: global function
Returns: Promise.<string> - A promise of a number representing the actual port.
| Param | Type | Default | Description |
|---|---|---|---|
| services | Object | The services WHOOK_RESOLVED_PLUGINS depends on | |
| [services.WHOOK_PLUGINS] | Array.<String> | The activated plugins | |
| [services.log] | Object | noop | An optional logging service |
Kind: global typedef
Id of the transaction
Kind: static property of WhookHTTPTransaction
Promise.<Object>Start the transaction
Kind: static property of WhookHTTPTransaction
Returns: Promise.<Object> - A promise to be resolved with the signed token.
| Param | Type | Description |
|---|---|---|
| buildResponse | function | A function that builds a response |
PromiseCatch a transaction error
Kind: static property of WhookHTTPTransaction
Returns: Promise - A promise to be resolved with the signed token.
| Param | Type | Description |
|---|---|---|
| err | Error | A function that builds a response |
Promise.<Object>End the transaction
Kind: static property of WhookHTTPTransaction
Returns: Promise.<Object> - A promise to be resolved with the signed token.
| Param | Type | Description |
|---|---|---|
| response | Object | A response for the transaction |
FAQs
Build strong and efficient REST web services.
The npm package @whook/whook receives a total of 510 weekly downloads. As such, @whook/whook popularity was classified as not popular.
We found that @whook/whook 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 for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Multiple high-impact npm maintainers confirm they have been targeted in the same social engineering campaign that compromised Axios.
Security News
Axios compromise traced to social engineering, showing how attacks on maintainers can bypass controls and expose the broader software supply chain.
Security News
Node.js has paused its bug bounty program after funding ended, removing payouts for vulnerability reports but keeping its security process unchanged.