@keyv/memoize

Memoize any function using Keyv as storage backend.

Install

npm install --save keyv @keyv/memoize

Usage

const memoize = require('@keyvhq/memoize');

const memoizedRequest = memoize(request);

memoizedRequest('http://example.com').then(resp => { /* from request */ });
memoizedRequest('http://example.com').then(resp => { /* from cache */ });

You can pass a keyv instance or options to be used as argument.

memoize(request, { store: new Map() });
memoize(request, 'redis://user:pass@localhost:6379');
memoize(request, new Keyv());

Resolver

By default the first argument of your function call is used as cache key.

You can use a resolver if you want to change the key. The resolver is called with the same arguments as the function.

const sum = (n1, n2) => n1 + n2;

const memoized = memoize(sum, new Keyv(), {
  resolver: (n1, n2) => `${n1}+${n2}`
});

// cached as { '1+2': 3 }
memoized(1, 2); 

The library uses flood protection internally based on the result of this resolver. This means you can make as many requests as you want simultaneously while being sure you won't flood your async resource.

TTL

Set ttl to a number for a static TTL value.

const memoizedRequest = memoize(request, new Keyv(), { ttl: 60000 });

// cached for 60 seconds
memoizedRequest('http://example.com');

Set ttl to a function for a dynamic TTL value.

const memoizedRequest = memoize(request, new Keyv(), {
  ttl: (res) => res.statusCode === 200 ? 60000 : 0
});

// cached for 60 seconds only if response was 200 OK
memoizedRequest('http://example.com'); 

Stale

Set stale to any number of milliseconds.

If the ttl of a requested resource is below this staleness threshold we will still return the stale value but meanwhile asynchronously refresh the value.

const memoizedRequest = memoize(request, new Keyv(), { 
  ttl: 60000,
  stale: 10000
});

// cached for 60 seconds
memoizedRequest('http://example.com'); 

// … 55 seconds later
// Our cache will expire in 5 seconds.
// This is below the staleness threshold of 10 seconds.
// returns cached result + refresh cache on background
memoizedRequest('http://example.com'); 

When the stale option is set we won't delete expired items either. The same logic as above applies.

API

memoize(fn, [keyvOptions], [options])

fn

Type: Function
Required

Promise-returning or async function to be memoized.

keyvOptions

Type: Object

The [Keyv]https://github.com/microlinkhq/keyv] instance or keyv#options to be used.

options

resolver

Type: Function
Default: identity

ttl

Type: Number or Function
Default: undefined

The time-to-live quantity of time the value will considered as fresh.

stale

Type: Number
Default: undefined

The staleness threshold we will still return the stale value but meanwhile asynchronously refresh the value.

License

@keyvhq/memoize © Microlink, Released under the MIT License.
Authored and maintained by Microlink with help from contributors.

microlink.io · GitHub @MicrolinkHQ · Twitter @microlinkhq