idempotency-redis/dist/executor.d.ts

Idempotency guarantee via Redis

import Client from 'ioredis';
import { Serializer } from './serialization';
/**
 * Defines the options for running an asynchronous action.
 */
interface RunOptions<T> {
    timeout: number;
    valueSerializer: Serializer<T>;
    errorSerializer: Serializer<Error>;
    shouldIgnoreError?: (error: Error) => boolean;
    onActionSuccess: (idempotencyKey: string, value: T) => T;
    onActionError: (idempotencyKey: string, error: Error) => Error;
    onSuccessReplay: (idempotencyKey: string, value: T) => T;
    onErrorReplay: (idempotencyKey: string, error: Error) => Error;
}
/**
 * Manages idempotency in asynchronous operations by leveraging Redis for storage and distributed locks.
 */
export declare class IdempotentExecutor {
    private redlock;
    private cache;
    /**
     * Initializes a new instance of the IdempotentExecutor class.
     *
     * @param {Client} redis - The Redis client to be used for managing state and locks.
     */
    constructor(redis: Client);
    /**
     * Executes the provided action with idempotency, ensuring that it runs exactly once for a given idempotency key.
     *
     * @param {string} idempotencyKey - A unique key identifying the operation to ensure idempotency.
     * @param {() => Promise<T>} action - An asynchronous function representing the operation to execute idempotently.
     * @param {Partial<RunOptions<T>>} options - Optional. Configuration options for the execution.
     *    @property {number} options.timeout - Optional. The maximum duration, in milliseconds, that the concurrent operations will wait for the in-progress one to complete after which they will be terminated. Defaults to 60 seconds.
     *    @property {Serializer<T>} options.valueSerializer - Optional. Responsible for serializing the successful result of the action. Defaults to JSON serialization.
     *    @property {Serializer<Error>} options.errorSerializer - Optional. Used for serializing errors that may occur during the action's execution. Defaults to a error serializer that uses serialize-error-cjs.
     *    @property {(idempotencyKey: string, value: T) => T} options.onActionSuccess - Optional. A callback that is invoked when the action is executed successfully. It receives the idempotency key and the result of the action, and should return the result to be returned by the executor.
     *    @property {(idempotencyKey: string, error: Error) => Error} options.onActionError - Optional. A callback that is invoked when the action fails during execution. It receives the idempotency key and the error that occurred, and should return the error to be thrown by the executor.
     *    @property {(idempotencyKey: string, value: T) => T} options.onSuccessReplay - Optional. A callback that is invoked when a successful action is replayed. It receives the idempotency key and the result of the action, and should return the result to be returned by the executor.
     *    @property {(idempotencyKey: string, error: Error) => Error} options.onErrorReplay - Optional. A callback that is invoked when a failed action is replayed. It receives the idempotency key and the error that occurred, and should return the error to be thrown by the executor.
     *    @property {(error: Error) => boolean} options.shouldIgnoreError - Optional. A callback that is invoked when an error is encountered. If it returns `true`, the error will not be cached and will not be replayed.
     * @returns {Promise<T>} The result of the executed action.
     * @throws {IdempotentExecutorCriticalError} If saving the result to cache fails, potentially leading to non-idempotent executions.
     * @throws {IdempotentExecutorCacheError} If retrieving the cached result fails.
     * @throws {IdempotentExecutorSerializationError} If serializing or deserializing the cached result fails.
     * @throws {IdempotentExecutorCallbackError} If executing a callback fails.
     * @throws {IdempotentExecutorNonErrorWrapperError} If the action throws a non-error object.
     * @throws {IdempotentExecutorUnknownError} If an unknown error occurs during the idempotent execution.
     * @throws {Error} If the action throws an error.
     */
    run<T>(idempotencyKey: string, action: () => Promise<T>, options?: Partial<RunOptions<T>>): Promise<T>;
    /**
     * Retrieves the cached result of an idempotent operation.
     */
    private getCachedResult;
    /**
     * Replays a cached error, potentially transforming it using a callback.
     */
    private replayCachedError;
    /**
     * Replays a cached value, potentially transforming it using a callback.
     */
    private replayCachedValue;
    /**
     * Caches the result of an idempotent operation.
     */
    private cacheResult;
    /**
     * Throws an error that occurred during the execution of an idempotent operation,
     * potentially transforming it using a callback.
     */
    private throwError;
    /**
     * Returns the result of an idempotent operation,
     * potentially transforming it using a callback.
     */
    private returnResult;
}
export {};