Memoize promise-returning & async functions
Useful for speeding up consecutive function calls by caching the result of calls with identical input.
By default, only the memoized function's first argument is considered via strict equality comparison. If you need to cache multiple arguments or cache objects by value, have a look at alternative caching strategies below.
This package is similar to memoize but with async-specific enhancements; in particular, it allows for asynchronous caches and does not cache rejected promises.
npm install p-memoize
import pMemoize from 'p-memoize';
import got from 'got';
const memoizedGot = pMemoize(got);
await memoizedGot('https://sindresorhus.com');
// This call is cached
await memoizedGot('https://sindresorhus.com');
Similar to the caching strategy for memoize with the following exceptions:
cache. Special properties assigned to a returned promise will not be kept after resolution and every promise may need to resolve with a serializable object if caching results in a database.Readable) is handed to every later caller already consumed.shouldCache predicate may await a nested call for that same key. The nested call joins the one already running, which is waiting on it, and neither ever settles..get(), .has() and .set() methods on cache can run asynchronously by returning a promise..set() being provided an object with the properties value and maxAge, it will only be provided value as the first argument. If you want to implement time-based expiry, consider doing so in cache.Returns a memoized version of the given function.
For an overloaded function, the option types come from one of its overloads, because ReturnType resolves a type with several call signatures to a single one. Pass both type arguments to pMemoize when that matters.
Type: Function
Promise-returning or async function to be memoized.
Type: object
Type: Function
Default: arguments_ => arguments_[0]
Example: arguments_ => JSON.stringify(arguments_)
Determines the cache key for storing the result based on the function arguments. By default, only the first argument is considered and it is compared by strict equality, so two objects only share an entry when they are the same one.
A cacheKey function can return any type supported by Map (or whatever structure you use in the cache option).
undefined explicitly. Pass a cacheKey that also looks at the argument count to tell them apart.cacheKey that returns a promise is rejected by the type: a promise is a fresh object on every call, so every key would be unique and nothing would ever be memoized.this) is not part of the key, and cacheKey cannot see it. See the receiver is not part of the cache key.See the caching strategy section for more information.
Type: object | false
Default: new Map()
Use a different cache storage. Must implement the following methods: .has(key), .get(key), and .set(key, value), and optionally .clear(). You could for example use a WeakMap instead or quick-lru for a LRU cache. To disable caching so that only concurrent executions resolve with the same value, pass false.
.has() decides whether there is a hit, and .get() is only called on a hit, to supply the value. If the two disagree, for example because the entry is evicted in between, the call resolves to undefined without running the function.cacheKey produces, which by default is the first argument's type. TypeScript cannot always check this, so a cache keyed by something else may only fail at runtime, depending on the cache..clear() cannot be emptied by pMemoizeClear(), and a WeakMap has none.See the caching strategy section in the mem package for more information.
Type: (value, {key, argumentsList}) => boolean | Promise<boolean>
Controls whether a fulfilled value should be written to the cache.
It runs after the function fulfills and before cache.set.
false to skip writing to the cache (in-flight de-duplication is still cleared).cache: false.import pMemoize from 'p-memoize';
// Only cache defined values
const getMaybe = pMemoize(async key => db.get(key), {
shouldCache: value => value !== undefined,
});
// Only cache non-empty arrays
const search = pMemoize(async query => fetchResults(query), {
shouldCache: value => Array.isArray(value) && value.length > 0,
});
Note: Affects only writes; reads from the cache are unchanged.
[!WARNING]
A method memoized on a prototype shares one cache between every instance, so it returns whichever instance's result was cached first.
The cache key is derived from the arguments only. The receiver (this) never reaches cacheKey, so there is no way to include it:
class Repository {
name = '';
async lookup(key) {
return `${this.name}:${key}`;
}
}
// `beta.lookup('k')` returns the value cached by `alpha.lookup('k')`.
Repository.prototype.lookup = pMemoize(Repository.prototype.lookup);
The same applies to pMemoizeDecorator() when you pass a cache of your own, since the same cache instance is handed to every instance. A method that depends on the instance needs a per-instance cache, which is what pMemoizeDecorator() gives you when you do not pass one:
class Repository {
name = '';
// Each instance gets its own cache.
@pMemoizeDecorator()
async lookup(key) {
return `${this.name}:${key}`;
}
}
Returns a decorator to memoize class methods (instance and static).
Notes:
experimentalDecorators are not supported.@pMemoizeDecorator() first (topmost) when you combine it with other method decorators. Decorators are applied from the bottom up, so a decorator listed above it replaces the method after it, and the memoized copy is then skipped so that it does not hide that replacement. This happens silently.super.method() call from the override reaches the original, unmemoized method.Type: object
Same as options for pMemoize().
import {pMemoizeDecorator} from 'p-memoize';
class Example {
index = 0
@pMemoizeDecorator()
async counter() {
return ++this.index;
}
}
class ExampleWithOptions {
index = 0
// Only cache positive results.
@pMemoizeDecorator({shouldCache: value => value > 0})
async counter() {
return ++this.index;
}
}
The decorator memoizes per-instance for an instance method, and per-class for a static one. With no cache of your own, you can clear an instance method's cache using pMemoizeClear(instance.method). With one, the cache is shared, so that call empties it for every instance of the class.
Clear all cached data of a memoized function.
What the clear reaches depends on what it is clearing:
A cache.set() that has already started when you clear is not undone, so that value can still land in the cleared cache.
This function is synchronous: a clear() that returns a promise finishes after it returns, and a rejection from it is dropped rather than reported, since there is nothing to return it through. A clear() that throws synchronously still propagates to the caller.
It throws when given something that was not memoized, when the memoized function has caching disabled, or when its cache cannot be cleared.
import pMemoize from 'p-memoize';
import ExpiryMap from 'expiry-map';
import got from 'got';
const cache = new ExpiryMap(10000); // Cached values expire after 10 seconds
const memoizedGot = pMemoize(got, {cache});
import pMemoize from 'p-memoize';
import pReflect from 'p-reflect';
const memoizedGot = pMemoize(async (url, options) => pReflect(got(url, options)));
await memoizedGot('https://example.com');
// {isFulfilled: true, isRejected: false, value: '...'}