Skip to content


Subversion checkout URL

You can clone with
Download ZIP
In-memory, Promises/A+, read-through lru-cache
Fetching latest commit...
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Build Status

In-memory, Promises/A+, read-through lru-cache via bluebird


First, instantiate the cache – passing options if necessary.

var BlueLRU = require("bluecache");
var options = {
  max: 500,
  maxAge: 1000 * 60 * 60

var cache = BlueLRU(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 String for the cache key and a Promise-returning function that resolves to a value to store in the cache. The cached value can be of any type.

cache('key', function (_key) {
  console.log("the invoked key => " + _key);  // "the invoked key => key"
  return Promise.resolve('value');
.then(function (_value) {
  console.log("the resolved value => " + _value);  // "the resolved value => value"

Note: the priming function is invoked with the resolved key. Thus, the key can be used to determine the behavior of the priming function without storing the key in higher-level scope.


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 interval); 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


cache(key, primingFunction)

Attempts to get the current value of key from the cache. If the key exists, the "recently-used"-ness of the key is updated and the cached value is returned. If the key does not exist, the primingFunction is executed and the returned Promise resolved to its underlying value before being set in the cache and returned. (To support advanced cases, the key can also be a Promise for a String.)

A rejected promise is returned if either key or primingFunction is missing.


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

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', function (data) {
  console.log('The cache took ' + + ' milliseconds to respond.');


Returns a promise that resolves to undefined after removing all data from the cache.

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.


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

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


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

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


PRs are welcome! For bugs, please include a failing test which passes when your PR is applied.


To run the unit test suite:

npm test

Or, to determine unit test coverage:

npm run coverage
Something went wrong with that request. Please try again.