redis lru cache
A least recently used (LRU) cache backed by Redis, allowing data to be shared by
multiple Node.JS processes. API inspired by node-lru-cache.
var redis = require('redis').createClient(port, host, opts);
var lru = require('redis-lru');
var personCache = lru(redis, 5);
personCache.set('john', {name: 'John Doe', age: 27})
.then(() => personCache.set('jane', {name: 'Jane Doe', age: 30}))
.then(() => personCache.get('john'))
.then(console.log)
.then(() => personCache.reset())
var bandCache = lru(redis, {max: 2, namespace: 'bands', maxAge: 15000});
bandCache.set('beatles', 'john, paul, george, ringo')
.then(() => bandCache.set('zeppelin', 'jimmy, robert, john, bonzo'))
.then(() => bandCache.get('beatles'))
.then(console.log)
.then(() => bandCache.set('floyd', 'david, roger, syd, richard, nick'))
.then(() => bandCache.get('zeppelin'))
.then(console.log)
Works both with node_redis and ioredis clients.
Installation
npm install redis-lru
Options
max
: Maximum amount of items the cache can hold. This option is required; if no
other option is needed, it can be passed directly as the second parameter when creating
the cache.namespace
: Prefix appended to all keys saved in Redis, to avoid clashes with other applications
and to allow multiple instances of the cache.maxAge
: Maximum amount of milliseconds the key will be kept in the cache; after that getting/peeking will
resolve to null
. Note that the value will be removed from Redis after maxAge
, but the key will
be kept in the cache until next time it's accessed (i.e. it will be included in count
, keys
, etc., although not in has
.).score
: function to customize the score used to order the elements in the cache. Defaults to () => new Date().getTime()
increment
: if true
, on each access the result of the score
function is added to the previous one,
rather than replacing it.
API
All methods return a Promise.
set(key, value, maxAge)
: set value for the given key, marking it as the most recently accessed one.
Keys should be strings, values will be JSON.stringified. The optional maxAge
overrides for this specific key
the global expiration of the cache.get(key)
: resolve to the value stored in the cache for the given key or null
if not present.
If present, the key will be marked as the most recently accessed one.getOrSet(key, fn, maxAge)
: resolve to the value stored in the cache for the given key. If not present,
execute fn
, save the result in the cache and return it. fn
should be a no args function that
returns a value or a promise. If maxAge
is passed, it will be used only if the key is not already in the cache.peek(key)
: resolve to the value stored in the cache for the given key, without changing its
last accessed time.del(key)
: removes the item from the cache.reset()
: empties the cache.has(key)
: resolves to true if the given key is present in the cache.keys()
: resolves to an array of keys in the cache, sorted from most to least recently accessed.values()
: resolves to an array of values in the cache, sorted from most to least recently accessed.count()
: resolves to the number of items currently in the cache.
Using as a LFU cache
By using a custom score
function and the increment
option, one can turn the cache
into a least frequently used (LFU), where the items that have been accessed more times
(rather than most recently) are preserved:
var redis = require('redis').createClient(port, host, opts);
var lru = require('redis-lru');
var bandLfu = lru(redis, {max: 2, score: () => 1, increment: true});
bandLfu.set('beatles', 'john, paul, george, ringo')
.then(() => bandLfu.get('beatles'))
.then(() => bandLfu.set('zeppelin', 'jimmy, robert, john, bonzo'))
.then(() => bandLfu.set('floyd', 'david, roger, syd, richard, nick'))
.then(() => bandLfu.get('zeppelin'))
.then(console.log)
Implementation
Each item in the cache is stored as a regular key/value in Redis. Additionally,
a ZSET is used to keep an
index of the keys sorted by last-accessed timestamp.
Requires Redis 3.0.2 or greater, since it uses the
XX option of ZADD.