@lgslabs/bits-memory-kv NPM

BITS Memory Key/Value

The implementation of an in-memory key/value store for BITS. This package extends the functionality provided in bits-core. Keys and values can be of any type.

Use

Importing

npm install @lgslabs/bits-memory-kv

const {KeyValueService, KeyValueManager, KeyValueMessenger, KeyValueApi} = require('@lgslabs/bits-memory-kv');

Service

The Service is responsible for creating, loading, and unloading the manager, messenger, 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, 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
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 Key/Value 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 manager. By default, it creates an instance of the base implementation of the Key/Value 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 Key/Value 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.

`set`

Sets the specified key to have the specified value.

set({key, value})

key ? the key to use
value ? the value to associate
Returns Promise resolving to undefined or rejecting to error
Emits set with an object containing the key and value

`get`

Retrieves the value associated with the specified key

get({key})

key ? the key
defaultValue ? the value to return if the key isn't found
Returns Promise resolving to the value or rejecting to error

`has`

Determines whether the specified key exists in the collection

has({key})

key ? the key
Returns Promise resolving to true if the key exists, false otherwise

`setDefault`

Sets the specified key to the given value if a value doesn't already exist

setDefault({key, value})

key ? the key
value ? the value
Returns Promise resolving to undefined, the result of the operation is that has will now return true

`delete`

Deletes the specified key and its value, if it exists

delete({key})

key ? the key
Returns Promise resolving to undefined or rejecting to error
Emits deleted with an object containing the key

`clear`

Clears the entire collection

clear()

Returns Promise resolving to undefined
Emits cleared with no arguments

`keys`

Retrieves all keys in the collection

keys()

Returns Promise resolving to an array of the keys

`values`

Retrieves all values in the collection

values()

Returns Promise resolving to an array of the values

`_initializeDefaults`

A hook provided to initialize default values on load.

_initializeDefaults()

Returns Promise resolving to undefined

Messenger

The Messenger is responsible for interacting with the MessageCenter for request handling, event subscriptions, and publishing events. It has default implementations for all Key/Value requests and 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.

`_set`

Handles incoming set requests, forwarding them to the manager.

_set(metadata, {key, value})

metadata Object information created by the MessageCenter about the request
key ? the key
value ? the value
Returns Promise resolving to undefined or rejecting to error

`_get`

Handles incoming get requests, forwarding them to the manager.

_get(metadata, {key})

metadata Object information created by the MessageCenter about the request
key ? the key
Returns Promise resolving to value or rejecting to error

`_has`

Handles incoming has requests, forwarding them to the manager.

_has(metadata, {key})

metadata Object information created by the MessageCenter about the request
key ? the key
Returns Promise resolving to true if the key exists, false otherwise

`_delete`

Handles incoming delete requests, forwarding them to the manager.

_delete(metadata, {key})

metadata Object information created by the MessageCenter about the request
key ? the key
Returns Promise resolving to undefined or rejecting to error if the key doesn't exist

`_keys`

Handles incoming keys requests, forwarding them to the manager.

_keys(metadata)

metadata Object information created by the MessageCenter about the request
Returns Promise resolving to an array of the keys

`_values`

Handles incoming values requests, forwarding them to the manager.

_values(metadata)

metadata Object information created by the MessageCenter about the request
Returns Promise resolving to an array of the values

`_onSet`

Handles the set event emitted from the manager, sending the * set event through the MessageCenter.

_onSet({key, value})

key ? the key
value ? the value

`_onDeleted`

Handles the deleted event emitted from the manager, sending the * deleted event through the MessageCenter.

_onDeleted({key})

key ? the key

`_onCleared`

Handles the cleared event emitted from the manager, sending the * cleared event through the MessageCenter.

_onCleared()

API

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