interface OnErrorArgs {
    error: unknown;
}
interface CacheKeyOptions {
    cacheKey?: string;
}
type PromiseFunction<T> = () => Promise<T>;
interface CachedPromiseOptions<T> extends CacheKeyOptions {
    defaultValue?: T;
    invalidate?: boolean;
    onError?: (args: OnErrorArgs) => Promise<T>;
}
interface GetCachedPromiseWithArgsOptions<T, TArgs extends unknown[]> extends Pick<CachedPromiseOptions<T>, 'defaultValue' | 'invalidate' | 'onError'> {
    cacheKeyFn?: (...args: TArgs) => string;
}
/**
 * Returns a deterministic cache key derived from a promise-returning function's name and source.
 *
 * The key has the format `${name}:${hash}` where `hash` is computed from `function.toString()`.
 * This means two functions sharing a name but with different bodies produce different keys, while
 * the same function always yields the same key.
 *
 * Returns `undefined` when no function is provided or when the function is anonymous —
 * most commonly an inline arrow function passed directly (e.g. `getCachedPromise(() => fetch(...))`).
 *
 * @template T - The type of the resolved promise value
 * @param promise - The promise-returning function to derive the cache key from
 * @returns A `${name}:${hash}` cache key or `undefined` if no function is provided or the function is anonymous
 */
export declare function getCacheKeyFromPromise<T>(promise?: PromiseFunction<T>): string | undefined;
/**
 * This utility function will safely handle concurrent requests for the same resource by caching the promise.
 * Caches the result of a promise based on a key derived from the promise function's name and body
 * (via {@link getCacheKeyFromPromise}) or on an explicit `cacheKey`. If a cached promise exists
 * for the given key, it returns the cached promise. Otherwise, it executes the promise function
 * and caches the result.
 *
 * On error, the cache entry is always invalidated and the error is always logged.
 * If a `defaultValue` is provided, it is returned instead of throwing.
 * If an `onError` callback is provided, its return value is used instead of throwing.
 * If neither is provided, the error propagates after logging and cache invalidation.
 *
 * @template T - The type of the resolved promise value
 * @param promise - Function that returns the promise to be cached. Inline arrow functions are
 *   anonymous and will be rejected unless an explicit `cacheKey` is provided — assign the arrow
 *   to a `const` first so name inference applies.
 * @param options - Options object for keying, invalidation, and error handling
 * @param options.cacheKey - Optional cache key to use instead of the one derived from the function's name and body
 * @param options.defaultValue - Optional default value to return if the promise rejects
 * @param options.invalidate - Optionally invalidates the cache for the derived key or `cacheKey`
 * @param options.onError - Optional error handler that receives the error and returns a fallback value
 * @returns A promise that resolves to the cached or newly computed value
 */
export declare function getCachedPromise<T>(promise: PromiseFunction<T>, options?: CachedPromiseOptions<T>): Promise<T>;
export declare function invalidateCachedPromisesCache(): void;
/**
 * Serializes a value with a typeof prefix to avoid collisions
 * between different types (e.g. null vs undefined, 1 vs "1").
 *
 * Uses `JSON.stringify` internally, so only JSON-safe values (primitives, plain objects,
 * and arrays) produce stable cache keys. If serialization fails (e.g. circular references),
 * a unique uncacheable key is generated and the failure is logged as an error.
 *
 * For arguments that are not plain POJOs (e.g. `Map`, `Set`, `Date`, `RegExp`, class instances),
 * use the `cacheKeyFn` parameter on {@link getCachedPromiseWithArgs} instead.
 */
