retry-async

Execute an operation with bounded, abortable retries and deterministic delay policy.


Package	`@vizejs/composable/retry-async`
Own the source	`vize lib pull composable:retry-async`
Runtime exports	`retryAsync`
Gzip budget	5632 B

Usage

import { retryAsync } from "@vizejs/composable/retry-async";

Runtime contract

Utility	Category	Stability	SSR	Hydration	Cleanup	Targets	Host globals	Uses
`retryAsync`	async	experimental	safe	not-applicable	returned-value	web, server, worker, native, desktop, terminal	`AbortController`	`timeoutAbortSignal`, `calculateRetryDelay`

API

`retryAsync`

Execute an operation with bounded, abortable retries and deterministic delay policy. Synchronous throws and asynchronous rejections follow the same path. A successful value is returned unchanged. Exhaustion rejects with the final operation error, a negative retry decision rejects with the error that was evaluated, and cancellation rejects with the signal's exact reason. These values are deliberately not wrapped. Cancellation races every asynchronous stage, so callers are not forced to wait for an operation or hook that ignores its signal. Late settlements are still observed internally and cannot become unhandled rejections. Backoff options and entropy are evaluated lazily only after a failure is approved for retry.

async function retryAsync<Value>( operation: (context: RetryAttemptContext) => Value | PromiseLike<Value>, options: RetryAsyncOptions = {}, ): Promise<Value>

Types

`RetryAttemptContext`

Context supplied to every invocation of a retried operation.

Member	Type	Description
`attempt`	`number`	One-based operation attempt, including the initial call.
`signal`	`AbortSignal`	Shared cancellation signal for the complete retry execution.

`RetryFailureContext`

Context supplied after an operation fails and before retry policy runs.

Member	Type	Description
`attempt`	`number`	One-based operation attempt, including the initial call.
`signal`	`AbortSignal`	Shared cancellation signal for the complete retry execution.
`error`	`unknown`	Exact value thrown or rejected by the failed operation.
`retryAttempt`	`number`	One-based retry that would follow this failure.

`RetryScheduledContext`

Context supplied when an approved retry is about to wait.

Member	Type	Description
`attempt`	`number`	One-based operation attempt, including the initial call.
`signal`	`AbortSignal`	Shared cancellation signal for the complete retry execution.
`error`	`unknown`	Exact value thrown or rejected by the failed operation.
`retryAttempt`	`number`	One-based retry that would follow this failure.
`nextAttempt`	`number`	One-based operation attempt that will run after the wait.
`delayMs`	`number`	Calculated backoff delay in integer milliseconds.

`RetryAsyncOptions`

Options for retryAsync.

Member	Type	Description
`initialDelayMs`?	`number`	Delay before the first retry, in milliseconds.
`multiplier`?	`number`	Exponential multiplier applied for each subsequent retry. Values may be fractional but must be finite and at least one. The calculated delay is rounded up so a retry never starts earlier than the requested backoff.
`maximumDelayMs`?	`number`	Inclusive ceiling for the calculated delay, in milliseconds. The ceiling may be lower than `RetryDelayOptions.initialDelayMs`; in that case it also caps the first retry.
`jitterRatio`?	`number`	Fraction of the capped delay eligible for downward jitter. `0` is deterministic exponential backoff, `0.5` samples from the upper half of the range, and `1` applies full jitter from zero through the capped delay. Jitter never exceeds the unjittered delay.
`random`?	`() => number`	Entropy source returning a number in the half-open interval `[0, 1)`. It is called exactly once when the selected jitter range contains more than one integer millisecond, and is otherwise not read.
`maximumRetries`?	`number`	Maximum retries after the initial operation attempt.
`signal`?	`AbortSignal`	Cancels the active operation, policy hook, notification hook, or backoff wait. The returned promise rejects with the signal's exact reason.
`scheduler`?	`TimeoutScheduler`	Deterministic or host-specific scheduler used for backoff waits.
`shouldRetry`?	`(context: RetryFailureContext) => boolean \| PromiseLike<boolean>`	Decide whether an operation failure is retryable. Returning `false` rejects with the original operation error without calculating a delay. The decision may be asynchronous and remains abortable.
`onRetry`?	`(context: RetryScheduledContext) => void \| PromiseLike<void>`	Observe an approved retry before its backoff wait begins. The hook may be asynchronous and remains abortable; a hook failure is propagated exactly and the next operation attempt is not started.