Bluecache NPM | npm.io

bluecache

Read-through, in-memory, least recently used (lru) cache

Use

First, instantiate the cache – passing options if necessary.

const Bluecache = require('bluecache');
const options = {
  max: 500,
  maxAge: '1h'
};

const cache = Bluecache(options);

Traditional cache "getting" and "setting" takes place within a single call, promoting functional use. The cache instance is a Promise-returning function which takes two parameters: a cache key and a priming value.

cache(Promise.resolve('dinosaur'), (key) => {
  console.log(`the invoked key was: ${key}`); // "the invoked key was: dinosaur"
  return Promise.resolve('rar');
})
.then((value) => {
  console.log(`the resolved value is: ${value}`); // "the resolved value is: rar"
});

Options

Options are passed to lru-cache at instantiation:

max: The maximum size of the cache, checked by applying the length function to all values in the cache
maxAge: Maximum age in ms (or a valid ms expression); lazily enforced; expired keys will return undefined
length: Function called to calculate the length of stored items (e.g. function (n) { return n.length; }); defaults to function (n) { return 1; }
dispose: Function called on items immediately before they are dropped from the cache; called with parameters (key, value)
stale: Allow the cache to return a stale (expired via maxAge) value before it is deleted

In addition, the following options are specific to bluecache:

pruneInterval: Interval at which the cache will pro-actively remove stale entries; by default stale items remain in memory until the next attempted read

Note: the underlying cache stores a memo for the promised value and a default length of 1 while the value is being resolved. After the value is first resolved, the length is updated to reflect the desired options.length passed at instantiation. (In short, peak cache "max" may exceed the specified max while values are being resolved.)

API

cache(`key`, `primingValue`)

Attempts to get the current value of key from the cache. If the key was previously used, the "recently-used"-ness of the key is updated and the cached value is returned. If the key does not exist, the primingValue is determined and the underlying cache value is set. If the primingValue is a function, it is invoked with the resolved key (resolved as a String) as its single argument.

Both key and primingValue can be a Boolean, Number, String, Symbol, Object, a Function that returns one of these primitives, or a Promise that resolves to one of these primitives.

By immediately caching and returning a Promise, the cache avoids a stampede for the target primingValue. However, a stampede may occur for a key because it resolves on each cache call. If you plan to asynchronously resolve the key, consider caching the key function as well.

A rejected Promise is returned if key is empty (null or undefined) or if there is an error resolving the primingValue.

cache#del(`key`)

Returns a Promise that resolves to undefined after deleting key from the cache.

cache#reset()

Clears the cache entirely, throwing away all values. Returns a Promise that resolves to null after the cache has been reset.

cache#on(`eventName`, `eventHandler`)

eventName is a string, corresponding to a supported event. eventHandler is a function which responds to the data provided by the target event.

cache.on('cache:hit', (data) => {
  console.log(`The cache took ${data.ms} milliseconds to respond to key: ${data.key}.`);
});

Emitted events

The cache instance is also an event emitter which provides an on method against which the implementing application can listen for the below events.

`cache:hit`

{
  'key': <String>,
  'ms': <Number:Integer:Milliseconds>
}

Note: ms is milliseconds elapsed between cache invocation and final resolution of the cached value.

`cache:miss`

{
  'key': <String>,
  'ms': <Number:Integer:Milliseconds>
}

Note: ms is milliseconds elapsed between cache invocation and final resolution of the priming value.

Changelog

v3 → v4

breaking Dropped Bluebird in favor of native promises
breaking Errored values (and rejected promises) are no longer held in cache
breaking Rewritten to use ES6 (ES2015, Node.js 4+) language features

v2 → v3

breaking Removed support for interval Object options in favor of ms expression
minor Added support for automatic pruning via pruneInterval option

v1 → v2

breaking Addressed thundering herd problem identified by @ketilovre and others (a minor api change but the side-effects in underlying _lrucache are considered breaking)
breaking Removed #reset instance method which was abused in practice; use a key-specific #del instead
minor Generalized key and priming values to any primitive, promise, or function
patch Upgraded dependencies
patch Reorganized test suite