@mobilabs/lru
v1.0.6
Published
An in-memory key/value cache based on the Least Recently Used algorithm
Downloads
68
Maintainers
Readme
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
returnsnull
.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
returnsnull
.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
returnsnull
.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.