agents/dist/retries-D9B2UCq3.d.ts

A home for your AI agents

//#region src/retries.d.ts
/**
 * Retry options for schedule(), scheduleEvery(), queue(), and this.retry().
 */
interface RetryOptions {
  /** Max number of attempts (including the first). Default: 3 */
  maxAttempts?: number;
  /** Base delay in ms for exponential backoff. Default: 100 */
  baseDelayMs?: number;
  /** Max delay cap in ms. Default: 3000 */
  maxDelayMs?: number;
}
/**
 * Internal options for tryN -- extends RetryOptions with a shouldRetry predicate.
 */
interface TryNOptions extends RetryOptions {
  /**
   * Predicate to determine if an error should be retried.
   * Receives the error and the next attempt number (so callers can
   * make attempt-aware decisions).
   * If not provided, all errors are retried.
   */
  shouldRetry?: (err: unknown, nextAttempt: number) => boolean;
}
/**
 * Validate retry options eagerly so invalid config fails at enqueue/schedule time
 * rather than at execution time. Checks individual field ranges, enforces integer
 * maxAttempts, and validates cross-field constraints after resolving against
 * defaults when provided.
 */
/** Fill unset per-call retry options from a required set of defaults. */
declare function resolveRetryConfig(
  retry: RetryOptions | undefined,
  defaults: Required<RetryOptions>
): Required<RetryOptions>;
declare function validateRetryOptions(
  options: RetryOptions,
  defaults?: Required<RetryOptions>
): void;
/**
 * Returns the number of milliseconds to wait before retrying a request.
 * Uses the "Full Jitter" approach from
 * https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/
 *
 * @param attempt The current attempt number (1-indexed).
 * @param baseDelayMs Base delay multiplier in ms.
 * @param maxDelayMs Maximum delay cap in ms.
 * @returns Milliseconds to wait before retrying.
 */
declare function jitterBackoff(
  attempt: number,
  baseDelayMs: number,
  maxDelayMs: number
): number;
/**
 * Retry an async function up to `n` total attempts with jittered exponential backoff.
 *
 * @param n Total number of attempts (must be a finite integer >= 1).
 * @param fn The async function to retry. Receives the current attempt number (1-indexed).
 * @param options Retry configuration.
 * @returns The result of `fn` on success.
 * @throws The last error if all attempts fail or `shouldRetry` returns false.
 */
declare function tryN<T>(
  n: number,
  fn: (attempt: number) => Promise<T>,
  options?: TryNOptions
): Promise<T>;
/**
 * Returns true if the given error is retryable according to Durable Object error handling.
 * See https://developers.cloudflare.com/durable-objects/best-practices/error-handling/
 *
 * An error is retryable if it has `retryable: true` but is NOT an overloaded error.
 */
declare function isErrorRetryable(err: unknown): boolean;
/**
 * Whether an error (or anything in its `cause` chain) is a transient
 * "superseded isolate" failure — see `SUPERSEDED_ISOLATE_PATTERN`. In-process
 * retries are futile for this class; the work must be deferred to a fresh
 * invocation, which runs the new code and succeeds.
 */
declare function isDurableObjectCodeUpdateReset(error: unknown): boolean;
/**
 * Whether an error (or anything in its `cause` chain) carries the exact
 * Durable Object storage-reset platform fragment. Generic SQL/internal errors
 * deliberately do not qualify.
 */
declare function isDurableObjectStorageReset(error: unknown): boolean;
/**
 * Whether an error (or anything in its `cause` chain, or a raw error-message
 * string) is a Durable Object memory-limit reset — see
 * {@link MEMORY_LIMIT_RESET_PATTERN}. Unlike {@link isPlatformTransientError},
 * re-running the same work re-OOMs deterministically, so callers must NOT defer
 * it like a transient; they should bound retries tightly and then seal (#1825).
 */
declare function isDurableObjectMemoryLimitReset(error: unknown): boolean;
/**
 * Whether an error (or anything in its `cause` chain) is a transient failure
 * of the PLATFORM rather than of the code that threw it:
 *
 *   - a superseded-isolate reset ("reset because its code was updated" /
 *     "this script has been upgraded") — a deploy replaced the isolate;
 *   - an error the platform itself flags `retryable: true` (excluding
 *     overloaded errors, where retrying the same object won't help) — see
 *     `isErrorRetryable`;
 *   - "Network connection lost." — the storage/stub connection dropped. The
 *     CF `retryable` flag does not survive error wrappers (e.g. `SqlError`
 *     copies only the message + `cause`) and is absent in some local-dev
 *     shapes, so the verbatim message is matched as well;
 *   - the exact "Internal error in Durable Object storage caused object to be
 *     reset" platform fragment. Generic internal and SQL errors remain fatal.
 *
 * Used to decide whether failed work should be RE-RUN LATER (platform
 * transient — the same work succeeds once the platform recovers, typically
 * seconds after a deploy) versus ABANDONED as genuinely failing (application
 * error — re-running yields the same failure). A genuine application error
 * carries none of these signals, so it is never misclassified by this check.
 */
/**
 * Whether a failure is the PLATFORM's rather than the application's — any
 * platform transient (see {@link isPlatformTransientError}, which includes
 * superseded-isolate resets) or a memory-limit reset. Failed work in this
 * class must be PRESERVED and deferred, never completed as an application
 * failure. The two sub-classes defer differently: transients re-run
 * indefinitely (the platform recovers), while memory-limit deferral is
 * bounded by the alarm circuit breaker (#1825).
 */
declare function isPlatformFailure(error: unknown): boolean;
declare function isPlatformTransientError(error: unknown): boolean;
//#endregion
export {
  isErrorRetryable as a,
  jitterBackoff as c,
  validateRetryOptions as d,
  isDurableObjectStorageReset as i,
  resolveRetryConfig as l,
  isDurableObjectCodeUpdateReset as n,
  isPlatformFailure as o,
  isDurableObjectMemoryLimitReset as r,
  isPlatformTransientError as s,
  RetryOptions as t,
  tryN as u
};
//# sourceMappingURL=retries-D9B2UCq3.d.ts.map