https://github.com/hqarroum/timed-cache
:alarm_clock: A minimalist time-based caching system.
https://github.com/hqarroum/timed-cache
cache-storage
Last synced: 12 days ago
JSON representation
:alarm_clock: A minimalist time-based caching system.
- Host: GitHub
- URL: https://github.com/hqarroum/timed-cache
- Owner: HQarroum
- License: mit
- Created: 2015-06-24T21:36:32.000Z (almost 10 years ago)
- Default Branch: master
- Last Pushed: 2023-07-19T18:08:49.000Z (almost 2 years ago)
- Last Synced: 2025-04-08T17:05:59.798Z (18 days ago)
- Topics: cache-storage
- Language: JavaScript
- Homepage:
- Size: 615 KB
- Stars: 43
- Watchers: 3
- Forks: 5
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
## Cache storage
[](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**
## Install
```bash
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.
```javascript
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 :
```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.
### 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 :
```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.
### 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` :
```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 !`)
});
```
### Element removal
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
[](https://app.fossa.io/projects/git%2Bgithub.com%2FHQarroum%2Ftimed-cache?ref=badge_large)