feat(async/unstable): add onRetry option to retry()

async/deno.json

@@ -14,6 +14,7 @@
     "./pool": "./pool.ts",
     "./unstable-pool": "./unstable_pool.ts",
     "./retry": "./retry.ts",
+    "./unstable-retry": "./unstable_retry.ts",
     "./tee": "./tee.ts",
     "./all-keyed": "./all_keyed.ts",
     "./unstable-abortable": "./unstable_abortable.ts",

async/unstable_retry.ts

@@ -0,0 +1,273 @@
+// Copyright 2018-2026 the Deno authors. MIT license.
+// This module is browser compatible.
+import { delay } from "./delay.ts";
+import { exponentialBackoffWithJitter } from "./_util.ts";
+import { RetryError } from "./retry.ts";
+
+/**
+ * Options for {@linkcode retry}.
+ *
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
+ */
+export interface RetryOptions {
+  /**
+   * How much to backoff after each retry.
+   *
+   * @default {2}
+   */
+  multiplier?: number;
+  /**
+   * The maximum milliseconds between attempts.
+   *
+   * @default {60000}
+   */
+  maxTimeout?: number;
+  /**
+   * The maximum amount of attempts until failure.
+   *
+   * @default {5}
+   */
+  maxAttempts?: number;
+  /**
+   * The initial and minimum amount of milliseconds between attempts.
+   *
+   * @default {1000}
+   */
+  minTimeout?: number;
+  /**
+   * Amount of jitter to introduce to the time between attempts. This is `1`
+   * for full jitter by default.
+   *
+   * @default {1}
+   */
+  jitter?: number;
+  /**
+   * Callback to determine if an error or other thrown value is retriable.
+   *
+   * @default {() => true}
+   *
+   * @param err The thrown error or other value.
+   * @returns `true` if the error is retriable, `false` otherwise.
+   */
+  isRetriable?: (err: unknown) => boolean;
+  /**
+   * An AbortSignal to cancel the retry operation.
+   *
+   * If the signal is aborted, the retry will stop and reject with the signal's
+   * reason. The signal is checked before each attempt and during the delay
+   * between attempts.
+   *
+   * @default {undefined}
+   */
+  signal?: AbortSignal;
+  /**
+   * Callback invoked when a retry is about to happen, immediately before
+   * waiting for the backoff delay.
+   *
+   * Called only when another attempt will follow: never for the terminal
+   * failure that becomes {@linkcode RetryError}, never for errors rejected
+   * by `isRetriable`, and never when `signal` is already aborted. An abort
+   * during the backoff wait can still cancel a retry after this callback
+   * has fired.
+   *
+   * The return value is ignored and not awaited. If the callback throws,
+   * {@linkcode retry} rejects with that error and makes no further attempts.
+   *
+   * @default {undefined}
+   *
+   * @param error The error or other value thrown by the failed attempt.
+   * @param attempt The 1-based number of the attempt that just failed,
+   * ranging from `1` to `maxAttempts - 1`.
+   * @param delay The number of milliseconds to wait before the next attempt,
+   * after backoff and jitter have been applied.
+   */
+  onRetry?: (error: unknown, attempt: number, delay: number) => void;
+}
+
+/**
+ * Calls the given (possibly asynchronous) function up to `maxAttempts` times.
+ * Retries as long as the given function throws. If the attempts are exhausted,
+ * throws a {@linkcode RetryError} with `cause` set to the inner exception.
+ *
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
+ *
+ * The backoff is calculated by multiplying `minTimeout` with `multiplier` to the power of the current attempt counter (starting at 0 up to `maxAttempts - 1`). It is capped at `maxTimeout` however.
+ * How long the actual delay is, depends on `jitter`.
+ *
+ * When `jitter` is the default value of `1`, waits between two attempts for a
+ * randomized amount between 0 and the backoff time. With the default options
+ * the maximal delay will be `15s = 1s + 2s + 4s + 8s`. If all five attempts
+ * are exhausted the mean delay will be `9.5s = ½(4s + 15s)`.
+ *
+ * When `jitter` is `0`, waits the full backoff time.
+ *
+ * @example Example configuration 1
+ * ```ts no-assert
+ * import { retry } from "@std/async/unstable-retry";
+ * const req = async () => {
+ *  // some function that throws sometimes
+ * };
+ *
+ * // Below resolves to the first non-error result of `req`
+ * const retryPromise = await retry(req, {
+ *  multiplier: 2,
+ *  maxTimeout: 60000,
+ *  maxAttempts: 5,
+ *  minTimeout: 100,
+ *  jitter: 1,
+ * });
+ * ```
+ *
+ * @example Example configuration 2
+ * ```ts no-assert
+ * import { retry } from "@std/async/unstable-retry";
+ * const req = async () => {
+ *  // some function that throws sometimes
+ * };
+ *
+ * // Make sure we wait at least 1 minute, but at most 2 minutes
+ * const retryPromise = await retry(req, {
+ *  multiplier: 2.34,
+ *  maxTimeout: 80000,
+ *  maxAttempts: 7,
+ *  minTimeout: 1000,
+ *  jitter: 0.5,
+ * });
+ * ```
+ *
+ * @example Only retry on specific error types
+ * ```ts no-assert
+ * import { retry } from "@std/async/unstable-retry";
+ *
+ * class HttpError extends Error {
+ *   status: number;
+ *   constructor(status: number) {
+ *     super(`HTTP ${status}`);
+ *     this.status = status;
+ *   }
+ * }
+ *
+ * const req = async () => {
+ *   // some function that throws HttpError
+ * };
+ *
+ * // Only retry on 429 (rate limit) or 5xx (server) errors
+ * const retryPromise = await retry(req, {
+ *   isRetriable: (err) =>
+ *     err instanceof HttpError && (err.status === 429 || err.status >= 500),
+ * });
+ * ```
+ *
+ * @example Observing retries with `onRetry`
+ * ```ts
+ * import { retry } from "@std/async/unstable-retry";
+ * import { assertEquals } from "@std/assert";
+ *
+ * let attempts = 0;
+ * const logs: string[] = [];
+ *
+ * const result = await retry(() => {
+ *   attempts++;
+ *   if (attempts < 3) throw new Error("Service unavailable");
+ *   return "ok";
+ * }, {
+ *   minTimeout: 1,
+ *   jitter: 0,
+ *   onRetry(_error, attempt, delay) {
+ *     logs.push(`Attempt ${attempt} failed, retrying in ${delay}ms`);
+ *   },
+ * });
+ *
+ * assertEquals(result, "ok");
+ * assertEquals(logs, [
+ *   "Attempt 1 failed, retrying in 1ms",
+ *   "Attempt 2 failed, retrying in 2ms",
+ * ]);
+ * ```
+ *
+ * @typeParam T The return type of the function to retry and returned promise.
+ * @param fn The function to retry.
+ * @param options Additional options.
+ * @returns The promise that resolves with the value returned by the function to retry.
+ * @throws {RetryError} If the function fails after `maxAttempts` attempts.
+ * @throws If the `signal` is aborted, throws the signal's reason.
+ * @throws If `isRetriable` returns `false` for an error, throws that error immediately.
+ * @throws If `onRetry` throws, throws that error without further attempts.
+ */
+export async function retry<T>(
+  fn: (() => Promise<T>) | (() => T),
+  options?: RetryOptions,
+): Promise<T> {
+  const {
+    multiplier = 2,
+    maxTimeout = 60000,
+    maxAttempts = 5,
+    minTimeout = 1000,
+    jitter = 1,
+    isRetriable = () => true,
+    signal,
+    onRetry,
+  } = options ?? {};
+
+  if (!Number.isInteger(maxAttempts) || maxAttempts < 1) {
+    throw new RangeError(
+      `Cannot retry as 'maxAttempts' must be a positive integer: current value is ${maxAttempts}`,
+    );
+  }
+  if (!Number.isFinite(multiplier) || multiplier < 1) {
+    throw new RangeError(
+      `Cannot retry as 'multiplier' must be a finite number >= 1: current value is ${multiplier}`,
+    );
+  }
+  if (Number.isNaN(maxTimeout) || maxTimeout <= 0) {
+    throw new RangeError(
+      `Cannot retry as 'maxTimeout' must be a positive number: current value is ${maxTimeout}`,
+    );
+  }
+  if (Number.isNaN(minTimeout) || minTimeout < 0) {
+    throw new RangeError(
+      `Cannot retry as 'minTimeout' must be >= 0: current value is ${minTimeout}`,
+    );
+  }
+  if (minTimeout > maxTimeout) {
+    throw new RangeError(
+      `Cannot retry as 'minTimeout' must be <= 'maxTimeout': current values 'minTimeout=${minTimeout}', 'maxTimeout=${maxTimeout}'`,
+    );
+  }
+  if (Number.isNaN(jitter) || jitter < 0 || jitter > 1) {
+    throw new RangeError(
+      `Cannot retry as 'jitter' must be between 0 and 1: current value is ${jitter}`,
+    );
+  }
+
+  let attempt = 0;
+  while (true) {
+    signal?.throwIfAborted();
+
+    try {
+      return await fn();
+    } catch (error) {
+      if (!isRetriable(error)) {
+        throw error;
+      }
+
+      if (attempt + 1 >= maxAttempts) {
+        throw new RetryError(error, maxAttempts);
+      }
+
+      // An aborted signal means no retry follows, so onRetry must not fire.
+      signal?.throwIfAborted();
+
+      const timeout = exponentialBackoffWithJitter(
+        maxTimeout,
+        minTimeout,
+        attempt,
+        multiplier,
+        jitter,
+      );
+      onRetry?.(error, attempt + 1, timeout);
+      await delay(timeout, signal ? { signal } : undefined);
+    }
+    attempt++;
+  }
+}