node-cache

From: https://www.npmjs.com/package/node-cache

Simple and fast NodeJS internal caching.

A simple caching module that has set, get and delete methods and works a little bit like memcached. Keys can have a timeout (ttl) after which they expire and are deleted from the cache. All keys are stored in a single object so the practical limit is at around 1m keys.

Since 4.1.0: Key-validation: The keys can be given as either string or number, but are casted to a string internally anyway. All other types will either throw an error or call the callback with an error.

Install

npm install node-cache --save

Or just require the node_cache.js file to get the superclass

Examples:

Initialize (INIT):

const NodeCache = require( "node-cache" );
const myCache = new NodeCache();

Options

stdTTL: (default: 0) the standard ttl as number in seconds for every generated cache element. 0 = unlimited
checkperiod: (default: 600) The period in seconds, as a number, used for the automatic delete check interval. 0 = no periodic check.
errorOnMissing: (default: false) en/disable throwing or passing an error to the callback if attempting to .get a missing or expired value.
useClones: (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. Here's a simple code exmaple showing the different behavior
deleteOnExpire: (default: true) whether variables will be deleted automatically when they expire. If true the variable will be deleted. If false the variable will remain. You are encouraged to handle the variable upon the event expired by yourself.

const NodeCache = require( "node-cache" );
const myCache = new NodeCache( { stdTTL: 100, checkperiod: 120 } );

Store a key (SET):

myCache.set( key, val, [ ttl ], [callback] )

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

obj = { my: "Special", variable: 42 };
myCache.set( "myKey", obj, function( err, success ){
  if( !err && success ){
    console.log( success );
    // true
    // ... do something ...
  }
});

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

Since 1.0.0: Callback is now optional. You can also use synchronous syntax.

obj = { my: "Special", variable: 42 };
success = myCache.set( "myKey", obj, 10000 );
// true

Retrieve a key (GET):

myCache.get( key, [callback] )

Gets a saved value from the cache. Returns a undefined if not found or expired. If the value was found it returns an object with the key value pair.

myCache.get( "myKey", function( err, value ){
  if( !err ){
    if(value == undefined){
      // key not found
    }else{
      console.log( value );
      //{ my: "Special", variable: 42 }
      // ... do something ...
    }
  }
});

Since 1.0.0: Callback is now optional. You can also use synchronous syntax.

value = myCache.get( "myKey" );
if ( value == undefined ){
  // handle miss!
}
// { my: "Special", variable: 42 }

Since 2.0.0:

The return format changed to a simple value and a ENOTFOUND error if not found ( as callback( err ) or on sync call as result instance of Error ).

Since 2.1.0:

The return format changed to a simple value, but a due to discussion in #11 a miss shouldn't return an error. So after 2.1.0 a miss returns undefined.

Since 3.1.0 errorOnMissing option added

try{
    value = myCache.get( "not-existing-key", true );
} catch( err ){
    // ENOTFOUND: Key `not-existing-key` not found
}

Get multiple keys (MGET):

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

Gets multiple saved values from the cache. Returns an empty object {} if not found or expired. If the value was found it returns an object with the key value pair.

myCache.mget( [ "myKeyA", "myKeyB" ], function( err, value ){
  if( !err ){
    console.log( value );
    /*
      {
        "myKeyA": { my: "Special", variable: 123 },
        "myKeyB": { the: "Glory", answer: 42 }
      }
    */
    // ... do something ...
  }
});

Since 1.0.0: Callback is now optional. You can also use synchronous syntax.

value = myCache.mget( [ "myKeyA", "myKeyB" ] );
/*
  {
    "myKeyA": { my: "Special", variable: 123 },
    "myKeyB": { the: "Glory", answer: 42 }
  }
*/

Since 2.0.0:

The method for mget changed from .get( [ "a", "b" ] ) to .mget( [ "a", "b" ] )

Delete a key (DEL):

myCache.del( key, [callback] )

Delete a key. Returns the number of deleted entries. A delete will never fail.

myCache.del( "myKey", function( err, count ){
  if( !err ){
    console.log( count ); // 1
    // ... do something ...
  }
});

Since 1.0.0: Callback is now optional. You can also use synchronous syntax.

value = myCache.del( "A" );
// 1

Delete multiple keys (MDEL):

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

Delete multiple keys. Returns the number of deleted entries. A delete will never fail.

myCache.del( [ "myKeyA", "myKeyB" ], function( err, count ){
  if( !err ){
    console.log( count ); // 2
    // ... do something ...
  }
});

Since 1.0.0: Callback is now optional. You can also use synchronous syntax.

value = myCache.del( "A" );
// 1
 
value = myCache.del( [ "B", "C" ] );
// 2
 
value = myCache.del( [ "A", "B", "C", "D" ] );
// 1 - because A, B and C not exists

Change TTL (TTL):

myCache.ttl( key, ttl, [callback] )

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.

The key will be deleted when passing in a ttl < 0.

myCache = new NodeCache( { stdTTL: 100 } )
myCache.ttl( "existendKey", 100, function( err, changed ){
  if( !err ){
    console.log( changed ); // true
    // ... do something ...
  }
});
 
myCache.ttl( "missingKey", 100, function( err, changed ){
  if( !err ){
    console.log( changed ); // false
    // ... do something ...
  }
});
 
myCache.ttl( "existendKey", function( err, changed ){
  if( !err ){
    console.log( changed ); // true
    // ... do something ...
  }
});

Get TTL (getTTL):

myCache.getTtl( key, [callback] )

Receive the ttl of a key. You will get:

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

myCache = new NodeCache( { stdTTL: 100 } )
 
// Date.now() = 1456000500000
myCache.set( "ttlKey", "MyExpireData" )
myCache.set( "noTtlKey", "NonExpireData", 0 )
 
ts = myCache.getTtl( "ttlKey" )
// ts wil be approximately 1456000600000
 
myCache.getTtl( "ttlKey", function( err, ts ){
  if( !err ){
    // ts wil be approximately 1456000600000
  }
});
// ts wil be approximately 1456000600000
 
ts = myCache.getTtl( "noTtlKey" )
// ts = 0
 
ts = myCache.getTtl( "unknownKey" )
// ts = undefined
 

List keys (KEYS)

myCache.keys( [callback] )

Returns an array of all existing keys.

// async
myCache.keys( function( err, mykeys ){
  if( !err ){
    console.log( mykeys );
   // [ "all", "my", "keys", "foo", "bar" ]
  }
});
 
// sync
mykeys = myCache.keys();
 
console.log( mykeys );
// [ "all", "my", "keys", "foo", "bar" ]
 

Statistics (STATS):

myCache.getStats()

Returns the statistics.

myCache.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
    }
  */

Flush all data (FLUSH):

myCache.flushAll()

Flush all data.

myCache.flushAll();
myCache.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 the cache:

myCache.close()

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

myCache.close();

Events

set

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

myCache.on( "set", function( 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.

myCache.on( "del", function( key, value ){
  // ... do something ...
});

expired

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

myCache.on( "expired", function( key, value ){
  // ... do something ...
});

flush

Fired when the cache has been flushed.

myCache.on( "flush", function(){
  // ... do something ...
});