@lgslabs/bits-core v2.2.0
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, load
ing, and unload
ing 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
andRESOURCE
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 usetag
String The tag to use for requests/eventsscopes
Array The scopes to use on requests/eventsreadScopes
Array The scopes for read-type requests/eventswriteScopes
Array The scopes for write-type requestsroutePath
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. Defaulttrue
.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 exportapiData
Object The data to supply for export ({name, filepath}
forGLOBAL
,{topic, value}
forRESOURCE
)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'sload
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 Themanager
object created in thecreateManager
function...options
Object The rest of the options passed into the Service'sload
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'sload
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'sload
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 TheapiData
object passed into theload
function. Must contain bothname
andfilepath
key/valuesmessageCenter
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 TheapiData
object passed into theload
function. Must contain bothtopic
andvalue
key/valuesmessageCenter
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 ResourceManager
s 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 useresourceTopics
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 ResourceManager
s
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 useresource
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 useresource
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'sload
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 sendmetadata
Object any metadata to send with the request (e.g. scopes). If not provided, the request will be sent withnull
scopesargs
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'sload
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 sendmetadata
Object any metadata to send with the request (e.g. scopes). If not provided, the request will be sent withnull
scopesargs
Array the arguments to send with the request.resolve
Function theresolve
callback from a Promise.reject
Function thereject
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'sload
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 usepath
String The path on which to mount the middlewaremiddleware
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 middlewaremiddleware
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 middlewaremiddleware
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 middlewaremiddleware
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 middlewaremiddleware
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 middlewaremiddleware
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 successfulmessages
Array Messages returned from the operationerrors
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.
constructor
constructor(options)
options
Object The options passed into the Service'sload
function