node-caching

A node internal caching module

Install

$ npm install --save node-caching

Usage

const NodeCaching = require('node-caching')

const nodeCache = new NodeCaching()

nodeCache.set('name', 'Bu Kinoshita')
// => true

nodeCache.get('name')
// => 'Bu Kinoshita'

nodecache decaffeinated

API

new NodeCaching([options])

options

Type: object

stdTTL

Type: number Default: 0

The standard ttl as number in seconds for every generated cache element. 0 = unlimited

checkperiod

Type: number Default: 600

The period in seconds, as a number, used for the automatic delete check interval. 0 = no periodic check

errorOnMissing

Type: boolean Default: false

En/disable throwing or passing an error to the callback if attempting to .get a missing or expired value.

useClones

Type: boolean Default: true

En/disable cloning of variables. If true you'll get a copy of the cached variable. If false you'll save and get just the reference.

Note: true is recommended, because it'll behave like a server-based caching. You should set false if you want to save mutable objects or other complex types with mutability involved and wanted.

Methods

.set(key, value, [ttl], [callback])

Sets a key value pair. It is possible to define a ttl (in seconds). Returns a boolean.

key

Type: string Required

Name of the key to be saved.

value

Type: string||object||number Required

Value of the key to be saved.

ttl

Type: number Optional

The standard ttl as number in seconds for every generated cache element.

callback

Type: function Optional

Callback is optional. You can also use synchronous syntax.

Example:

const NodeCaching = require('node-caching')

const nodeCache = new NodeCaching()

nodeCache.set('name', 'Bu Kinoshita', 10000)
// => true

Note: If the key expires based on it's ttl it will be deleted entirely from the internal data object.

.get(key, [callback])

Gets a saved value from cache. Returns an object or a string or a number

key

Type: string Required

Name of the key to be saved.

callback

Type: function Optional

Callback is optional. You can also use synchronous syntax.

Example:

const NodeCaching = require('node-caching')

const nodeCache = new NodeCaching()

nodeCache.get('name')
// => 'Bu Kinoshita'

.mget([key1, key2, ...], [callback])

Gets multiple saved values from cache. Returns an object

key

Type: string Required

Name of the key to be saved.

callback

Type: function Optional

Callback is optional. You can also use synchronous syntax.

Example:

const NodeCaching = require('node-caching')

const nodeCache = new NodeCaching()

nodeCache.mget(['name', 'age'])
// => { name: 'Bu Kinoshita', age: 22 }

.del([key1, key2, ...], [callback])

Delete a key. Returns a number

key

Type: string Required

Name of the key to be saved.

callback

Type: function Optional

Callback is optional. You can also use synchronous syntax.

Example:

const NodeCaching = require('node-caching')

const nodeCache = new NodeCaching()

nodeCache.del('name')
// => 1

nodeCache.del(['name', 'age'])
// => 2

.ttl(key, ttl, [callback])

Redefine the ttl of a key. Returns a boolean

key

Type: string Required

Name of the key to be saved.

ttl

Type: number Optional

The standard ttl as number in seconds for every generated cache element. If the ttl-argument isn't passed the default-TTL will be used. The key will be deleted when passing in a ttl < 0.

callback

Type: function Optional

Callback is optional. You can also use synchronous syntax.

Example:

const NodeCaching = require('node-caching')

const nodeCache = new NodeCaching()

nodeCache.ttl('name', 100)
// => true

.getTtl(key, [callback])

Receive the ttl of a key. Returns:

• undefined if the key does not exist
• 0 if this key has no ttl
• timestamp in ms until the key expires

key

Type: string Required

Name of the key to be saved.

callback

Type: function Optional

Callback is optional. You can also use synchronous syntax.

Example:

const NodeCaching = require('node-caching')

const nodeCache = new NodeCaching()

nodeCache.getTtl('name')
// => 1456000600000

.keys([callback])

Get all existing keys. Returns an array

callback

Type: function Optional

Callback is optional. You can also use synchronous syntax.

Example:

const NodeCaching = require('node-caching')

const nodeCache = new NodeCaching()

nodeCache.keys()
// => ['name', 'age', ...]

.getStats()

Get statistics. Returns an object

Example:

const NodeCaching = require('node-caching')

const nodeCache = new NodeCaching()

nodeCache.getStats()
/*
  {
    keys: 0,    // global key count
    hits: 0,    // global hit count
    misses: 0,  // global miss count
    ksize: 0,   // global key size count
    vsize: 0    // global value size count
  }
*/

.flushAll()

Flush all data.

Example:

const NodeCaching = require('node-caching')

const nodeCache = new NodeCaching()

nodeCache.flushAll()
nodeCache.getStats()
/*
  {
    keys: 0,    // global key count
    hits: 0,    // global hit count
    misses: 0,  // global miss count
    ksize: 0,   // global key size count
    vsize: 0    // global value size count
  }
*/

.close()

Close cache. This will clear the interval timeout which is set on check period option.

Example:

const NodeCaching = require('node-caching')

const nodeCache = new NodeCaching()

nodeCache.close()

Events

set

Fired when a key has been added or changed. You will get the key and the value as callback argument.

nodeCache.on('set', (key, value) => {
  // do something ...
})

del

Fired when a key has been removed manually or due to expiry. You will get the key and the deleted value as callback arguments.

nodeCache.on('del', (key, value) => {
  // do something ...
})

expired

Fired when a key expires. You will get the key and value as callback argument.

nodeCache.on('expired', (key, value) => {
  // do something ...
})

flush

Fired when the cache has been flushed.

nodeCache.on('flush', () => {
  // do something ...
})

License

MIT © Bu Kinoshita