p-memoize

pMemoize: <
    FunctionToMemoize extends AnyAsyncFunction,
    CacheKeyType = Parameters<FunctionToMemoize>[0]
>(
    fn: FunctionToMemoize,
    options?: Options<FunctionToMemoize, CacheKeyType>
) => FunctionToMemoize;

pMemoizeClear: (fn: AnyAsyncFunction) => void;

pMemoizeDecorator: <
    FunctionToMemoize extends AnyAsyncFunction = (
        ...arguments_: any[]
    ) => Promise<any>,
    CacheKeyType = Parameters<FunctionToMemoize>[0]
>(
    options?: Options<NoInfer<FunctionToMemoize>, NoInfer<CacheKeyType>>
) => <This, Value extends FunctionToMemoize>(value: Value, context: any) => void;

type AnyAsyncFunction = (...arguments_: readonly any[]) => Promise<unknown | void>;

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;
    /**
    Not used by p-memoize. It is allowed so that a cache which has one can still be passed as an object literal.
    */
    delete?: (key: KeyType) => unknown;
    clear?: () => unknown;
};

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 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).

    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});
    ```

    - A call with no arguments has an undefined first argument, so it shares an entry with a call passing `undefined` explicitly. Pass a `cacheKey` that also looks at the argument count to tell them apart.
    - A `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.
    - The receiver (`this`) is not part of the key, and `cacheKey` cannot see it. A method memoized on a prototype, or one given a `cache` that is shared between instances, returns whichever instance's result was cached first. Use `pMemoizeDecorator()` without a custom `cache` for methods that depend on the instance.

    @default arguments_ => arguments_[0]
    @example arguments_ => JSON.stringify(arguments_)
    */
    readonly cacheKey?: (
        arguments_: Parameters<FunctionToMemoize>
    ) => CacheKeyType extends PromiseLike<unknown> ? never : CacheKeyType;
    /**
    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`](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`.

    - `.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.
    - Its key type must be the one `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.
    - A cache with no `.clear()` cannot be emptied by `pMemoizeClear()`, and a `WeakMap` has none.

    @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. The predicate does not run at all when caching is disabled with `cache: false`.

    @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>
    >;
};

type ShouldCache<
    KeyType,
    ValueType,
    ArgumentsList extends readonly unknown[] = readonly unknown[]
> = (
    value: ValueType,
    context: {
        key: KeyType;
        argumentsList: ArgumentsList;
    }
) => boolean | Promise<boolean>;