lean-cache

Lean and customizable in-memory cache. Allows to restrict cache in size as well as time. Provides different replacement strategies

Quick start

const LeanCache = require('lean-cache');
// how to get new entry
const loadFunc = (id) => {
  return db.fetch(id);
};

const opts = {
  load: loadFunc,
};
const cache = new LeanCache(opts);

await cache.get('abc'); // Await is not needed if No Load Function was provided
cache.get('abc', function(err, value){
    // either fetched from memory or via <loadFunc>
    console.log('my value = %s', value);
});

API

init(opts)

// DEFAULT_OPTIONS
{
	size: 100000, 	// 100k records max
	ttl: (60 * 60), // 1 hour
	interval: 600, 	// 10 minutes
	strategy: 'fifo', 	// First in first out
	storage: 'memory', // where to store cache objects
	load: null, 			// Where to get missing data
}

att	min	max	enum	comment
size	0	5000000		5 mil
ttl	0	2592000		30 days
interval	0	86400		24 hours
strategy	_	_	fifo, lru, none	more
storage	_	_	memory, file	more

.get(key)

if availible - returns a value from cache, otherwise uses to fetch value (and stores it for next use)

.set(key, value)

explicitly set the tuple

.count()

returns amount of entries in the cache

.stats()

{
	"count": 0,
	"strategy": "fifo",
	"head": null, 			// Key, for FiFo - the Oldest entry
	"headAdded": null, // Timestamp
	"tail": null, 			// Key, for FiFo - the Newest entry
	"tailAdded": null, // Timestamp
	"lastInterval": "2019-01-21T07:56:55.638Z", // Timestamp, when last check happened
	"lastExpiredCount": 5, // Number, how many entries were removed during the last check
	"lastExpiredAdded": "2019-01-21T07:56:52.642Z",
	"lastExpiredRemoved": "2019-01-21T07:56:55.638Z"
}

.keys()

Array of availible keys

other

replacement strategy

• 'fifo' - First in First out, when exceeds , removes an element starting from Head
• 'lru' - Least Recently Used, During Get moves the element to the Tail when exceeds , removes an element starting from Head
• 'none' - No replacement, elements are removed only on Time to Live basis
• 'none' - When is reached, cleans up storage completely, starts from scratch

custom strategy

// Demonstrates "None" strategy - when <count> exceeds <size>, returns False
const custom = function(opts, storage){
	this.opts = opts;
	const store = storage;
	
	this.set = function(key, obj){
		if(store.count() >= this.opts.size){
			return false; //deny
		}
		// add to Tail
		store.add(key, obj);
		return true;
	};
	
	this.get = function(key){
		return store.get(key);
	};
};

const cache = new LeanCache({size:1, strategy:custom});
cache.set('a', {}); //true
cache.set('b', {}); //false
cache.keys(); 		// ['a']

DEBUG

Debugging is done via "debug" library, add ENV variable to enable.

DEBUG=lean-cache node your-very-cool-app.js

storage options

• 'memory' - Default, keeps objects in memory
• 'file' - Flushes on to a File, picks it up after Restart

Performance

Array vs LinkedList

$ node --expose-gc benchmark/storageLoad.js

// benchmark - simple array
// n - amount of operations

*** Start - storageLoad.js ***
>>> TimeAdd - benchmark         - n = 1000000 | t = 192 ms | mem = 77.09 mb
>>> TimeAdd - storage           - n = 1000000 | t = 1028 ms | mem = 306.25 mb
add = -836

>>> TimeRead - benchmark        - n = 500000 | t = 3 ms | mem = 306.28 mb
>>> TimeRead - storage          - n = 500000 | t = 162 ms | mem = 307.38 mb
read = -159

>>> TimeDelete - benchmark      - n = 1000 | t = 1441 ms | mem = 307.39 mb
>>> TimeDelete - storage        - n = 1000 | t = 1 ms | mem = 307.4 mb
del = 1440

On avg the storage is Ahead by = 148.33 ms
>>> Garbage collector - mem = 275.74 mb

Array vs QueueArray

1*** Start - storageLoad.js ***
2>>> TimeAdd - benchmark         - n = 1000000 | t = 179 ms | mem = 81.2 mb
3>>> TimeAdd - storage           - n = 1000000 | t = 1096 ms | mem = 309.46 mb
4add = -917
5
6>>> TimeRead - benchmark        - n = 500000 | t = 3 ms | mem = 309.49 mb
7>>> TimeRead - storage          - n = 500000 | t = 158 ms | mem = 310.13 mb
8read = -155
9
10>>> TimeDelete - benchmark      - n = 1000 | t = 1399 ms | mem = 310.14 mb
11>>> TimeDelete - storage        - n = 1000 | t = 1259 ms | mem = 310.15 mb
12del = 140
13
14On avg the storage is Ahead by = -310.67 ms
15>>> Garbage collector - mem = 270.53 mb