@lgslabs/bits-core NPM

BITS Core

The base implementation of classes that make up a BITS subsystem.

Use

Importing

npm install @lgslabs/bits-core

const {Service, Manager, Messenger, Router, Api} = require('@lgslabs/bits-core');

Service

The Service is responsible for creating, loading, and unloading the manager, messenger, router (if desired), a public API (if desired), and any resources the subsystem may need.

`ApiExport`

Static getter for obtaining the Symbols for the apiExport option

Service.ApiExport

Returns Object Key/Value pairs for the GLOBAL and RESOURCE export types

`load`

Loads the Service, thereby creating and loading the other subsystem components with the provided options

load({messageCenter, tag, scopes, readScopes, writeSCopes, routePath, routerFilepath, apiExport, apiData, ...args})

messageCenter MessageCenter The MessageCenter to use
tag String The tag to use for requests/events
scopes Array The scopes to use on requests/events
readScopes Array The scopes for read-type requests/events
writeScopes Array The scopes for write-type requests
routePath String The path to use for the router (optional)
routerFilepath String The path to the Router class to use (optional)
routeAuthenticated Boolean The route should be authenticated. Default true.
routeParams Object The optional params object to pass in the router resource value.
apiExport Symbol(API_EXPORT) How to export the API. This must be a value from API_EXPORT object in order to export
apiData Object The data to supply for export ({name, filepath} for GLOBAL, {topic, value} for RESOURCE)
resourceTopics Array The array of topics for which to create and manage ResourceManagers
...args Any number of additional key/value pairs
Returns Promise resolving to request or rejecting to error

`createManager`

Called in the Service's load function to create the manager. By default, it uses the Manager class included in this package. It is recommended to override this function.

createManager()

Returns Promise resolving to request or rejecting to error

`loadManager`

Called in the Service's load function to load the manager. By default, it passes the options argument to the supplied Manager's load function. It is unusual to override this function.

loadManager(options)

options Object The options passed into the Service's load function
Returns Promise resolving to request or rejecting to error

`unloadManager`

Called in the Service's unload function to unload the manager. By default, it passes the options argument to the supplied Manager's unload function. It is unusual to override this function.

messageCenter MessageCenter The MessageCenter to use
Returns Promise resolving to request or rejecting to error

`createMessenger`

Called in the Service's load function to create the manager. By default, it uses the Messenger class included in this package. It is recommended to override this function.

createMessenger()

Returns Promise resolving to request or rejecting to error

`loadMessenger`

Called in the Service's load function to load the messenger. By default, it passes the options argument to the supplied Messenger's load function. It is unusual to override this function.

loadMessener({manager, ...options})

manager Manager The manager object created in the createManager function
...options Object The rest of the options passed into the Service's load function
Returns Promise resolving to request or rejecting to error

`unloadMessenger`

Called in the Service's unload function to unload the messenger. By default, it passes the options argument to the supplied Messenger's unload function. It is unusual to override this function.

unloadMessenger({messageCenter})

messageCenter MessageCenter The MessageCenter to use
Returns Promise resolving to request or rejecting to error

`createAndLoadRouterResource`

Called in the Service's load function to create and load the Router resource to be used by the subsystem. This function will only be called if the routePath option is valid. It is unusual to override this function and recommened to override _createRouterResource if further control over the Router resource creation is needed.

createAndLoadRouterResource(options)

options Object The options passed into the Service's load function
Returns Promise resolving to request or rejecting to error

`unloadRouterResource`

Called in the Service's unload function to unload the Router resource, if one exists.

unloadRouterResource({messageCenter})

messageCenter MessageCenter The MessageCenter to use
Returns Promise resolving to request or rejecting to error

`exportApi`

Called in the Service's load function to export the API as specified in the arguments. This function will not be called if apiExport is not valid.

exportApi(options)

options Object The options passed into the Service's load function
Returns Promise resolving to request or rejecting to error

