Skip to content

Latest commit

 

History

History
116 lines (93 loc) · 4.51 KB

README.md

File metadata and controls

116 lines (93 loc) · 4.51 KB
Raw

nano-cache

A little in-memory cache solution for nodejs.

Features

  • In memory cache storage for any JSON serializable data.
  • Expiration configured by number of accesses or time interval.
  • Limits memory usage by total usage or minimum free memory.
  • Supports compressed memory for higher capacity
  • Eviction by Least Recently Used algorithm.
  • Stats for cache hits, memory used, and evictions.
  • Not constrained by heap memory limit (about 1.5GB, depending on platform)
  • Emits events when some actions occurs.

Installation

> npm install --save-dev nano-cache

Use

The NanoCache constructor is also a singleton which can be used directly or as a factory.

// use the default singleton
var cache = require('nano-cache');

// or construct your own
var NanoCache = require('nano-cache');
var cache = new NanoCache();

// listen to events
cache.on('del', function (deletedKey) { /* ... */ });
cache.on('get', function (accessedKey) { /* ... */ });
cache.on('set', function (setKey) { /* ... */ });
cache.on('clear', function () { /* ... */ });

new NanoCache(options)

Use of the default singleton is optional. New cache objects can be constructed with custom configurations.

var NanoCache = require('nano-cache');
var cache = new NanoCache({
    ttl: 30000,                      // max aged for cache entry
    limit: 5,                        // max hits for a cache entry
    bytes : 100 * NanoCache.SIZE.MB, // max memory use for data
});
cache.set('mykey', myvalue);

cache.set(key, value, options)

Set the item in the cache dictionary, overriding any previous value or settings for the key. The value must be a JSON-serializable object which includes simple strings, numbers, or booleans.

var cache = require('nano-cache');
NanoCache.set('mykey', myvalue, {
    ttl: 60000, // ttl 60 seconds
    limit: 10 // limits the read count to 10 times, the 10'th time will expire the cache
});

cache.get(key)

Returns the value from the cache, or null if non-existent or expired.

NanoCache.set('mykey', myvalue)
var value = NanoCache.get('mykey');

Methods

  • get(key) returns a value
  • set(key, value, options) sets a key/value pair, returns the value set
  • del(key) deletes a key/value pair, returns the value deleted
  • clear() delete everything
  • clearExpired() deletes all expired key with their values to free up memory
  • isTTLExpired(key) check if a key's ttl is up, returns true/false, always false if there is no ttl set
  • isLimitReached(key) check if a key's read count has reached its limit, returns true/false, always false if there is no limit set
  • info(key) returns information about key, including access time, hits, and expiry
  • stats() returns number of items in cache, total byte size, and hit/miss ratio

EventEmitter

Every cache instance extends the EventEmitter object, so it has all of its methods. However, the most common used ones are probably the following:

  • on(eventName, callback)
  • once(eventName, callback)
  • emit(eventName, callback)
  • removeListener(eventName)
  • removeAllListeners(eventName, listenerCallbackReference)

Native Events

Every cache instance will emit the following events.

  • 'del' when a key is deleted. Its listeners callbacks will receive the deletedKey as the 1st argument.
  • 'get' when a key is accessed. Its listeners callbacks will receive the accessedKey as the 1st argument.
  • 'set' when a key is set. Its listeners callbacks will receive the setKey as the 1st argument.
  • 'clear' when all is clear from memory. No argument is passed to the listeners.

Constructor Options

  • ttl time in msec before the item is removed from cache. defaults to null for no limit.
  • limit maximum number of reads before item is removed from cache. defaults to null for no limit.
  • bytes maximum number of bytes before an item removed from the cache. defaults to Infinity for no limit.

Advanced Options

  • compress - use compression to reduce in-memory cache size. Defaults to true, but can be disabled for improved speed at the cost of memory size.
  • minFreeMem - items will be evicted from cache if os.freemem() is lower. Defaults to 0% of total memory.
  • maxEvictBytes - maximum amount of memory to be evicted on check, which leaves time for garbage collection, defaults to 5% of total memory.

License

Copyright (c) 2017 Cxense Inc

Authors:

  • aziz.khoury
  • greg.kindel

MIT license https://opensource.org/licenses/MIT