jlru

JLRU

JLRU is no longer supported. Use @mobilabs/lru instead.

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

JLRU runs on both the browser and Node.js.

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

JLRU is freely inspired from node-lru-cache.

Quick Startup

You can create your database object by typing:

const cache = JLRU();

There is no need to use the new operator as JLRU 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

JLRU 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 = JLRU({ maxAge: 1000, maxItems: 100000 });

The methods

JLRU 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 = JLRU({ 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 JLRU into your own library

You can easily embed JLRU into your own library by a simple copy and paste. As said earlier, JLRU is encapsulated inside a module pattern. It does export only the variable JLRU in the global space.

If you want to embed, JLRU inside your library, you just need to copy it and replace this at the top of the library by the object you want to attach it:

} else {
  // Browser globals.
  /* eslint-disable no-param-reassign */
  root.JLRU = factory(root);
  /* eslint-enable no-param-reassign */
}
}(this, function(root) {
'use strict';

You don't need browserify, webpack or so on!

Enjoy!

License

MIT.