@aws-lambda-powertools/idempotency/lib/esm/IdempotencyHandler.d.ts

The idempotency package for the Powertools for AWS Lambda (TypeScript) library. It provides options to make your Lambda functions idempotent and safe to retry.

import type { JSONValue, MiddyLikeRequest } from '@aws-lambda-powertools/commons/types';
import type { IdempotencyRecord } from './persistence/IdempotencyRecord.js';
import type { AnyFunction, IdempotencyHandlerOptions } from './types/IdempotencyOptions.js';
/**
 * @internal
 *
 * Class that handles the idempotency lifecycle.
 *
 * This class is used under the hood by the Idempotency utility
 * and provides several methods that are called at different stages
 * to orchestrate the idempotency logic.
 */
export declare class IdempotencyHandler<Func extends AnyFunction> {
    #private;
    constructor(options: IdempotencyHandlerOptions);
    /**
     * Takes an idempotency key and returns the idempotency record from the persistence layer.
     *
     * If a response hook is provided in the idempotency configuration, it will be called before returning the response.
     *
     * If the idempotency record is not COMPLETE, then it will throw an error based on the status of the record.
     *
     * @param idempotencyRecord The idempotency record stored in the persistence layer
     * @returns The result of the function if the idempotency record is in a terminal state
     */
    determineResultFromIdempotencyRecord(idempotencyRecord: IdempotencyRecord): JSONValue;
    /**
     * Execute the handler and return the result.
     *
     * If the handler fails, the idempotency record will be deleted.
     * If it succeeds, the idempotency record will be updated with the result.
     *
     * @returns The result of the function execution
     */
    getFunctionResult(): Promise<ReturnType<Func>>;
    /**
     * Entry point to handle the idempotency logic.
     *
     * Before the handler is executed, we need to check if there is already an
     * execution in progress for the given idempotency key. If there is, we
     * need to determine its status and return the appropriate response or
     * throw an error.
     *
     * If there is no execution in progress, we need to save a record to the
     * idempotency store to indicate that an execution is in progress.
     *
     * In some rare cases, when the persistent state changes in small time
     * window, we might get an `IdempotencyInconsistentStateError`. In such
     * cases we can safely retry the handling a few times.
     */
    handle(): Promise<ReturnType<Func>>;
    /**
     * Handle the idempotency operations needed after the handler has returned.
     *
     * When the handler returns successfully, we need to update the record in the
     * idempotency store to indicate that the execution has completed and
     * store its result.
     *
     * To avoid duplication of code, we expose this method so that it can be
     * called from the `after` phase of the Middy middleware.
     *
     * @param response The response returned by the handler.
     */
    handleMiddyAfter(response: unknown): Promise<void>;
    /**
     * Handle the idempotency operations needed after the handler has returned.
     *
     * Before the handler is executed, we need to check if there is already an
     * execution in progress for the given idempotency key. If there is, we
     * need to determine its status and return the appropriate response or
     * throw an error.
     *
     * If there is no execution in progress, we need to save a record to the
     * idempotency store to indicate that an execution is in progress.
     *
     * In some rare cases, when the persistent state changes in small time
     * window, we might get an `IdempotencyInconsistentStateError`. In such
     * cases we can safely retry the handling a few times.
     *
     * @param request The request object passed to the handler.
     * @param callback Callback function to cleanup pending middlewares when returning early.
     */
    handleMiddyBefore(request: MiddyLikeRequest, callback: (request: MiddyLikeRequest) => Promise<void>): Promise<ReturnType<Func> | undefined>;
    /**
     * Handle the idempotency operations needed when an error is thrown in the handler.
     *
     * When an error is thrown in the handler, we need to delete the record from the
     * idempotency store.
     *
     * To avoid duplication of code, we expose this method so that it can be
     * called from the `onError` phase of the Middy middleware.
     */
    handleMiddyOnError(): Promise<void>;
    /**
     * Setter for the payload to be hashed to generate the idempotency key.
     *
     * This is useful if you want to use a different payload than the one
     * used to instantiate the `IdempotencyHandler`, for example when using
     * it within a Middy middleware.
     *
     * @param functionPayloadToBeHashed The payload to be hashed to generate the idempotency key
     */
    setFunctionPayloadToBeHashed(functionPayloadToBeHashed: JSONValue): void;
    /**
     * Avoid idempotency if the eventKeyJmesPath is not present in the payload and throwOnNoIdempotencyKey is false
     */
    shouldSkipIdempotency(): boolean;
}
//# sourceMappingURL=IdempotencyHandler.d.ts.map