2.2.0 • Published 5 years ago

@lgslabs/bits-core v2.2.0

Weekly downloads
-
License
Apache-2.0
Repository
github
Last release
5 years ago

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.

constructor

constructor(options)
  • options Object The options passed into the Service's load function
2.2.0

5 years ago

2.1.0

6 years ago

2.0.0

6 years ago

1.3.0

6 years ago

1.2.0

6 years ago

1.1.2

6 years ago

1.1.1

6 years ago

1.1.0

6 years ago

1.0.2

6 years ago

1.0.1

6 years ago

1.0.0

6 years ago