alepha/retry.d.ts

Alepha is a convention-driven TypeScript framework for building robust, end-to-end type-safe applications, from serverless APIs to full-stack React apps.

import { AlephaError, Descriptor, DescriptorArgs, KIND } from "alepha";
import { DateTimeProvider, DurationLike } from "alepha/datetime";

//#region src/descriptors/$retry.d.ts

/**
 * Creates a function that automatically retries a handler upon failure,
 * with support for exponential backoff, max duration, and cancellation.
 */
declare const $retry: {
  <T extends (...args: any[]) => any>(options: RetryDescriptorOptions<T>): RetryDescriptorFn<T>;
  [KIND]: typeof RetryDescriptor;
};
interface RetryDescriptorOptions<T extends (...args: any[]) => any> {
  /**
   * The function to retry.
   */
  handler: T;
  /**
   * The maximum number of attempts.
   *
   * @default 3
   */
  max?: number;
  /**
   * The backoff strategy for delays between retries.
   * Can be a fixed number (in ms) or a configuration object for exponential backoff.
   *
   * @default { initial: 200, factor: 2, jitter: true }
   */
  backoff?: number | RetryBackoffOptions;
  /**
   * An overall time limit for all retry attempts combined.
   *
   * e.g., `[5, 'seconds']`
   */
  maxDuration?: DurationLike;
  /**
   * A function that determines if a retry should be attempted based on the error.
   *
   * @default (error) => true (retries on any error)
   */
  when?: (error: Error) => boolean;
  /**
   * A custom callback for when a retry attempt fails.
   * This is called before the delay.
   */
  onError?: (error: Error, attempt: number, ...args: Parameters<T>) => void;
  /**
   * An AbortSignal to allow for external cancellation of the retry loop.
   */
  signal?: AbortSignal;
}
declare class RetryDescriptor<T extends (...args: any[]) => any> extends Descriptor<RetryDescriptorOptions<T>> {
  protected readonly dateTimeProvider: DateTimeProvider;
  protected appAbortController: AbortController;
  constructor(args: DescriptorArgs<RetryDescriptorOptions<T>>);
  run(...args: Parameters<T>): Promise<ReturnType<T>>;
}
interface RetryDescriptorFn<T extends (...args: any[]) => any> extends RetryDescriptor<T> {
  (...args: Parameters<T>): Promise<ReturnType<T>>;
}
interface RetryBackoffOptions {
  /**
   * Initial delay in milliseconds.
   *
   * @default 200
   */
  initial?: number;
  /**
   * Multiplier for each subsequent delay.
   *
   * @default 2
   */
  factor?: number;
  /**
   * Maximum delay in milliseconds.
   */
  max?: number;
  /**
   * If true, adds a random jitter to the delay to prevent thundering herd.
   *
   * @default true
   */
  jitter?: boolean;
}
//#endregion
//#region src/errors/RetryCancelError.d.ts
declare class RetryCancelError extends AlephaError {
  constructor();
}
//#endregion
//#region src/errors/RetryTimeoutError.d.ts
declare class RetryTimeoutError extends AlephaError {
  constructor(duration: number);
}
//#endregion
export { $retry, RetryBackoffOptions, RetryCancelError, RetryDescriptor, RetryDescriptorFn, RetryDescriptorOptions, RetryTimeoutError };
//# sourceMappingURL=index.d.ts.map