@AppKu/StashKu

@AppKu/StashKu

v1.0.46

Class

StashKu

The StashKu class provides the ability to work with a variety of storage mediums through a single, standardized, RESTful interface, working much like HTTP - using a request and a response.

StashKu supports middleware which can be configured to pre- and post-process requests and responses.

Constructor

new StashKu(configopt)

Creates a new StashKu instance using the provided configuration settings (which override defaults).

Parameters

Source

Members

engineBaseEngine|Promise.<module:engines/base-engine~BaseEngine>

The currently active storage engine, or the promise to load it. All operations will await the engine if it is a promise.

Type

  • BaseEngine | Promise.<module:engines/base-engine~BaseEngine>

Source

stats

Counter of all requests handled by this instance (or parent instance in the case of a proxy) of stashku.

Source

Methods

asyncstatic

parseDelete(reqObj, modelResolveropt) → {Promise.<module:requests/delete-request~DeleteRequest>}

Attempts to parse (convert) a StashKu request-like object (including http requests) into a DeleteRequest. If the request-like object does not appear to be parsable into the request type, a value of null is returned.

Parameters

  • reqObj *

    The untyped request object.

  • modelResolver ModelNameResolveCallback | Modeling.AnyModelType <optional>

    Callback function that resolves a model name into a model type (constructor/class). Optionally can be a model type.

Returns

  • Promise.<module:requests/delete-request~DeleteRequest>

Source

asyncstatic

parseGet(reqObj, modelResolveropt) → {Promise.<module:requests/get-request~GetRequest>}

Attempts to parse (convert) a StashKu request-like object (including http requests) into a GetRequest. If the request-like object does not appear to be parsable into the request type, a value of null is returned.

Parameters

  • reqObj *

    The untyped request object.

  • modelResolver ModelNameResolveCallback | Modeling.AnyModelType <optional>

    Callback function that resolves a model name into a model type (constructor/class). Optionally can be a model type.

Returns

  • Promise.<module:requests/get-request~GetRequest>

Source

asyncstatic

parseOptions(reqObj, modelResolveropt) → {Promise.<module:requests/options-request~OptionsRequest>}

Attempts to parse (convert) a StashKu request-like object (including http requests) into a OptionsRequest. If the request-like object does not appear to be parsable into the request type, a value of null is returned.

Parameters

  • reqObj *

    The untyped request object.

  • modelResolver ModelNameResolveCallback | Modeling.AnyModelType <optional>

    Callback function that resolves a model name into a model type (constructor/class). Optionally can be a model type.

Returns

  • Promise.<module:requests/options-request~OptionsRequest>

Source

asyncstatic

parsePatch(reqObj, modelResolveropt) → {Promise.<module:requests/patch-request~PatchRequest>}

Attempts to parse (convert) a StashKu request-like object (including http requests) into a PatchRequest. If the request-like object does not appear to be parsable into the request type, a value of null is returned.

Parameters

  • reqObj *

    The untyped request object.

  • modelResolver ModelNameResolveCallback | Modeling.AnyModelType <optional>

    Callback function that resolves a model name into a model type (constructor/class). Optionally can be a model type.

Returns

  • Promise.<module:requests/patch-request~PatchRequest>

Source

asyncstatic

parsePost(reqObj, modelResolveropt) → {Promise.<module:requests/post-request~PostRequest.<InstanceType.<MT>>>}

Attempts to parse (convert) a StashKu request-like object (including http requests) into a PostRequest. If the request-like object does not appear to be parsable into the request type, a value of null is returned.

Parameters

  • reqObj *

    The untyped request object.

  • modelResolver ModelNameResolveCallback | Modeling.AnyModelType | MT <optional>

    Callback function that resolves a model name into a model type (constructor/class). Optionally can be a model type.

Returns

  • Promise.<module:requests/post-request~PostRequest.<InstanceType.<MT>>>

Source

asyncstatic

parsePut(reqObj, modelResolveropt) → {Promise.<module:requests/put-request~PutRequest.<InstanceType.<MT>>>}

Attempts to parse (convert) a StashKu request-like object (including http requests) into a PutRequest. If the request-like object does not appear to be parsable into the request type, a value of null is returned.

Parameters

  • reqObj *

    The untyped request object.

  • modelResolver ModelNameResolveCallback | Modeling.AnyModelType | MT <optional>

    Callback function that resolves a model name into a model type (constructor/class). Optionally can be a model type.

Returns

  • Promise.<module:requests/put-request~PutRequest.<InstanceType.<MT>>>

Source

asyncstatic