export declare function serializeArg(value: unknown, baseKey: string): string;
/**
 * Creates a cached version of a promise-returning function, keyed by its arguments.
 *
 * The base cache key is derived from the function's name and body via
 * {@link getCacheKeyFromPromise}, then combined with the per-call argument key.
 *
 * By default, cache keys are derived by serializing each argument with {@link serializeArg}
 * using `JSON.stringify`. This works reliably for:
 * - Primitives: `string`, `number`, `boolean`, `null`, `undefined`, `bigint`
 * - Plain objects (POJOs) and arrays
 *
 * **If your function accepts non-POJO arguments** (e.g. `Map`, `Set`, `Date`, `RegExp`,
 * class instances, NaN, Infinity, -0, or objects with circular references), you **must** provide a custom
 * `cacheKeyFn`. Without one, these values produce unstable or colliding keys (e.g. every
 * `Map` serializes to `{}` via `JSON.stringify`, and circular references fall through to a
 * single-use `uncacheable:<uuid>` key). When `cacheKeyFn` is provided, the default
 * serialization is bypassed and the caller is responsible for producing unique keys.
 *
 * @template T - The type of the resolved promise value
 * @template TArgs - The type of the arguments for the promise function
 * @param promise - A named promise-returning function to be cached. Inline arrow functions are
 *   anonymous and require a `cacheKeyFn` — or assign the arrow to a `const` first so name
 *   inference applies.
 * @param options - Options for keying, invalidation, and error handling
 * @param options.defaultValue - Optional default value to return if the promise rejects
 * @param options.invalidate - Optionally invalidates the cache for the derived key
 * @param options.onError - Optional error handler that receives the error and returns a fallback value
 * @param options.cacheKeyFn - Optional function that receives the same arguments as `fn` and returns a
 *   cache key string. **Required** when `fn` accepts arguments that are not plain POJOs.
 * @returns A wrapper function with the same signature as `fn` that returns cached promises
 */
export declare function getCachedPromiseWithArgs<T, TArgs extends unknown[]>(promise: (...args: TArgs) => Promise<T>, options?: GetCachedPromiseWithArgsOptions<T, TArgs>): (...args: TArgs) => Promise<T>;
/**
 * Removes a cached promise entry so the next call with the same key re-executes the function.
 *
 * The key is derived from the promise function's name and body via {@link getCacheKeyFromPromise}.
 * Silently no-ops when no entry exists for the resolved key.
 *
 * @template T - The type of the resolved promise value
 * @param promise - The promise-returning function whose cache entry should be invalidated. Inline
 *   arrow functions are anonymous and will be rejected — use the `cacheKey` overload instead, or
 *   assign the arrow to a `const` first so name inference applies.
 * @throws {Error} when the function is anonymous
 */
export declare function invalidateCachedPromise<T>(promise: PromiseFunction<T>): void;
/**
 * Removes a cached promise entry so the next call with the same key re-executes the function.
 *
 * Silently no-ops when no entry exists for the given key.
 *
 * @param cacheKey - The explicit cache key for the entry to invalidate.
 * @throws {Error} when `cacheKey` is empty
 */
export declare function invalidateCachedPromise(cacheKey: string): void;
/**
 * Replaces the cached promise entry with an already-resolved value, so subsequent reads with the
 * same key return `updatedValue` without re-invoking the function.
 *
 * The key is derived from the promise function's name and body via {@link getCacheKeyFromPromise}.
 * Adds the entry even when no prior value was cached for the key.
 *
 * @template T - The type of the resolved promise value
 * @param promise - The promise-returning function whose cache entry should be replaced. Inline
 *   arrow functions are anonymous and will be rejected — use the `cacheKey` overload instead, or
 *   assign the arrow to a `const` first so name inference applies.
 * @param updatedValue - The resolved value to cache. Subsequent cache reads with the same
 *   key will resolve to this value without re-invoking the function.
 * @throws {Error} when the function is anonymous
 */
export declare function replaceCachedPromise<T>(promise: PromiseFunction<T>, updatedValue: T): void;
/**
 * Replaces the cached promise entry with an already-resolved value, so subsequent reads with the
 * same key return `updatedValue` without re-invoking the function.
 *
 * Adds the entry even when no prior value was cached for the key.
 *
 * @param cacheKey - The explicit cache key for the entry to replace.
 * @param updatedValue - The resolved value to cache. Subsequent cache reads with the same
 *   key will resolve to this value without re-invoking the function.
 * @throws {Error} when `cacheKey` is empty
 */
export declare function replaceCachedPromise(cacheKey: string, updatedValue: unknown): void;
export {};