hqarroum / timed-cache

:alarm_clock: A minimalist time-based caching system.

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

npm install --save timed-cache

Usage

Import the cache module

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

import Cache from 'timed-cache';

Creating the cache module

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 :

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 :

// 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.

Basic insertions

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 :

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 :

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 :

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.

Customizing elements TTL

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

// 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 :

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

Element removal

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

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