bluecache
v4.1.3
Published
Read-through, in-memory, least recently used (lru) cache
Downloads
3,056
Maintainers
Readme
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 cachemaxAge
: Maximum age in ms (or a valid ms expression); lazily enforced; expired keys will returnundefined
length
: Function called to calculate the length of stored items (e.g.function (n) { return n.length; }
); defaults tofunction (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 viamaxAge
) 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
Contribute
PRs are welcome! For bugs, please include a failing test which passes when your PR is applied.
Thanks @ismriv!
Tests
To run the unit test suite:
npm test
Or, to determine unit test coverage:
npm run coverage
This project maintains 100% coverage of statements, branches, and functions.