requestFromFile(jsonFile, fsOptionsopt, modelNameResolveropt) → {Promise.<(module:requests/delete-request~DeleteRequest|module:requests/get-request~GetRequest|module:requests/patch-request~PatchRequest|module:requests/post-request~PostRequest|module:requests/put-request~PutRequest|module:requests/options-request~OptionsRequest)>}

Reads a request defintion from file and returns an instance of that request.

Parameters

  • jsonFile fs.PathOrFileDescriptor

    The file path to the JSON formatted file defining a single StashKu request.

  • fsOptions Object | String | fs.BufferEncodingOption <optional>

    File encoding options.

  • modelNameResolver ModelNameResolveCallback <optional>

    Callback function that resolves a model name into a model type (constructor/class).

Returns

  • Promise.<(module:requests/delete-request~DeleteRequest|module:requests/get-request~GetRequest|module:requests/patch-request~PatchRequest|module:requests/post-request~PostRequest|module:requests/put-request~PutRequest|module:requests/options-request~OptionsRequest)>

Throws

Error when used on an unsupported platform (browser).

Source

asyncstatic

requestFromObject(reqObj, modelNameResolveropt) → {Promise.<(module:requests/delete-request~DeleteRequest|module:requests/get-request~GetRequest|module:requests/patch-request~PatchRequest|module:requests/post-request~PostRequest|module:requests/put-request~PutRequest|module:requests/options-request~OptionsRequest)>}

Converts a StashKu request-like object (including http requests) into an instance of the appropriate StashKu request. This can be used in conjunction with JSON.stringify(...) and subsequently a JSON.parse(...) of a request.

If the object is null or undefined, a null value is returned.

Parameters

  • reqObj *

    The untyped request object.

  • modelNameResolver ModelNameResolveCallback | Modeling.AnyModelType <optional>

    Callback function that resolves a model name into a model type (constructor/class). Optionally can be a model type.

Deprecated

  • Please switch to `StashKu.parse***` functions. This function will be removed in a later versions.

Returns

  • Promise.<(module:requests/delete-request~DeleteRequest|module:requests/get-request~GetRequest|module:requests/patch-request~PatchRequest|module:requests/post-request~PostRequest|module:requests/put-request~PutRequest|module:requests/options-request~OptionsRequest)>

Throws

  1. Error if the object is missing a method property.

  2. Error if the method property value is invalid.

Source

configure(configopt) → {StashKu}

Configures this StashKu instance with the specified configuration. If a null value is passed, the configuration is cleared and reset to the default.

When the config parameter is undefined (not specified), this function can be awaited. This will await the import and load of the configured StashKu engine. If the engine is already loaded, the function will return.

Parameters

Returns

Throws

Error if the configured storage engine name (config.engine) is not registered with StashKu.

Source

async

delete(request) → {Promise.<module:response~Response.<I>>}

Run a DELETE request to delete any matching objects with the specified template properties and values. This operation will respond with the objects deleted.

Parameters

Returns

  • Promise.<module:response~Response.<I>>

    Returns the data objects from storage that were deleted with the request criteria.

Example

let sk = new StashKu();
...
await sk.patch(r => r
    .from('Runners')
    .where(f => f.and('Gender', f.OP.EQUALS, 'Female'))
);

Throws

Error if the "request" argument is not a callback function or DeleteRequest instance.

Source

async

destroy()

This method safely cleans up resources and should be called after the use of the StashKu instance is complete, such as just before application exit.

Source

async

get(requestopt) → {Promise.<module:response~Response.<I>>}

Run a GET request through StashKu using the configured storage engine.
This operation returns objects from storage that match the GET request criteria.

Parameters

Returns

  • Promise.<module:response~Response.<I>>

    Returns the data objects from storage matching request criteria.

Example

let sk = new StashKu();
...
await sk.get(r => r
    .properties('FirstName', 'LastName')
    .from('Contacts')
    .where(f => f.and('FirstName', f.OP.STARTSWITH, 'Rob'))
    .sort('LastName')
);

Throws

  1. Error if the storage engine fails to return a response.

  2. Error if the storage engine returns an invalid response object.

Source

async

http(httpRequest, modelTypeopt) → {Promise.<module:response~Response.<I>>}

Instructs StashKu to transform a HTTP request into a StashKu request and run it.

Parameters

  • httpRequest Request

    The HTTP request to be transformed and run.

  • modelType Modeling.AnyModelType <optional>

    The model type StashKu can use to discover the proper resource of a request. If this is specified, the resource will always be derived from the model's appropriate resource value. If your StashKu chain includes a model, that model will be used when this argument is not specified.

