LRU

LRU is an in-memory key/value cache that relies on the Least Recently Used algorithm to maintain its size in a predefined limits.

LRU runs on both Node.js and ECMAScript 2015 (ES6) compliant browsers.

LRU is encapsulated in a module pattern. Only the variable LRU is accessible outside the module. Thus, it doesn't pollute the global space.

LRU is freely inspired from node-lru-cache.

Quick Startup

You can create your database object by typing:

const cache = LRU();

There is no need to use the new operator as LRU implements the prototypal instantiation pattern.

When, your cache is created, you can add a key/value by typing:

cache.set('a', { a: 1 });

if the key/value is already in the cache, the operation is ignored. But, you can force to update a key/value with the option force:

cache.set('a', { a: 2 }, { force: true });

You can read a key/value, from the cache, by typing:

cache.get('a');

API

The constructor

LRU accepts optionals parameters including: maxItems and maxAge.

By default, maxItems is set to 1000. It can't be lower than 1.

By default, maxAge is set to 1 hour. It can't be lower than 100ms.

To set different values, simply do:

const cache = LRU({ maxAge: 1000, maxItems: 100000 });

The methods

LRU provides the following methods:

• set set(key, value) stores a new key/value into the cache and returns the added key/value.

  If the key key already exists into the cache, set returns the stored value.

  You can force to update the value by typing: set(key, newval, { force: true });

• get get(key) returns the key/value stored into the cache. If this key/value doesn't exist, or it has reached its lifetime, get returns null.

• has has(key) returns the key/value stored into the cache. If this key/value doesn't exist, or it has reached its lifetime, has returns null.

• remove remove(key) returns the key/value stored into the cache and remove it from the cache. If this key/value doesn't exist, or it has reached its lifetime, remove returns null.

• empty empty() removes all the key/values from the cache.

• dump dump() returns an array with all the key(s)/value(s) stored into the cache that haven't exceeded their lifetime.

  The array looks like:

  [
    { key: 'a', value: 'aaa', age: 100 },
    { key: 'b', value: 'bbb', age: 80 },
    ...
  ]

  it is ordered from the oldest to the newest key/value.

• prune prune() removes, from the cache, the key/value pairs that have exceeded their lifetime.

• count count() returns the number of key(s)/value(s) stored into the cache.

• renew renew(key) sets to zero the age of a key/value.

Remove programatically old key/value pairs

By default, a key/value pair that has exceeded its lifetime is removed from the cache only when a method get or has is performed.

If you want to automatically clean the cache, you have to pass a duration when you create the cache by typing:

const cache = LRU({ prune: 2000 });

The value is expressed in milliseconds. It can be lower that 1000. In the example above, the prune method is processed every 2000ms.

Embed LRU into your own library

You can easily embed LRU into your own library by a simple copy and paste. Or by using import.

Enjoy!

License

MIT.