@m4x1m1l14n/cache
Version:
Lightweight in-memory isomorphic cache implementation with TTL for browser & Node JS written in TypeScript
289 lines (193 loc) • 6.6 kB
Markdown
[](https://www.npmjs.com/package/@m4x1m1l14n/cache)
[](https://github.com/m4x1m1l14n/cache-js/actions/workflows/ci.yml)
[](https://codecov.io/gh/m4x1m1l14n/cache-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](#installation)
- [Documentation](#documentation)
- [Instantiation](#instantiation)
- [set](#set)
- [get](#get)
- [take](#take)
- [has](#has)
- [delete](#delete)
- [flush](#flush)
## Installation
```bash
npm i @m4x1m1l14n/cache
```
## Documentation
### Instantiation
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<number, string>();
```
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<number, string>(options);
```
Store value in cache under specified key.
Prototype:
```ts
public set( key : K, value : T, ttl? : number, callback?: ExpirationCallback<T> ) : Cache<K, T>;
```
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<number, string>();
cache.set(1, 'Hello').set(2, 'World').set(3, '!');
```
Example:
```ts
import { Cache } from '@m4x1m1l14n/cache';
const cache = new Cache<number, string>();
// 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
});
```
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<number, string>();
cache.set(1, 'Hello');
console.log(cache.get(1));
// Expected output
// > Hello
```
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<number, string>();
cache.set(1, 'Hello');
console.log(cache.take(1));
console.log(cache.take(1));
// Expected output
// > Hello
// > undefined
```
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<number, string>();
cache.set(1, 'Hello');
console.log(cache.has(1));
console.log(cache.has(2));
// Expected output
// > true
// > false
```
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<number, string>();
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
```
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<number, string>();
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();
```