`_exportApiGlobal`

Called in the Service's exportApi function to export the API on the global property.

_exportApiGlobal({apiData, messageCenter})

apiData Object The apiData object passed into the load function. Must contain both name and filepath key/values
messageCenter MessageCenter The MessageCenter to use
Returns Promise resolving to request or rejecting to error

`_exportApiResource`

Called in the Service's exportApi function to export the API as a LocalResource.

_exportApiResource({apiData, messageCenter})

apiData Object The apiData object passed into the load function. Must contain both topic and value key/values
messageCenter MessageCenter The MessageCenter to use
Returns Promise resolving to request or rejecting to error

`unloadApi`

Called in the Service's unload function to remove the API from public view, if applicable.

unloadApi({messageCenter})

messageCenter MessageCenter The MessageCenter to use
Returns Promise resolving to request or rejecting to error

`createAndLoadResourceManagers`

Called in the Service's load function to create and load ResourceManagers for provided topics, if any. The add and remove listeners are also added with bound instances of _onResourceAdded and _onResourceRemoved, respectively.

createAndLoadResourceManagers({messageCenter, resourceTopics})

messageCenter MessageCenter The MessageCenter to use
resourceTopics Array The Array of topics passed to options, if any
Returns Promise resolving to request or rejecting to error

`unloadResourceManagers`

Called in the Service's unload function to remove listeners and unload any ResourceManagers

unloadResourceManagers({messageCenter})

messageCenter MessageCenter The MessageCenter to use
Returns Promise resolving to request or rejecting to error

`_onResourceAdded`

Abstract function bound with this and the messageCenter for the purpose of handling added resources. This must be overridden if resourceTopics are passed in the options object.

_onResourceAdded(messageCenter, resource)

messageCenter MessageCenter The MessageCenter to use
resource LocalResource The added resource
Returns Promise resolving to request or rejecting to error

`_onResourceRemoved`

Abstract function bound with this and the messageCenter for the purpose of handling removed resources. This must be overridden if resourceTopics are passed in the options object.

_onResourceRemoved(messageCenter, resource)

messageCenter MessageCenter The MessageCenter to use
resource LocalResource The added resource
Returns Promise resolving to request or rejecting to error

`_nullifyProperties`

Called in the Service's constructor and unload functions as a hook to allow for properties to be nulled out.

_nullifyProperties()

void

Manager

The Manager is responsible for performing any operations related to the subsystem. The manager is an EventEmitter to allow communication with the Messenger. To change the Manager class being used, override the createManager function in the Service to create and return the desired Manager implementation. The loadManager and unloadManager functions can be overridden in the event more customization is required.

`load`

Loads the Manager. This is where all initialization should be done, and how the Manager should receive any additional parameters.

load(options)

options Object The options passed into the Service's load function
Returns Promise resolving to request or rejecting to error

