node-cache-manager
Flexible NodeJS cache module
A cache module for nodejs that allows easy wrapping of functions in cache,
tiered caches, and a consistent interface.
Features
- Easy way to wrap any function in cache.
- Tiered caches -- data gets stored in each cache and fetched from the highest
priority cache(s) first.
- Use any cache you want, as long as it has the same API.
- 100% test coverage via mocha,
istanbul, and sinon.
Express.js Example
See the Express.js cache-manager example app to see how to use
node-cache-manager
in your applications.
Installation
npm install cache-manager
Store Engines
Overview
First, it includes a wrap
function that lets you wrap any function in cache.
(Note, this was inspired by node-caching.)
This is probably the feature you're looking for. As an example, where you might have to do this:
function getCachedUser(id, cb) {
memoryCache.get(id, function (err, result) {
if (err) { return cb(err); }
if (result) {
return cb(null, result);
}
getUser(id, function (err, result) {
if (err) { return cb(err); }
memoryCache.set(id, result);
cb(null, result);
});
});
}
... you can instead use the wrap
function:
function getCachedUser(id, cb) {
memoryCache.wrap(id, function (cacheCallback) {
getUser(id, cacheCallback);
}, {ttl: ttl}, cb);
}
Second, node-cache-manager features a built-in memory cache (using node-lru-cache),
with the standard functions you'd expect in most caches:
set(key, val, {ttl: ttl}, cb) // * see note below
get(key, cb)
del(key, cb)
mset(key1, val1, key2, val2, {ttl: ttl}, cb) // set several keys at once
mget(key1, key2, key3, cb) // get several keys at once
// * Note that depending on the underlying store, you may be able to pass the
// ttl as the third param, like this:
set(key, val, ttl, cb)
// ... or pass no ttl at all:
set(key, val, cb)
Third, node-cache-manager lets you set up a tiered cache strategy. This may be of
limited use in most cases, but imagine a scenario where you expect tons of
traffic, and don't want to hit your primary cache (like Redis) for every request.
You decide to store the most commonly-requested data in an in-memory cache,
perhaps with a very short timeout and/or a small data size limit. But you
still want to store the data in Redis for backup, and for the requests that
aren't as common as the ones you want to store in memory. This is something
node-cache-manager handles easily and transparently.
Fourth, it allows you to get and set multiple keys at once for caching store that support it. This means that when getting muliple keys it will go through the different caches starting from the highest priority one (see multi store below) and merge the values it finds at each level.
Usage Examples
See examples below and in the examples directory. See examples/redis_example
for an example of how to implement a
Redis cache store with connection pooling.
Single Store
var cacheManager = require('cache-manager');
var memoryCache = cacheManager.caching({store: 'memory', max: 100, ttl: 10});
var ttl = 5;
memoryCache.set('foo', 'bar', {ttl: ttl}, function(err) {
if (err) { throw err; }
memoryCache.get('foo', function(err, result) {
console.log(result);
memoryCache.del('foo', function(err) {});
});
});
function getUser(id, cb) {
setTimeout(function () {
console.log("Returning user from slow database.");
cb(null, {id: id, name: 'Bob'});
}, 100);
}
var userId = 123;
var key = 'user_' + userId;
memoryCache.wrap(key, function (cb) {
getUser(userId, cb);
}, {ttl: ttl}, function (err, user) {
console.log(user);
memoryCache.wrap(key, function (cb) {
getUser(userId, cb);
}, function (err, user) {
console.log(user);
});
});
The ttl
can also be computed dynamically by passing in a function. E.g.,
var opts = {
ttl: function(user) {
if (user.id === 1) {
return 0.1;
} else {
return 0.5;
}
}
};
memoryCache.wrap(key, function(cb) {
getUser(userId, cb);
}, opts, function(err, user) {
console.log(user);
}
You can get several keys at once. E.g.
var key1 = 'user_1';
var key2 = 'user_1';
memoryCache.wrap(key1, key2, function (cb) {
getManyUser([key1, key2], cb);
}, function (err, users) {
console.log(users[0]);
console.log(users[1]);
});
Example setting/getting several keys with mset() and mget()
memoryCache.mset('foo', 'bar', 'foo2', 'bar2' {ttl: ttl}, function(err) {
if (err) { throw err; }
memoryCache.mget('foo', 'foo2', function(err, result) {
console.log(result);
memoryCache.del('foo', 'foo2', function(err) {});
memoryCache.del(['foo', 'foo2'], function(err) {});
});
});
Example Using Promises
memoryCache.wrap(key, function() {
return getUserPromise(userId);
})
.then(function(user) {
console.log('User:', user);
});
If you are using a Node version that does not include native promises, you can
specify your promise dependency in the options passed to the cache module.
E.g.,
var Promise = require('es6-promise').Promise;
cache = caching({store: store, promiseDependency: Promise});
Example Using async/await
try {
let user = await memoryCache.wrap(key, function() {
return getUserPromise(userId);
});
} catch (err) {
}
Hint: should wrap await
call with try
- catch
to handle promise
error.
Example Express App Usage
(Also see the Express.js cache-manager example app).
function respond(res, err, data) {
if (err) {
res.json(500, err);
} else {
res.json(200, data);
}
}
app.get('/foo/bar', function(req, res) {
var cacheKey = 'foo-bar:' + JSON.stringify(req.query);
var ttl = 10;
memoryCache.wrap(cacheKey, function(cacheCallback) {
DB.find(req.query, cacheCallback);
}, {ttl: ttl}, function(err, result) {
respond(res, err, result);
});
});
Custom Stores
You can use your own custom store by creating one with the same API as the
built-in memory stores (such as a redis or memcached store). To use your own store just pass
in an instance of it.
E.g.,
var myStore = require('your-homemade-store');
var cache = cacheManager.caching({store: myStore});
Multi-Store
var multiCache = cacheManager.multiCaching([memoryCache, someOtherCache]);
userId2 = 456;
key2 = 'user_' + userId;
ttl = 5;
multiCache.set('foo2', 'bar2', {ttl: ttl}, function(err) {
if (err) { throw err; }
multiCache.get('foo2', function(err, result) {
console.log(result);
multiCache.del('foo2');
});
});
function getTTL(data, store) {
if (store === 'redis') {
return 6000;
}
return 3000;
}
multiCache.mset('key', 'value', 'key2', 'value2', {ttl: getTTL}, function(err) {
if (err) { throw err; }
multiCache.mget('key', 'key2', function(err, result) {
console.log(result[0]);
console.log(result[1]);
multiCache.del('key', 'key2');
multiCache.del(['key', 'key2']);
});
});
multiCache.wrap(key2, function (cb) {
getUser(userId2, cb);
}, {ttl: ttl}, function (err, user) {
console.log(user);
multiCache.wrap(key2, function (cb) {
getUser(userId2, cb);
}, function (err, user) {
console.log(user);
});
});
multiCache.wrap('key1', 'key2', function (cb) {
getManyUser(['key1', 'key2'], cb);
}, {ttl: ttl}, function (err, users) {
console.log(users[0]);
console.log(users[1]);
});
Specifying What to Cache in wrap
Function
Both the caching
and multicaching
modules allow you to pass in a callback function named
isCacheableValue
which is called by the wrap
function with every value returned from cache or from the wrapped function.
This lets you specify which values should and should not be cached by wrap
. If the function returns true, it will be
stored in cache. By default the caches cache everything except undefined
.
NOTE: The set
functions in caching
and multicaching
do not use isCacheableValue
.
For example, if you don't want to cache false
and null
, you can pass in a function like this:
var isCacheableValue = function(value) {
return value !== null && value !== false && value !== undefined;
};
Then pass it to caching
like this:
var memoryCache = cacheManager.caching({store: 'memory', isCacheableValue: isCacheableValue});
And pass it to multicaching
like this:
var multiCache = cacheManager.multiCaching([memoryCache, someOtherCache], {
isCacheableValue: isCacheableValue
});
Docs
To generate JSDOC 3 documentation:
make docs
Tests
To run tests, first run:
npm install -d
Run the tests and JShint:
make
Contribute
If you would like to contribute to the project, please fork it and send us a pull request. Please add tests
for any new features or bug fixes. Also run make
before submitting the pull request.
License
node-cache-manager is licensed under the MIT license.