API

Usage

npm install --save @feathers-plus/batch-loader
// JS
const BatchLoader = require('@feathers-plus/batch-loader');
const { getResultsByKey, getUniqueKeys } = BatchLoader;
const usersLoader = new BatchLoader(async (keys, context) => {
const usersRecords = await users.find({ query: { id: { $in: getUniqueKeys(keys) } } });
return getResultsByKey(keys, usersRecords, user => user.id, '')
},
{ context: {} }
);
const user = await usersLoader.load(key);

May be used on the client.

class BatchLoader( batchLoadFunc [, options] )

Create a new batch-loader given a batch loading function and options.

Argument Type Default Description
batchLoadFunc Function See Batch Function.
options Object Options.
options Argument Type Default Description
batch Boolean true Set to false to disable batching, invoking batchLoadFunc with a single load key.
cache Boolean true Set to false to disable memoization caching, creating a new Promise and new key in the batchLoadFunc for every load of the same key.
cacheKeyFn Function key => key Produces cache key for a given load key. Useful when keys are objects and two objects should be considered equivalent.
cacheMap Object new Map() Instance of Map (or an object with a similar API) to be used as cache. See below.
context Object null A context object to pass into batchLoadFunc as its second argument.
maxBatchSize Number Infinity Limits the number of keys when calling batchLoadFunc.
Name Type Description
batchLoader Object BatchLoader instance.

You can consider wrapping npm’s lru on the browser.

static BatchLoader.getUniqueKeys( keys )

Returns the unique elements in an array.

Argument Type Default Description
keys Array< String / Number > The keys. May contain duplicates.
Name Type Description
keys Array< String / Number > The keys with no duplicates.

static BatchLoader.getResultsByKey( keys, records, getRecordKeyFunc, type [, options] )

Reorganizes the records from the service call into the result expected from the batch function.

Argument Type Default Description
keys Array< String / Number> An array of key elements, which the value the batch loader function will use to find the records requested.
records Array< Object > An array of records which, in total, resolve all the keys.
getRecordKeyFunc Function See below.
type String The type of value the batch loader must return for each key.
options Object Options.
type Value Description
'' An optional single record.
'!' A required single record.
'[]' A required array including 0, 1 or more records.
options Argument Type Default Description
defaultElem {null / []} null The value to return for a key having no record(s).
onError Function (i, msg) => {} Handler for detected errors, e.g. (i, msg) => { throw new Error(msg, 'on element', i); }
Name Type Description
results Array< Object > The result for each key. results[i] is the result for keys[i].

batchLoader.load( key )

Loads a key, returning a Promise for the value represented by that key.

Argument Type Default Description
key String Number Object Array The key the batch-loader uses to find the result(s).
Name Type Description
promise Promise< Object > Resolves to the result(s).

batchLoader.loadMany( keys )

Loads multiple keys, promising a arrays of values.

Argument Type Default Description
keys Array< String / Number / Object / Array> The keys the batch-loader will return result(s) for.
Name Type Description
promise Promise[ Array< Object > ] Resolves to an array of result(s). promise[i] is the result for keys[i].

batchLoader.clear( key )

Clears the value at key from the cache, if it exists.

Argument Type Default Description
key String Number Object Array The key to remove from the cache.

The key is matches using strict equality. This is particularly important for Object and Array keys.

batchLoader.clearAll()

Clears the entire cache.

batchLoader.prime( key, value )

Primes the cache with the provided key and value.

Argument Type Default Description
key String Number Object Array The key in the cache for the record.
record Object The value for the key.

What’s New

The details are at Changelog.

Feb. 2018