`unload

Unloads the Manager. This is where all teardown should be done.

unload({messageCenter})

messageCenter MessageCenter The MessageCenter to use
Returns Promise resolving to request or rejecting to error

`_nullifyProperties`

Called in the Manager's constructor and unload functions as a hook to allow for properties to be nullified.

_nullifyProperties()

void

`_sendRequest`

Allows the Manager to send a request through the MessageCenter without acting directly on it.

NOTE: This should NOT be used in lieu of a standard API (e.g. don't hardcode the event to avoid using a subsystem's API). This pattern is designed to allow Promisified requests to be made with a system's Just In Time Strategic Non-Deferred Yagi (JITSNDY) Events.

_sendRequest({event, metadata, args})

event String the request name to send
metadata Object any metadata to send with the request (e.g. scopes). If not provided, the request will be sent with null scopes
args Array the arguments to send with the request.
Returns Promise resolving the request or rejecting with an error

Messenger

The Messenger is responsible for interacting with the MessageCenter for request handling, event subscriptions, and publishing events. To change the Messenger class being used, override the createMessenger function in the Service to create and return the desired Messenger implementation. The loadMessenger and unloadMessenger functions can be overridden in the event more customization is required.

`load`

Loads the Messenger. This is where all initialization should be done, and how the Messenger should receive any additional parameters.

load(options)

options Object The options passed into the Service's load function
Returns Promise resolving to request or rejecting to error

`unload`

Unloads the Messenger. This is where all teardown should be done.

unload({messageCenter})

messageCenter MessageCenter The MessageCenter to use
Returns Promise resolving to request or rejecting to error

`_sendRequest`

Sends the specified request when the Manager emits the send-request-promise event.

_sendRequest({event, metadata, args, resolve, reject})

event String the request name to send
metadata Object any metadata to send with the request (e.g. scopes). If not provided, the request will be sent with null scopes
args Array the arguments to send with the request.
resolve Function the resolve callback from a Promise.
reject Function the reject callback from a Promise.
Returns Promise resolving the request or rejecting with an error

Router

The Router is responsible for creating RESTful endpoints and handling any requests made. The Router is not intended to be created explicitly, but intended to be loaded as a resource for BaseServer to utilize. BaseServer will create an instance and add the middleware on the path provided. A Router is not required and will only be created if the routePath option is passed to Service.load.

`constructor`

constructor(options)

options Object The options passed into the Service's load function

`_addResources`

Called from the constructor to allow the extender to add any additional resources

_addResources(options)

options Object The options passed into the constructor
Returns void

`_createRouter`

Called from the constructor to allow the extender to override the default router implementation

_createRouter(options)

options Object The options passed into the constructor
Returns void

`_loadApi`

Allows the extender to create the API object for the Router to use during requests

_loadApi(req, res, next)

req request The request object
res response The response object
next function The function to call when done loading the API
Returns void

`_useBodyParser`

Creates and adds the body parser config to the Router

_useBodyParser(options)

options Object The options passed into the constructor
Returns void

`_addRoutes`

Allows the extender to override or add additional routes and middleware. By default, _loadApi is the only middleware added in this function.

_addRoutes(options)

Returns void

`addRoute`

Mounts middleware at the given path. By default, the middleware is added with the GET method.

addRoute({method, path, middleware})

method String The HTTP method to use
path String The path on which to mount the middleware
middleware Function|Array The middleware(s) to be invoked
Returns void

`use`

Mounts middleware at the given path. By default, the middleware is mounted at /.

use({path, middleware})

path String The path on which to mount the middleware
middleware Function|Array The middleware(s) to be invoked
Returns void

`get`

Mounts middleware at the given path with the GET method.

get({path, middleware})

path String The path on which to mount the middleware
middleware Function|Array The middleware(s) to be invoked
Returns void

`post`

Mounts middleware at the given path with the POST method.

post({path, middleware})

path String The path on which to mount the middleware
middleware Function|Array The middleware(s) to be invoked
Returns void

`put`

Mounts middleware at the given path with the PUT method.

put({path, middleware})

path String The path on which to mount the middleware
middleware Function|Array The middleware(s) to be invoked
Returns void

`delete`

Mounts middleware at the given path with the DELETE method.

delete({path, middleware})

path String The path on which to mount the middleware
middleware Function|Array The middleware(s) to be invoked
Returns void

`_addErrorHandlers`

Allows the extender to override or add additional error handlers.

_addErrorHandlers(options)

Returns void

`_prepareResult`

Allows the extender to override or add to the default result contract.

_prepareResult({result, messages, errors})

result *** The result returned from the operation, if successful
messages Array Messages returned from the operation
errors Array Errors returned from the operation, if unsuccessful
Returns void

API

The API allows other modules to call the functions of the current subsystem. Not all functions in the Manager need to be exposed in the API. An API is not required and will not be created unless both apiExport and apiData are supplied and valid.