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.
Table of Contents
Features
- Made with Typescript and compatible with ESModules
- 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 vitest.
Installation
pnpm install cache-manager
Usage Examples
Single Store
import { caching } from 'cache-manager';
const memoryCache = await caching('memory', {
max: 100,
ttl: 10 * 1000 ,
});
const ttl = 5 * 1000;
await memoryCache.set('foo', 'bar', ttl);
console.log(await memoryCache.get('foo'));
await memoryCache.del('foo');
console.log(await memoryCache.get('foo'));
const getUser = (id: string) => new Promise.resolve({ id: id, name: 'Bob' });
const userId = 123;
const key = 'user_' + userId;
console.log(await memoryCache.wrap(key, () => getUser(userId), ttl));
See unit tests in test/caching.test.ts
for more information.
Example setting/getting several keys with mset() and mget()
await memoryCache.store.mset(
[
['foo', 'bar'],
['foo2', 'bar2'],
],
ttl,
);
console.log(await memoryCache.store.mget('foo', 'foo2'));
await memoryCache.store.mdel('foo', 'foo2');
Custom Stores
You can use your own custom store by creating one with the same API as the built-in memory stores.
Create single cache store synchronously
As caching()
requires async functionality to resolve some stores, this is not well-suited to use for default function/constructor parameters etc.
If you need to create a cache store synchronously, you can instead use createCache()
:
import { createCache, memoryStore } from 'node-cache-manager';
const memoryCache = createCache(memoryStore(), {
max: 100,
ttl: 10 * 1000 ,
});
function myService(cache = createCache(memoryStore())) {}
const DEFAULT_CACHE = createCache(memoryStore(), { ttl: 60 * 1000 });
class MyService {
constructor(private cache = DEFAULT_CACHE) {}
}
Multi-Store
import { multiCaching } from 'cache-manager';
const multiCache = multiCaching([memoryCache, someOtherCache]);
const userId2 = 456;
const key2 = 'user_' + userId;
const ttl = 5;
await multiCache.set('foo2', 'bar2', ttl);
console.log(await multiCache.get('foo2'));
await multiCache.del('foo2');
await multiCache.mset(
[
['foo', 'bar'],
['foo2', 'bar2'],
],
ttl
);
console.log(await multiCache.mget('key', 'key2'));
await multiCache.mdel('foo', 'foo2');
See unit tests in test/multi-caching.test.ts
for more information.
Cache Manager Options
The caching
function accepts an options object as the second parameter. The following options are available:
- ttl: The time to live in milliseconds. This is the maximum amount of time that an item can be in the cache before it is removed.
- refreshThreshold: discussed in details below.
- isCacheable: a function to determine whether the value is cacheable or not.
- onBackgroundRefreshError: a function to handle errors that occur during background refresh.
import { caching } from 'cache-manager';
const memoryCache = await caching('memory', {
max: 100,
ttl: 10 * 1000 ,
shouldCloneBeforeSet: false,
});
When creating a memory store, you also get these addition options:
- max: The maximum number of items that can be stored in the cache. If the cache is full, the least recently used item is removed.
- shouldCloneBeforeSet: If true, the value will be cloned before being set in the cache. This is set to
true
by default.
Refresh cache keys in background
Both the caching
and multicaching
modules support a mechanism to refresh expiring cache keys in background when using the wrap
function.
This is done by adding a refreshThreshold
attribute while creating the caching store or passing it to the wrap
function.
If refreshThreshold
is set and after retrieving a value from cache the TTL will be checked.
If the remaining TTL is less than refreshThreshold
, the system will update the value asynchronously,
following same rules as standard fetching. In the meantime, the system will return the old value until expiration.
NOTES:
- In case of multicaching, the store that will be checked for refresh is the one where the key will be found first (highest priority).
- If the threshold is low and the worker function is slow, the key may expire and you may encounter a racing condition with updating values.
- The background refresh mechanism currently does not support providing multiple keys to
wrap
function. - If no
ttl
is set for the key, the refresh mechanism will not be triggered. For redis, the ttl
is set to -1 by default.
For example, pass the refreshThreshold to caching
like this:
const memoryCache = await caching('memory', {
max: 100,
ttl: 10 * 1000 ,
refreshThreshold: 3 * 1000 ,
onBackgroundRefreshError: (error) => { }
});
When a value will be retrieved from Redis with a TTL minor than 3sec, the value will be updated in the background.
Error Handling
multiCaching
now does not throw errors by default. Instead, all errors are evented through the error
event. Here is an example on how to use it:
const multicache = await multiCaching([memoryCache, someOtherCache]);
multicache.on('error', (error) => {
console.error('Cache error:', error);
});
Store Engines
Official and updated to last version
Third party
Contribute
If you would like to contribute to the project, please read how to contribute here CONTRIBUTING.md.
License
cache-manager is licensed under the MIT license.