@lgslabs/bits-memory-crud NPM

BITS Memory CRUD

The implementation of in-memory CRUD for BITS. This package extends the functionality provided in bits-core. All items in the collection are expected to be properly-formatted JSON objects with at least an id field.

Use

Importing

npm install @lgslabs/bits-memory-crud

const {CrudService, CrudManager, CrudMessenger, CrudRouter, CrudApi} = require('@lgslabs/bits-memory-crud');

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.

`load`

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

load({messageCenter, tag, scopes, readScopes, writeScopes, filter, 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
filter Boolean True if the Messenger should filter CRUD events, false otherwise
routePath String The path to use for the router (optional)
routerFilepath String The path to the Router class to use (optional)
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)
...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 creates an instance of the base implementation of the CRUD manager. If the subsystem needs additional functionality, it is recommended to override this function.

createManager()

Returns Promise resolving to request or rejecting to error

`createMessenger`

Called in the Service's load function to create the messenger. By default, it creates an instance of the base implementation of the CRUD messenger. If the subsystem needs additional functionality, it is recommended to override this function.

createMessenger()

Returns Promise resolving to request or rejecting to error

Manager

The Manager is responsible for performing any operations related to the subsystem. It has default implementations for all CRUD operations. 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.

`_createId`

Helper function to create an ID for the item to be added. By default, IDs are strings.

_createId(item)

item Object The item to be created
Returns Promise resolving to the ID or rejecting to error

`validate`

Helper function to perform any necessary validation on the item. By default, the function ensures the item is a non-null object.

validate(item)

item Object The item to validate
Returns Promise resolving to the validated item or rejecting to error

`create`

Creates the provided item(s). The function allows a single item OR an array of items to be passed.

create(item)

item Object|Array The item(s) to add to the collection
Returns Promise resolving to the created item(s) or rejecting to error
Emits created with an array of the created item(s)

`_create`

Helper function to create a single item.

_create(item)

item Object The item to create
Returns Promise resolving to the item to add to the collection or rejecting to error

`update`

Applies the provided update to the specified ID(s). NOTE This function does NOT perform a deep update.

update(id, update)

id String|Array the ID(s) of the item(s) to apply the update
update Object the update to apply
Returns Promise resolving to the updated item(s) or rejecting to error
Emits updated with an array of the updated item(s)

`_update`

Helper function to update a single item

_update(id, update)

id String the ID of the item to apply the update
update Object the update to apply
Returns Promise resolving to the updated item or rejecting to error

`delete`

Removes the item(s) holding the specified ID(s).

delete(id)

id String|Array the ID(s) of the item(s) to remove
Returns Promise resolving to the deleted item(s) or rejecting to error
Emits deleted with an array of the deleted item(s)

`_delete`

Helper function to delete a single item

_delete(id)

id String the ID of the item to remove
Returns Promise resolving to the deleted item or rejecting to error

`upsert`

Upserts the item(s).

upsert(item)

item Object|Array the ID(s) of the item(s) to remove
Returns Promise resolving to the deleted item(s) or rejecting to error
Emits created with an array of the created item(s), if any
Emits updated with an array of the updated item(s), if any

`_upsert`

Helper function to upsert a single item

_upsert(item)

item Object the item to upsert
Returns Promise resolving to an object containing item and event (created| updated), or rejecting to error

`_upsertFilter`

Helper function that attempts to retrieve an existing item matching some criterion. By default, this function matches on the id property.

_upsertFilter(item)

item Object the item to upsert
Returns Promise resolving to an object, or rejecting to error

`list`

Retrieves the entire collection of items

list(query, options)

query Object unused
options Object unused
Returns Promise resolving to an array of items or rejecting to error

`count`

Retrieves the number of items in the collection.

count(query)

query Object unused in implementation
Returns Promise resolving to the item count or rejecting to error

`get`

Retrieves a specific item from the collection

get(id)

id String the ID of the item to retrieve
Returns Promise resolving to the specified item or rejecting to error

Messenger

The Messenger is responsible for interacting with the MessageCenter for request handling, event subscriptions, and publishing events. It has default implementations for all CRUD requests and events, including event filtering if options.filter is true. 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({filter, ...options})

filter Boolean True if the Messenger should filter CRUD events, false otherwise
options Object The rest of the options passed into the Service's load function
Returns Promise resolving to request or rejecting to error

`sanitize`

Removes any sensitive information from the object.

sanitize(item)

item Object the item to sanitize
Returns Promise resolving to the sanitized item or rejecting to error

`filterCreated`

Filters the created item(s) based on the subscribed user

filterCreated(user, items)

user Object the user to use for filtering conditions
items Array the items for filtering
Returns Promise resolving to the filtered items or rejecting to error

`filterUpdated`

Filters the updated item(s) based on the subscribed user

filterUpdated(user, items)

user Object the user to use for filtering conditions
items Array the items for filtering
Returns Promise resolving to the filtered items or rejecting to error

`filterDeleted`

Filters the deleted item(s) based on the subscribed user

filterDeleted(user, items)

user Object the user to use for filtering conditions
items Array the items for filtering
Returns Promise resolving to the filtered items or rejecting to error

`_create`

Handles incoming create requests, forwarding them to the manager and sanitizing the result.

_create(metadata, item)

metadata Object information created by the MessageCenter about the request
item Object|Array the item(s) to create
Returns Promise resolving to the created items, after being sanitized, or rejecting to error

`_update`

Handles incoming update requests, forwarding them to the manager and sanitizing the result.

_update(metadata, ids, update)

metadata Object information created by the MessageCenter about the request
id String|Array the ID(s) of the item(s) to apply the update
update Object the update to apply
Returns Promise resolving to the updated items, after being sanitized, or rejecting to error

`_delete`

Handles incoming delete requests, forwarding them to the manager and sanitizing the result.

_delete(metadata, id)

metadata Object information created by the MessageCenter about the request
id String|Array the ID(s) of the item(s) to remove
Returns Promise resolving to the deleted items, after being sanitized, or rejecting to error

`_list`

Handles incoming list requests, forwarding them to the manager and sanitizing the result.

_list(metadata, query, options)

metadata Object information updated by the MessageCenter about the request
query Object unused
options Object unused
Returns Promise resolving to the items in the collection, after being sanitized, or rejecting to error

`_count`

Handles incoming count requests, forwarding them to the manager.

_count(metadata, query)

metadata Object information updated by the MessageCenter about the request
query Object unused
Returns Promise resolving to the number of items in the collection or rejecting to error

`_get`

Handles incoming get requests, forwarding them to the manager and sanitizing the result.

_get(metadata, id)

metadata Object information created by the MessageCenter about the request
id String the ID of the item to retrieve
Returns Promise resolving to the deleted items, after being sanitized, or rejecting to error

`_created`

Handles the created event emitted from the manager. If options.filter was true, it sends the created event with null scopes, then with read scopes to the subscribed user(s)

_created(item)

items Object|Array the created item(s)

`_updated`

Handles the updated event emitted from the manager. If options.filter was true, it sends the updated event with null scopes, then with read scopes to the subscribed user(s)

_updated(item)

items Object|Array the updated item(s)

`_deleted`

Handles the deleted event emitted from the manager. If options.filter was true, it sends the deleted event with null scopes, then with read scopes to the subscribed user(s)

_deleted(item)

items Object|Array the deleted item(s)

Router

The Router is responsible for creating RESTful endpoints and handling any requests made. It has default endpoints for all CRUD operations. 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.

Endpoints

Create POST <routePath>/create
Update POST <routePath>/update
Delete POST <routePath>/delete
List GET <routePath>/list
Get GET <routePath>/get
Count GET <routePath>/count

`_create`

Calls create on the subsystem's API with the item(s) provided in the request's body.

_create(req, res, next)

req express.Request the request object
res express.Response the response object
next Function signals to express the continue down the middleware stack

`_update`

Calls update on the subsystem's API with the ID(s) and update provided in the request's body.

_update(req, res, next)

req express.Request the request object
res express.Response the response object
next Function signals to express the continue down the middleware stack

`_delete`

Calls delete on the subsystem's API with the ID(s) provided in the request's body.

_delete(req, res, next)

req express.Request the request object
res express.Response the response object
next Function signals to express the continue down the middleware stack

`_list`

Calls list on the subsystem's API with the query and options provided as query parameters, if any.

_list(req, res, next)

req express.Request the request object
res express.Response the response object
next Function signals to express the continue down the middleware stack

`_get`

Calls get on the subsystem's API with the ID provided as a query parameter, if any.

_get(req, res, next)

req express.Request the request object
res express.Response the response object
next Function signals to express the continue down the middleware stack

`_count`

Calls count on the subsystem's API with the query provided as a query parameter, if any.

_count(req, res, next)

req express.Request the request object
res express.Response the response object
next Function signals to express the continue down the middleware stack

API

The API allows other modules to call the functions of the current subsystem. It has default implementations for all CRUD operations, as well as adding and removing CRUD event listeners. 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.