141 lines
5.4 KiB
TypeScript
141 lines
5.4 KiB
TypeScript
import type { AsyncReturnType } from 'type-fest';
|
||
export type AnyAsyncFunction = (...arguments_: readonly any[]) => Promise<unknown | void>;
|
||
export type CacheStorage<KeyType, ValueType> = {
|
||
has: (key: KeyType) => Promise<boolean> | boolean;
|
||
get: (key: KeyType) => Promise<ValueType | undefined> | ValueType | undefined;
|
||
set: (key: KeyType, value: ValueType) => Promise<unknown> | unknown;
|
||
delete: (key: KeyType) => unknown;
|
||
clear?: () => unknown;
|
||
};
|
||
/**
|
||
Controls whether a fulfilled value should be written to the cache.
|
||
*/
|
||
export type ShouldCache<KeyType, ValueType, ArgumentsList extends readonly unknown[] = readonly unknown[]> = (value: ValueType, context: {
|
||
key: KeyType;
|
||
argumentsList: ArgumentsList;
|
||
}) => boolean | Promise<boolean>;
|
||
export type Options<FunctionToMemoize extends AnyAsyncFunction, CacheKeyType> = {
|
||
/**
|
||
Determines the cache key for storing the result based on the function arguments. By default, __only the first argument is considered__ and it only works with [primitives](https://developer.mozilla.org/docs/Glossary/Primitive).
|
||
|
||
A `cacheKey` function can return any type supported by `Map` (or whatever structure you use in the `cache` option).
|
||
|
||
You can have it cache **all** the arguments by value with `JSON.stringify`, if they are compatible:
|
||
|
||
```
|
||
import pMemoize from 'p-memoize';
|
||
|
||
pMemoize(function_, {cacheKey: JSON.stringify});
|
||
```
|
||
|
||
Or you can use a more full-featured serializer like [serialize-javascript](https://github.com/yahoo/serialize-javascript) to add support for `RegExp`, `Date` and so on.
|
||
|
||
```
|
||
import pMemoize from 'p-memoize';
|
||
import serializeJavascript from 'serialize-javascript';
|
||
|
||
pMemoize(function_, {cacheKey: serializeJavascript});
|
||
```
|
||
|
||
@default arguments_ => arguments_[0]
|
||
@example arguments_ => JSON.stringify(arguments_)
|
||
*/
|
||
readonly cacheKey?: (arguments_: Parameters<FunctionToMemoize>) => CacheKeyType;
|
||
/**
|
||
Use a different cache storage. Must implement the following methods: `.has(key)`, `.get(key)`, `.set(key, value)`, `.delete(key)`, and optionally `.clear()`. You could for example use a `WeakMap` instead or [`quick-lru`](https://github.com/sindresorhus/quick-lru) for a LRU cache. To disable caching so that only concurrent executions resolve with the same value, pass `false`.
|
||
|
||
@default new Map()
|
||
@example new WeakMap()
|
||
*/
|
||
readonly cache?: CacheStorage<CacheKeyType, AsyncReturnType<FunctionToMemoize>> | false;
|
||
/**
|
||
Controls whether a fulfilled value should be written to the cache.
|
||
|
||
It runs after the function fulfills and before `cache.set`.
|
||
|
||
- Omit to keep current behavior (always write).
|
||
- Return `false` to skip writing to the cache (in-flight de-duplication is still cleared).
|
||
- Throw or reject to propagate the error and skip caching.
|
||
|
||
@example
|
||
```
|
||
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: This only affects writes; reads from the cache are unchanged.
|
||
*/
|
||
readonly shouldCache?: ShouldCache<CacheKeyType, AsyncReturnType<FunctionToMemoize>, Parameters<FunctionToMemoize>>;
|
||
};
|
||
/**
|
||
[Memoize](https://en.wikipedia.org/wiki/Memoization) functions - An optimization used to speed up consecutive function calls by caching the result of calls with identical input.
|
||
|
||
@param fn - Function to be memoized.
|
||
|
||
@example
|
||
```
|
||
import {setTimeout as delay} from 'node:timer/promises';
|
||
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');
|
||
|
||
await delay(2000);
|
||
|
||
// This call is not cached as the cache has expired
|
||
await memoizedGot('https://sindresorhus.com');
|
||
```
|
||
*/
|
||
export default function pMemoize<FunctionToMemoize extends AnyAsyncFunction, CacheKeyType = Parameters<FunctionToMemoize>[0], OptionsType = Options<FunctionToMemoize, CacheKeyType>>(fn: FunctionToMemoize, options?: OptionsType & Options<FunctionToMemoize, CacheKeyType>): FunctionToMemoize;
|
||
/**
|
||
- Only class methods are supported; regular functions are not part of the decorators proposals.
|
||
- Uses the new ECMAScript decorators (TypeScript 5.0+). Legacy `experimentalDecorators` are not supported.
|
||
- Babel’s legacy decorators are not supported.
|
||
- Private methods are not supported.
|
||
|
||
@returns A decorator to memoize class methods or static class methods.
|
||
|
||
@example
|
||
```
|
||
import {pMemoizeDecorator} from 'p-memoize';
|
||
|
||
class Example {
|
||
index = 0
|
||
|
||
@pMemoizeDecorator()
|
||
async counter() {
|
||
return ++this.index;
|
||
}
|
||
}
|
||
|
||
class ExampleWithOptions {
|
||
index = 0
|
||
|
||
@pMemoizeDecorator()
|
||
async counter() {
|
||
return ++this.index;
|
||
}
|
||
}
|
||
```
|
||
*/
|
||
export declare function pMemoizeDecorator<FunctionToMemoize extends AnyAsyncFunction = AnyAsyncFunction, CacheKeyType = Parameters<FunctionToMemoize>[0]>(options?: Options<NoInfer<FunctionToMemoize>, NoInfer<CacheKeyType>>): <This, Value extends FunctionToMemoize>(value: Value, context: ClassMethodDecoratorContext<This, Value>) => void;
|
||
/**
|
||
Clear all cached data of a memoized function.
|
||
|
||
@param fn - Memoized function.
|
||
*/
|
||
export declare function pMemoizeClear(fn: AnyAsyncFunction): void;
|