timed-cache
Version:
A minimalist time-based caching system.
117 lines (77 loc) • 4.02 kB
Markdown
<br /><br /><br /><br /><p align="center">
<img width="200" src="https://upload.wikimedia.org/wikipedia/commons/thumb/4/49/Applications-database.svg/240px-Applications-database.svg.png" />
</p><br /><br /><br />
[](https://app.travis-ci.com/HQarroum/timed-cache)
[](https://www.codefactor.io/repository/github/hqarroum/timed-cache)
[](https://deepsource.io/gh/HQarroum/timed-cache/?ref=repository-badge)
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**
```bash
npm install --save timed-cache
```
`timed-cache` is distributed as an ESM module that you can import in your implementation.
```javascript
import Cache from 'timed-cache';
```
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.
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`](https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Objets_globaux/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.
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 !`)
});
```
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.
[](https://app.fossa.io/projects/git%2Bgithub.com%2FHQarroum%2Ftimed-cache?ref=badge_large)