timed-cache

Cache storage


A minimalist time-based caching system.

This storage module evicts cached key/value pairs based on their time-to-live.

Current version: 2.0.0

Install

``bash
npm install --save timed-cache
`

Usage

$3

timed-cache is distributed as an ESM module that you can import in your implementation.

`javascript
import Cache from 'timed-cache';
`

$3

Basic operations you can perform on an instance of a Cache are insertion, retrieval and removal of key/value pairs.

To do so, you will need to create a new instance of the cache, by calling its constructor :

`javascript
const cache = new Cache();
`

Note that by default, a key/value pair will be held by the cache storage for 60 seconds before being evicted.

It is however possible to specify what default value you would like the TTL to have when creating the storage :

`javascript
// The TTL is always expressed in milliseconds.
// In this case it will be equal to 5 minutes.
const cache = new Cache({ defaultTtl: 300 * 1000 });
`

You will then be able to interact with the storage by retrieving and inserting data.

$3

You insert a key/value pair into the storage by using the .put primitive and retrieve a value given its key identifier using the .get primitive.

Here is an example of inserting values associated with a string key :

`javascript
cache.put('bar', 'baz');
cache.put('foo', { foo: 'bar' });
cache.put('qux', 42);
`

It is then possible to retrieve the cached values using their associated keys :

`javascript
cache.get('bar'); // Returns 'baz'
cache.get('foo'); // Returns the object { foo: 'bar' }
`

It is also possible to use an object as a key as long as it is serializable using JSON.stringify :

`javascript
cache.put({ foo: 'bar' }, { bar: 'baz' });
cache.get({ foo: 'bar' }); // Returns the object { bar: 'baz' }
`

Note that inserting a value already associated with the inserted key will cause the previous value to be overwritten, and the TTL to be reset.

$3

You can customize the time-to-live value of a key/value pair at insertion time using the third optional argument to .put :

`javascript
// Example of an insertion using a TTL expressed in milliseconds.
cache.put('foo', 'bar', { ttl: 5 * 1000 });
`

It is also possible to define a callback for each inserted key/value pair to be informed when it is actually evicted from the storage :

`javascript
cache.put('baz', 'bar', {
ttl: 5 * 1000,
callback: (key, value) => console.log(${key} ${value} evicted !)
});
`

$3

It is possible to remove a cache entry before its time-to-live is reached, by using the .remove primitive :

`javascript
cache.put('foo', 'bar', {
callback: (key, value) => console.log(${key} ${value} removed !)
});

cache.remove('foo');
`

In this case, the callback passed to a .put` will be called if the user removed the inserted entry.

License