alepha/dist/retry/index.d.ts

Easy-to-use modern TypeScript framework for building many kind of applications.

import { AlephaError, Middleware, Primitive, PrimitiveArgs } from "alepha";
import { DateTimeProvider, DurationLike } from "alepha/datetime";
//#region ../../src/retry/errors/RetryCancelError.d.ts
declare class RetryCancelError extends AlephaError {
  constructor();
}
//#endregion
//#region ../../src/retry/errors/RetryTimeoutError.d.ts
declare class RetryTimeoutError extends AlephaError {
  constructor(duration: number);
}
//#endregion
//#region ../../src/retry/providers/RetryProvider.d.ts
interface RetryOptions<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;
  /**
   * An additional AbortSignal to combine with the provided signal.
   * Used internally by $retry to handle app lifecycle.
   */
  additionalSignal?: AbortSignal;
}
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;
}
/**
 * Service for executing functions with automatic retry logic.
 * Supports exponential backoff, max duration, conditional retries, and cancellation.
 */
declare class RetryProvider {
  protected readonly log: import("alepha/logger").Logger;
  protected readonly dateTime: DateTimeProvider;
  /**
   * Execute a function with automatic retry logic.
   */
  retry<T extends (...args: any[]) => any>(options: RetryOptions<T>, ...args: Parameters<T>): Promise<ReturnType<T>>;
  /**
   * Calculate the backoff delay for a given attempt.
   */
  protected calculateBackoff(attempt: number, options?: number | RetryBackoffOptions): number;
}
//#endregion
//#region ../../src/retry/primitives/$retry.d.ts
/**
 * Retry middleware for `use` arrays in `$action`, `$job`, `$page`, `$pipeline`.
 *
 * Retries the handler on failure with configurable backoff, max attempts, and
 * conditional retry via `when`. Aborts on application shutdown.
 *
 * ```ts
 * processOrder = $action({
 *   use: [$retry({ max: 3, backoff: { initial: 500 } })],
 *   handler: async ({ body }) => { ... },
 * });
 * ```
 */
declare const $retry: (options?: RetryMiddlewareOptions) => Middleware;
interface RetryPrimitiveOptions<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;
}
/**
 * Options for $retry in middleware mode (no handler).
 */
interface RetryMiddlewareOptions {
  /**
   * The maximum number of attempts.
   *
   * @default 3
   */
  max?: number;
  /**
   * The backoff strategy for delays between retries.
   *
   * @default { initial: 200, factor: 2, jitter: true }
   */
  backoff?: number | RetryBackoffOptions;
  /**
   * An overall time limit for all retry attempts combined.
   */
  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.
   */
  onError?: (error: Error, attempt: number) => void;
  /**
   * An AbortSignal to allow for external cancellation of the retry loop.
   */
  signal?: AbortSignal;
}
declare class RetryPrimitive<T extends (...args: any[]) => any> extends Primitive<RetryPrimitiveOptions<T>> {
  protected readonly retryProvider: RetryProvider;
  protected appAbortController?: AbortController;
  constructor(args: PrimitiveArgs<RetryPrimitiveOptions<T>>);
  run(...args: Parameters<T>): Promise<ReturnType<T>>;
}
interface RetryPrimitiveFn<T extends (...args: any[]) => any> extends RetryPrimitive<T> {
  (...args: Parameters<T>): Promise<ReturnType<T>>;
}
//#endregion
//#region ../../src/retry/index.d.ts
/**
 * Automatic retry with backoff.
 *
 * **Features:**
 * - Retry configuration
 * - Exponential backoff
 * - Max retry limits
 * - Custom retry predicates
 *
 * @module alepha.retry
 */
declare const AlephaRetry: import("alepha").Service<import("alepha").Module>;
//#endregion
export { $retry, AlephaRetry, RetryBackoffOptions, RetryCancelError, RetryMiddlewareOptions, RetryOptions, RetryPrimitive, RetryPrimitiveFn, RetryPrimitiveOptions, RetryProvider, RetryTimeoutError };
//# sourceMappingURL=index.d.ts.map