Returns

  • Promise.<module:response~Response.<I>>

    Returns the data objects from storage matching HTTP request criteria.

Throws

  1. Error when StashKu failed to transform the HTTP request into a valid StashKu request.

  2. Error when used on an unsupported platform (browser).

Source

async

middlerun(state, request, response)

Runs configured middleware callbacks matching the current state and request method.

Parameters

  • state String

    The name of the state of where in the RESTful process the callback is being made, either:

    • "request": Indicates the callback was made before the request has handed off to the engine.
    • "response": Indicates the callback was made before the engine's response has been considered.
    • "done": Indicates the callback was made after the engine has completed the response and the action is about to complete (StashKu hands off the storage engine response to the caller).
  • request GetRequest | PostRequest | PutRequest | PatchRequest | DeleteRequest | OptionsRequest

    The request object being specified.

  • response Promise.<module:response~Response>

    The response object (null if not prepared yet).

Source

model(modelType) → {module:stashku~StashKu.<MT, InstanceType.<MT>>}

Attaches a model to StashKu operations through a new returned (proxy) StashKu instance. The model is attached only to the returned proxying instance. This allows the use of the model within the request callback methods as the second argument (model), and the resulting Response data to be instances of the model.

Parameters

  • modelType MT

    The model "class" or constructor function.

Returns

Example

let sk = new StashKu();
...
//the model object will be exposed as the "m" argument in the callback.
await sk.model(PersonModel).get((r, m) => r...);
await sk.model(PersonModel).post((r, m) => r...);
await sk.model(PersonModel).put((r, m) => r...);
await sk.model(PersonModel).patch((r, m) => r...);
await sk.model(PersonModel).delete((r, m) => r...);

Throws

  1. Error if the modelType argument missing or falsey.

  2. Error if the modelType argument is not a class or constructor function.

Source

async

options(request) → {Promise.<module:response~Response.<I>>}

Run an OPTIONS request which returns a dynamically constructed model type which defines how StashKu can interact with the target (from) resource.

Parameters

Returns

  • Promise.<module:response~Response.<I>>

    Returns a response with a single data object- the dynamically created model configuration.

Example

let sk = new StashKu();
...
await sk.options(r => r
    .from('Runners')
);

Throws

Error if the "request" argument is not a callback function or OptionsRequest instance.

Source

async

patch(request) → {Promise.<module:response~Response.<I>>}

Run a PATCH request to update any matching objects with the specified template properties and values. This operation will respond with the objects updated.

Parameters

Returns

  • Promise.<module:response~Response.<I>>

    Returns a response with the total number of the objects affected in storage. No data objects are typically returned with this request.

Example

let sk = new StashKu();
...
await sk.patch(r => r
    .template({
        walking: true,
        date_walked: new Date()
    })
    .to('Runners')
    .where(f => f.and('Gender', f.OP.EQUALS, 'Female'))
);

Throws

  1. Error if the storage engine fails to return a response.

  2. Error if the storage engine returns an invalid response object.

Source

async

post(request) → {Promise.<module:response~Response.<I>>}

Run a POST request to create objects in a target resource using the StashKu configured storage engine. This operation returns an array of the objects that were created.

Parameters

Returns

  • Promise.<module:response~Response.<I>>

    Returns the data objects from storage that were created with the request criteria.

Example

let sk = new StashKu();
...
let person1 = { FirstName: 'Robert', LastName: 'Yolo' };
let person2 = { FirstName: 'Suzy', LastName: 'CraftyMine' };
await sk.post(r => r
    .objects(person1, person2)
    .to('Contacts')
);

Throws

  1. Error if the storage engine fails to return a response.

  2. Error if the storage engine returns an invalid response object.

Source

async

put(request) → {Promise.<module:response~Response.<I>>}

Run a PUT request to update objects in the target resource using the StashKu configured storage engine. This operation will respond with the objects updated.

Parameters

Returns

  • Promise.<module:response~Response.<I>>

    Returns the data objects from storage that were updated with the request criteria. This may not exactly match the objects requested to be updated, as some may have been deleted from storage or some may not match the key criteria.

Example

let sk = new StashKu();
...
let person1 = { ID: 1, FirstName: 'Robert', LastName: 'Yolo' };
let person2 = { ID: 2, FirstName: 'Suzy', LastName: 'CraftyMine' };
await sk.put(r => r
    .objects(person1, person2)
    .pk('ID')
    .to('Contacts')
);

Throws

  1. Error if the storage engine fails to return a response.

  2. Error if the storage engine returns an invalid response object.

Source