nnash
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.
Install
npm install nnash --save
Examples:
Initialize (INIT):
const Cache = const cache = options
Options
stdTTL
: (default:0
) the standard ttl as number in seconds for every generated cache element.
0
= unlimitedcheckperiod
: (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. Iftrue
you'll get a copy of the cached variable. Iffalse
you'll save and get just the reference.
Note:true
is recommended, because it'll behave like a server-based caching. You should setfalse
if you want to save complex variable types like functions, promises, regexp, ...
const Cache = const cache = stdTTL: 100 checkperiod: 120 ;
Store a key (SET):
cache.set( key, val, [ ttl ], [callback] )
Sets a key
value
pair. It is possible to define a ttl
(in seconds).
Returns true
on success.
const obj = my: 'Special' variable: 42 cache
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.
const obj = my: 'Special' variable: 42 const success = cache// true
Retrieve a key (GET):
cache.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.
cache
Since 1.0.0
:
Callback is now optional. You can also use synchronous syntax.
value = cacheif 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 = cache; catch err // ENOTFOUND: Key `not-existing-key` not found
Get multiple keys (MGET):
cache.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.
cache
Since 1.0.0
:
Callback is now optional. You can also use synchronous syntax.
const value = cache/* { "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):
cache.del(key, [callback])
Delete a key. Returns the number of deleted entries. A delete will never fail.
cache;
Since 1.0.0
:
Callback is now optional. You can also use synchronous syntax.
value = cache;// 1
Delete multiple keys (MDEL):
cache.del( [ key1, key2, ... ,keyn ], [callback] )
Delete multiple keys. Returns the number of deleted entries. A delete will never fail.
cache
Since 1.0.0
:
Callback is now optional. You can also use synchronous syntax.
value = cache;// 1 value = cache// 2 value = cache// 1 - because A, B and C not exists
Change TTL (TTL):
cache.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.
const cache = stdTTL: 100 cache; cache; cache
Get TTL (getTTL):
cache.getTTL(key, [callback])
Receive the ttl of a key. You will get:
undefined
if the key does not exist0
if this key has no ttl- a timestamp in ms until the key expires
const cache = stdTTL: 100 // Date.now() = 1456000500000cachecache const ts = cache// ts wil be approximately 1456000600000 cache// ts wil be approximately 1456000600000 const ts = cache// ts = 0 const ts = cache// ts = undefined
List keys (KEYS)
cache.keys( [callback] )
Returns an array of all existing keys.
// asynccache // syncconst mykeys = cache console// [ "all', "my', "keys', "foo', "bar" ]
Statistics (STATS):
cache.getStats()
Returns the statistics.
cache /* { 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):
cache.flushAll()
Flush all data.
cache;cache; /* { 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:
cache.close()
This will clear the interval timeout which is set on check period option.
cache
Events
set
Fired when a key has been added or changed.
You will get the key
and the value
as callback argument.
cache;
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.
cache
expired
Fired when a key expires.
You will get the key
and value
as callback argument.
cache
flush
Fired when the cache has been flushed.
cache
Benchmarks
Version 1.1.x
After adding io.js to the travis test here are the benchmark results for set and get of 100000 elements. But be careful with this results, because it has been executed on travis machines, so it is not guaranteed, that it was executed on similar hardware.
node.js 0.10.36
SET: 324
ms ( 3.24
µs per item )
GET: 7956
ms ( 79.56
µs per item )
node.js 0.12.0
SET: 432
ms ( 4.32
µs per item )
GET: 42767
ms ( 427.67
µs per item )
io.js v1.1.0
SET: 510
ms ( 5.1
µs per item )
GET: 1535
ms ( 15.35
µs per item )
Version 2.0.x
Again the same benchmarks by travis with version 2.0
node.js 0.6.21
SET: 786
ms ( 7.86
µs per item )
GET: 56
ms ( 0.56
µs per item )
node.js 0.10.36
SET: 353
ms ( 3.53
µs per item )
GET: 41
ms ( 0.41
µs per item )
node.js 0.12.2
SET: 327
ms ( 3.27
µs per item )
GET: 32
ms ( 0.32
µs per item )
io.js v1.7.1
SET: 238
ms ( 2.38
µs per item )
GET: 34
ms ( 0.34
µs per item )
As you can see the version 2.x will increase the GET performance up to 200x in node 0.10.x. This is possible because the memory allocation for the object returned by 1.x is very expensive.
Version 3.0.x
see travis results
node.js 0.6.21
SET: 786
ms ( 7.24
µs per item )
GET: 56
ms ( 1.14
µs per item )
node.js 0.10.38
SET: 353
ms ( 5.41
µs per item )
GET: 41
ms ( 1.23
µs per item )
node.js 0.12.4
SET: 327
ms ( 4.63
µs per item )
GET: 32
ms ( 0.60
µs per item )
io.js v2.1.0
SET: 238
ms ( 4.06
µs per item )
GET: 34
ms ( 0.67
µs per item )
until the version 3.0.x the object cloning is included, so we lost a little bit of the performance
Version 3.1.x
node.js v0.10.41
SET: 305ms
( 3.05µs
per item )
GET: 104ms
( 1.04µs
per item )
node.js v0.12.9
SET: 337ms
( 3.37µs
per item )
GET: 167ms
( 1.67µs
per item )
node.js v4.2.6
SET: 356ms
( 3.56µs
per item )
GET: 83ms
( 0.83µs
per item )