@cacheable/node-cache
Table of Contents
- Node-Cache
- Table of Contents
- Getting Started
- Basic Usage
- NodeCache Performance
- NodeCache API
constructor(options?: NodeCacheOptions)
set(key: string | number, value: any, ttl?: number): boolean
mset(data: Array
): boolean get
(key: string | number): T | undefined mget
(keys: Array ): Record take
(key: string | number): T | undefined del(key: string | number | Array
): number mdel(keys: Array
): number ttl(key: string | number, ttl?: number): boolean
getTtl(key: string | number): number | undefined
has(key: string | number): boolean
keys(): string[]
getStats(): NodeCacheStats
flushAll(): void
flushStats(): void
on(event: string, callback: Function): void
- NodeCacheStore
- How to Contribute
- License and Copyright
Node-Cache
Simple and Maintained fast Node.js caching
@cacheable/node-cache
is compatible with the node-cache package with regular maintenance and additional functionality (async/await and storage adapters). The only thing not implemented is the enableLegacyCallbacks
option and functions. If you need them we are happy to take a PR to add them.
- Fully Compatible with
node-cache
using{NodeCache}
- Faster than the original
node-cache
package 🚀 - Async/Await functionality with
{NodeCacheStore}
- Storage Adapters via Keyv with
{NodeCacheStore}
- Maintained and Updated Regularly! 🎉
Table of Contents
- Getting Started
- Basic Usage
- NodeCache Performance
- NodeCache API
constructor(options?: NodeCacheOptions)
set(key: string | number, value: any, ttl?: number): boolean
mset(data: Array
): boolean get
(key: string | number): T | undefined mget
(keys: Array ): Record take
(key: string | number): T | undefined del(key: string | number | Array
): number mdel(keys: Array
): number ttl(key: string | number, ttl?: number): boolean
getTtl(key: string | number): number | undefined
has(key: string | number): boolean
keys(): string[]
getStats(): NodeCacheStats
flushAll(): void
flushStats(): void
on(event: string, callback: Function): void
- NodeCacheStore
- How to Contribute
- License and Copyright
Getting Started
npm install @cacheable/node-cache --save
Basic Usage
import NodeCache from '@cacheable/node-cache';
const cache = new NodeCache();
cache.set('foo', 'bar');
cache.get('foo'); // 'bar'
cache.set('foo', 'bar', 10); // 10 seconds
cache.del('foo'); // true
cache.set('bar', 'baz', '35m'); // 35 minutes using shorthand
The NodeCache
is not the default export, so you need to import it like this:
import {NodeCache} from '@cacheable/node-cache';
const cache = new NodeCache();
cache.set('foo', 'bar');
cache.get('foo'); // 'bar'
NodeCache Performance
The performance is comparable if not faster to the original node-cache
package, but with additional features and improvements.
name | summary | ops/sec | time/op | margin | samples |
---|---|---|---|---|---|
Cacheable NodeCache - set / get | 🥇 | 117K | 9µs | ±1.01% | 111K |
Node Cache - set / get | -4.6% | 112K | 9µs | ±1.31% | 106K |
NodeCache API
constructor(options?: NodeCacheOptions)
Create a new cache instance. You can pass in options to set the configuration:
export type NodeCacheOptions = {
stdTTL?: number; // The standard ttl as number in seconds for every generated cache element. 0 = unlimited. If string, it will be parsed as shorthand and default to milliseconds if it is a number as a string.
checkperiod?: number; // Default is 600, 0 means no periodic check
useClones?: boolean; // Default is true
deleteOnExpire?: boolean; // Default is true, if false it will keep the key and not delete during an interval check and the value on get() will be undefined
maxKeys?: number; // Default is -1 (unlimited). If this is set it will throw and error if you try to set more keys than the max.
};
When initializing the cache you can pass in the options to set the configuration like the example below where we set the stdTTL
to 10 seconds and checkperiod
to 5 seconds.:
const cache = new NodeCache({stdTTL: 10, checkperiod: 5});
When setting deleteOnExpire
to true
it will delete the key when it expires. If you set it to false
it will keep the key but the value on get()
will be undefined
. You can manage the key with on('expired')
event.
const cache = new NodeCache({deleteOnExpire: false});
cache.on('expired', (key, value) => {
console.log(`Key ${key} has expired with value ${value}`);
});
set(key: string | number, value: any, ttl?: number): boolean
Set a key value pair with an optional ttl (in seconds). Will return true on success. If the ttl is not set it will default to 0 (no ttl).
cache.set('foo', 'bar', 10); // true
mset(data: Array): boolean
Set multiple key value pairs at once. This will take an array of objects with the key, value, and optional ttl.
cache.mset([{key: 'foo', value: 'bar', ttl: 10}, {key: 'bar', value: 'baz'}]); // true
the NodeCacheItem
is defined as:
export type NodeCacheItem = {
key: string;
value: any;
ttl?: number;
};
get(key: string | number): T | undefined
Get a value from the cache by key. If the key does not exist it will return undefined
.
cache.get('foo'); // 'bar'
mget(keys: Array): Record
Get multiple values from the cache by keys. This will return an object with the keys and values.
const obj = { my: 'value', my2: 'value2' };
const obj2 = { special: 'value3', life: 'value4' };
cache.set('my', obj);
cache.set('my2', obj2);
cache.mget(['my', 'my2']); // { my: { my: 'value', my2: 'value2' }, my2: { special: 'value3', life: 'value4' } }
take(key: string | number): T | undefined
Get a value from the cache by key and delete it. If the key does not exist it will return undefined
.
cache.set('foo', 'bar');
cache.take('foo'); // 'bar'
cache.get('foo'); // undefined
del(key: string | number | Array): number
Delete a key from the cache. Will return the number of deleted entries and never fail. You can also pass in an array of keys to delete multiple keys. All examples assume that you have initialized the cache like const cache = new NodeCache();
.
cache.del('foo'); // true
passing in an array of keys:
cache.del(['foo', 'bar']); // true
mdel(keys: Array): number
Delete multiple keys from the cache. Will return the number of deleted entries and never fail.
cache.mdel(['foo', 'bar']); // true
ttl(key: string | number, ttl?: number): boolean
Redefine the ttl of a key. Returns true if the key has been found and changed. Otherwise returns false. If the ttl-argument isn't passed the default-TTL will be used.
cache.ttl('foo', 10); // true
getTtl(key: string | number): number | undefined
Get the ttl expiration from Date.now()
of a key. If the key does not exist it will return undefined
.
cache.getTtl('foo'); // 1725993344859
has(key: string | number): boolean
Check if a key exists in the cache.
cache.set('foo', 'bar');
cache.has('foo'); // true
keys(): string[]
Get all keys from the cache.
await cache.keys(); // ['foo', 'bar']
getStats(): NodeCacheStats
Get the stats of the cache.
cache.getStats(); // {hits: 1, misses: 1, keys: 1, ksize: 2, vsize: 3}
flushAll(): void
Flush the cache. Will remove all keys and reset the stats.
cache.flushAll();
await cache.keys(); // []
cache.getStats(); // {hits: 0, misses: 0, keys: 0, ksize: 0, vsize: 0}
flushStats(): void
Flush the stats. Will reset the stats but keep the keys.
await cache.set('foo', 'bar');
cache.flushStats();
cache.getStats(); // {hits: 0, misses: 0, keys: 0, ksize: 0, vsize: 0}
await cache.keys(); // ['foo']
on(event: string, callback: Function): void
Listen to events. Here are the events that you can listen to:
set
- when a key is set and it will pass in thekey
andvalue
.expired
- when a key is expired and it will pass in thekey
andvalue
.flush
- when the cache is flushedflush_stats
- when the stats are flusheddel
- when a key is deleted and it will pass in thekey
andvalue
.
cache.on('set', (key, value) => {
console.log(`Key ${key} has been set with value ${value}`);
});
NodeCacheStore
NodeCacheStore
has a similar API to NodeCache
but it is using async / await
as it uses the Keyv
storage adapters under the hood. This means that you can use all the storage adapters that are available in Keyv
and it will work seamlessly with the NodeCacheStore
. To learn more about the Keyv
storage adapters you can check out the Keyv documentation.
import {NodeCacheStore} from '@cacheable/node-cache';
const cache = new NodeCacheStore();
await cache.set('foo', 'bar');
await cache.get('foo'); // 'bar'
Here is an example of how to use the NodeCacheStore
with a primary and secondary storage adapter:
import {NodeStorageCache} from '@cacheable/node-cache';
import {Keyv} from 'keyv';
import {KeyvRedis} from '@keyv/redis';
const primary = new Keyv(); // In-memory storage as primary
const secondary = new Keyv({store: new KeyvRedis('redis://user:pass@localhost:6379')});
const cache = new NodeStorageCache({primary, secondary});
// with storage you have the same functionality as the NodeCache but will be using async/await
await cache.set('foo', 'bar');
await cache.get('foo'); // 'bar'
// if you call getStats() this will now only be for the single instance of the adapter as it is in memory
cache.getStats(); // {hits: 1, misses: 1, keys: 1, ksize: 2, vsize: 3}
When initializing the cache you can pass in the options below:
export type NodeCacheStoreOptions = {
ttl?: number; // The standard ttl as number in milliseconds for every generated cache element. 0 = unlimited
primary?: Keyv; // The primary storage adapter
secondary?: Keyv; // The secondary storage adapter
maxKeys?: number; // Default is 0 (unlimited). If this is set it will throw and error if you try to set more keys than the max.
stats?: boolean; // Default is true, if this is set to false it will not track stats
};
Note: the ttl
is now in milliseconds and not seconds like stdTTL
in NodeCache
. You can learn more about using shorthand also in the cacheable documentation as it is fully supported. Here is an example:
const cache = new NodeCacheStore({ttl: 60000 }); // 1 minute as it defaults to milliseconds
await cache.set('foo', 'bar', '1h'); // 1 hour
await cache.set('longfoo', 'bar', '1d'); // 1 day
NodeCacheStore API
set(key: string | number, value: any, ttl?: number): Promise
- Set a key value pair with an optional ttl (in milliseconds). Will return true on success. If the ttl is not set it will default to 0 (no ttl)mset(data: Array
- Set multiple key value pairs at once): Promise get
- Get a value from the cache by key(key: string | number): Promise mget(keys: Array
- Get multiple values from the cache by keys): Promise > take
- Get a value from the cache by key and delete it(key: string | number): Promise del(key: string | number): Promise
- Delete a keymdel(keys: Array
- Delete multiple keys): Promise clear(): Promise
- Clear the cachesetTtl(key: string | number, ttl: number): Promise
- Set the ttl of a keydisconnect(): Promise
- Disconnect the storage adaptersstats
:NodeCacheStats
- Get the stats of the cachettl
:number
|string
- The standard ttl as number in seconds for every generated cache element.< 0
orundefined
= unlimitedprimary
:Keyv
- The primary storage adaptersecondary
:Keyv
- The secondary storage adaptermaxKeys
:number
- If this is set it will throw and error if you try to set more keys than the max
How to Contribute
You can contribute by forking the repo and submitting a pull request. Please make sure to add tests and update the documentation. To learn more about how to contribute go to our main README https://github.com/jaredwray/cacheable. This will talk about how to Open a Pull Request
, Ask a Question
, or Post an Issue
.