redis-backed LRU cache
npm install redis-lruA least recently used (LRU) cache backed by Redis, allowing data to be shared by
multiple Node.JS processes. API inspired by node-lru-cache.
``js
var redis = require('redis').createClient(port, host, opts);
var lru = require('redis-lru');
var personCache = lru(redis, 5); // up to 5 items
personCache.set('john', {name: 'John Doe', age: 27})
.then(() => personCache.set('jane', {name: 'Jane Doe', age: 30}))
.then(() => personCache.get('john'))
.then(console.log) // prints {name: 'John Doe', age: 27}
.then(() => personCache.reset()) //clear the cache
var bandCache = lru(redis, {max: 2, namespace: 'bands', maxAge: 15000}); // use a different namespace and set expiration
bandCache.set('beatles', 'john, paul, george, ringo')
.then(() => bandCache.set('zeppelin', 'jimmy, robert, john, bonzo'))
.then(() => bandCache.get('beatles')) // now beatles are the most recently accessed
.then(console.log) // 'john, paul, george, ringo'
.then(() => bandCache.set('floyd', 'david, roger, syd, richard, nick')) // cache full, remove least recently accessed
.then(() => bandCache.get('zeppelin'))
.then(console.log) // null, was evicted from cache
`
Works both with node_redis and ioredis clients.
``
npm install redis-lru
* max: Maximum amount of items the cache can hold. This option is required; if nonamespace
other option is needed, it can be passed directly as the second parameter when creating
the cache.
* : Prefix appended to all keys saved in Redis, to avoid clashes with other applicationsmaxAge
and to allow multiple instances of the cache.
* : Maximum amount of milliseconds the key will be kept in the cache; after that getting/peeking willnull
resolve to . Note that the value will be removed from Redis after maxAge, but the key willcount
be kept in the cache until next time it's accessed (i.e. it will be included in , 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.
All methods return a Promise.
* set(key, value, maxAge): set value for the given key, marking it as the most recently accessed one.maxAge
Keys should be strings, values will be JSON.stringified. The optional overrides for this specific keyget(key)
the global expiration of the cache.
* : resolve to the value stored in the cache for the given key or null if not present.getOrSet(key, fn, maxAge)
If present, the key will be marked as the most recently accessed one.
* : resolve to the value stored in the cache for the given key. If not present,fn
execute , save the result in the cache and return it. fn should be a no args function thatmaxAge
returns a value or a promise. If 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 itsdel(key)
last accessed time.
* : 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.
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:
`js
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')) // accessed twice
.then(() => bandLfu.set('zeppelin', 'jimmy, robert, john, bonzo'))
.then(() => bandLfu.set('floyd', 'david, roger, syd, richard, nick')) // cache full, remove least frequently accessed
.then(() => bandLfu.get('zeppelin'))
.then(console.log) // null, was evicted from cache
``
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.