idmp/dist/index.d.ts

A lightweight TypeScript library for deduplicating and caching async function calls with automatic retries, designed for idempotent network requests in React and Node.js.

/**
 * IdmpGlobalKey type - Represents the key used to identify and store promises globally
 * Can be a string, number, symbol, or falsy value (false, null, undefined)
 */
type IdmpGlobalKey = string | number | symbol | false | null | undefined;
/**
 * IdmpPromise type - Function that returns a Promise of generic type T
 */
type IdmpPromise<T> = () => Promise<T>;
/**
 * Configuration options for IDMP (Intelligent Deduplication of Multiple Promises)
 */
interface IdmpOptions {
    /**
     * Maximum number of retry attempts for failed promises
     * @default 30
     */
    maxRetry?: number;
    /**
     * Minimum delay between retry attempts in milliseconds
     * @default 50
     */
    minRetryDelay?: number;
    /**
     * Maximum delay between retry attempts in milliseconds
     * @default 5000
     */
    maxRetryDelay?: number;
    /**
     * Maximum cache age in milliseconds
     * After this period, the cached promise result will be cleared
     * @default 3000
     * @max 604800000 (7 days)
     */
    maxAge?: number;
    signal?: AbortSignal;
    /**
     * Function executed before each retry attempt
     * @param err - The error object that caused the retry
     * @param extra - Additional context information
     * @param extra.globalKey - The key identifying this promise in the global store
     * @param extra.retryCount - Current retry attempt number
     */
    onBeforeRetry?: (err: any, extra: {
        globalKey: IdmpGlobalKey;
        retryCount: number;
    }) => void;
}
/**
 * Normalizes options, applying defaults as needed
 * @param options - User-provided options
 * @returns Normalized options object
 */
declare const getOptions: (options?: IdmpOptions) => {
    maxRetry: number;
    maxAge: number;
    minRetryDelay: number;
    maxRetryDelay: number;
    onBeforeRetry: (err: any, extra: {
        globalKey: IdmpGlobalKey;
        retryCount: number;
    }) => void;
    f: boolean;
    signal: AbortSignal | undefined;
};
/**
 * Main IDMP function - Intelligent Deduplication of Multiple Promises
 *
 * Ensures that multiple calls to the same asynchronous operation (identified by globalKey)
 * will reuse the same promise, avoiding duplicate network requests or operations.
 * Includes automatic retry logic, caching, and request deduplication.
 *
 * @param globalKey - Unique identifier for this promise operation
 * @param promiseFunc - Function that returns the promise to execute
 * @param options - Configuration options
 * @returns Promise resolving to the result of promiseFunc
 *
 * @example
 * ```typescript
 * // Basic usage
 * const data = await idmp('user-123', () => fetchUserData(123));
 *
 * // With options
 * const data = await idmp('user-123', () => fetchUserData(123), {
 *   maxRetry: 5,
 *   maxAge: 60000, // 1 minute cache
 *   onBeforeRetry: (err, {retryCount}) => console.log(`Retry #${retryCount}`)
 * });
 * ```
 */
declare const idmp: {
    <T>(globalKey: IdmpGlobalKey, promiseFunc: IdmpPromise<T>, options?: IdmpOptions): Promise<T>;
    /**
     * Clear the cached result for a specific key
     */
    flush: (globalKey: IdmpGlobalKey) => void;
    /**
     * Clear all cached results
     */
    flushAll: () => void;
};
/**
 * Type definition for the idmp function including its methods
 */
type Idmp = typeof idmp;
export default idmp;
export { getOptions, idmp, type Idmp, type IdmpGlobalKey, type IdmpOptions, type IdmpPromise, };