@m4x1m1l14n/cache

!GitHub issues

Lightweight in-memory isomorphic cache implementation with TTL for browser & Node JS

This simple cache is written in TypeScript and works both for browser and Node. It is build on top of built-in Map thus theoretical limit for stored entries is in case of Node 2 ^ 24, which is approximately 16.6 million.
Each entry in cache can has its own TTL (timeout) and assigned expiration callback fired once entry expire.

Table of Contents

- Installation
- Documentation
- Instantiation
- set
- get
- take
- has
- delete
- flush

Installation

``bash
npm i @m4x1m1l14n/cache
`

Documentation

$3

Cache implementation uses templates so when you use this library in TypeScript project, you can restrict what type of key and value cache has to consume.

`ts
import { Cache } from '@m4x1m1l14n/cache';

const cache = new Cache();
`

Cache behavior can be altered with options object passed to its constructor. Following table shows options that can be changed.

| Option | Default value | Description |
| ---------- | ------------- | ------------------------------------------------------------------- |
| resolution | 1000 | Interval in milliseconds after which entries are checked for expiry |
| defaultTTL | Infinity | Default TTL for all added entries |
| maxItems | 1000 | Maximum number of entries stored in cache |

Example:

`ts
import { Cache, CacheOptions } from '@m4x1m1l14n/cache';

const options: CacheOptions = {
resolution: 1000,
defaultTTL: Number.POSITIVE_INFINITY,
maxItems: 1000,
};

const cache = new Cache(options);
`

$3

Store value in cache under specified key.

Prototype:

`ts
public set( key : K, value : T, ttl? : number, callback?: ExpirationCallback ) : Cache;
`

Params:

- key: Key under which value will be stored
- value: Value to store
- ttl (optional): Timeout after which cache entry will expire and will be deleted
- callback (optional): Callback invoked once entry expire

Return value:

set method returns itself, so it is possible to chain multiple sets

`ts
import { Cache } from '@m4x1m1l14n/cache';

const cache = new Cache();

cache.set(1, 'Hello').set(2, 'World').set(3, '!');
`

Example:

`ts
import { Cache } from '@m4x1m1l14n/cache';

const cache = new Cache();

// Key 1 will persist in cache until standardTTL is reached
cache.set(1, 'Hello');
// Key 2 will expire after 5 seconds
cache.set(2, 'World', 5000);
// Key 3 will expire after 3 seconds, and callback is called
cache.set(3, 'Some other value', 3000, (value) => {
console.log('${value}' has expired);
// Expected output
// > 'Some other value' has expired
});
`

$3

Retrieve value of cached entry by its key.

Prototype:

`ts
public get( key : K, refresh = false ) : T | undefined
`

Params:

- key: Key to retrieve
- refresh (default: false): Whether to refresh entry TTL or not. In case true is passed, item TTL is refreshed and its expiration is postponed, like item is freshly inserted in cache.

Return value:

get returns value assigned to specified key. If key is not found in cache, undefined is returned.

Example:

`ts
import { Cache } from '@m4x1m1l14n/cache';

const cache = new Cache();

cache.set(1, 'Hello');
console.log(cache.get(1));
// Expected output
// > Hello
`

$3

Retrieve value of cached entry by its key and remove it from cache.

Prototype:

`ts
public take( key: K ): T | undefined
`

Params:

- key: Key to retrieve

Return value:

take returns value assigned to specified key. If key is not found in cache, undefined is returned.

Example:

`ts
import { Cache } from '@m4x1m1l14n/cache';

const cache = new Cache();

cache.set(1, 'Hello');
console.log(cache.take(1));
console.log(cache.take(1));
// Expected output
// > Hello
// > undefined
`

$3

Returns wether cache contains specified key or not.

Prototype:

`ts
public has( key : K ) : boolean
`

Params:

- key: Key to check for

Return value:

true in case key exists in cache, false otherwise

Example:

`ts
import { Cache } from '@m4x1m1l14n/cache';

const cache = new Cache();

cache.set(1, 'Hello');
console.log(cache.has(1));
console.log(cache.has(2));
// Expected output
// > true
// > false
`

$3

Removes cache entry by specified key.

Prototype:

`ts
public delete( key : K ) : boolean
`

Params:

- key: Key of entry to remove

Return value:

true in case key was removed, false otherwise

Example:

`ts
import { Cache } from '@m4x1m1l14n/cache';

const cache = new Cache();

cache.set(1, 'Hello');
console.log(cache.get(1));
console.log(cache.delete(1));
console.log(cache.get(1));
console.log(cache.delete(1));
// Expected output
// > Hello
// > true
// > undefined
// > false
`

$3

Clears all entries from the cache, with an option to invoke expiration callbacks for each entry before deletion.

Prototype:

`ts
public flush(invokeCallback: boolean = false) : void
`

Params:

- invokeCallback (default: false): If set to true, any expiration callback assigned to an entry will be called before the entry is deleted.

Return value:

flush does not return a value.

Example:

`ts
import { Cache } from '@m4x1m1l14n/cache';

const cache = new Cache();

cache.set(1, 'Hello', 1000, (value) => {
console.log('${value}' has expired);
});
cache.set(2, 'World', 2000, (value) => {
console.log('${value}' has expired);
});

// Flush cache and invoke callbacks
cache.flush(true);
// Expected output:
// > 'Hello' has expired
// > 'World' has expired

// Flush cache without invoking callbacks
cache.flush();
``