Skip to content
@sandlada/result

reliability

{/* @generated by scripts/sync-content.mjs; do not edit */}

@sandlada/result/reliability — retry, timeout and concurrency primitives for production pipelines.

Scope

Section titled “Scope”
  • Operates on: AsyncResult thunks (plus one eager retry entry point). This is the only async layer that never rejects.
  • Execution model: retry and timeoutEager are eager; retryLazy, timeout, race, any and allSettled are lazy and run on .run().
  • Not here: general async operators (async-result, promise-result).

API

Section titled “API”

Retry

Section titled “Retry”
Export Description Source
retry Eager bounded retry; resolves IResultOfT<T, E | TE | AE> and never rejects. retry.ts
retryLazy Lazy thunk wrap of retry with the same error contract. retryLazy.ts
RetryOptions (type) times, delayMs, shouldRetry, onRetry, signal, onThrow, onAborted. retry.ts
ThrownError (type) Default TE — { kind: 'Thrown', thrown }, preserving the thrown value verbatim. retry.ts
AbortedError (type) Default AE — { kind: 'Aborted', reason, times } when the loop never runs fn. retry.ts

Timeout

Section titled “Timeout”
Export Description Source
timeout Lazily races an AsyncResult against setTimeout; the default error is { kind: 'Timeout', ms }. timeout.ts
timeoutEager Eager counterpart of timeout. timeoutEager.ts
TimeoutError (type) Default timeout error shape; replace it through onTimeout. timeout.ts

Concurrency

Section titled “Concurrency”
Export Description Source
race First Ok wins; if all fail, the lowest input index wins; an empty array becomes Err(EmptyInputsError) unless onEmpty overrides it. race.ts
EmptyInputsError (type) Default error for an empty race input. race.ts
any Runs everything; returns all successes, or all errors when none succeed (rejections tagged { kind: 'Rejected' }). any.ts
AnyError (type) Error channel of any — E or the { kind: 'Rejected', error: unknown } rejection envelope. any.ts
allSettled Always Ok: every thunk’s outcome in input order. allSettled.ts
Settled (type) Per-thunk outcome: { ok: true, value }, { ok: false, error } or { ok: false, kind: 'Rejected', error }. allSettled.ts

Contract notes

Section titled “Contract notes”
  • NeverRejects: synchronous throws, async rejections and throwing hooks are all collapsed into Err. This is a stronger guarantee than the promise-* / async-* layers. A carrier that breaks the AsyncResult contract at runtime - its run() resolves with something that is not a Result - is treated as an upstream contract violation and reported through the error channel too, never as a rejection.
  • retry keeps error channels additive: E from your fn, TE when something throws (ThrownError by default), AE when the loop never runs fn (AbortedError by default). Supply onThrow / onAborted to fold them into your own E. A fn that resolves with a non-Result is reported through the TE channel.
  • A non-finite delayMs is clamped before it reaches the timer: an infinite delay becomes the maximum timer interval, NaN becomes zero.
  • A non-finite or out-of-range ms is clamped the same way before it reaches the timer, so timeout(Infinity, …) no longer expires after 1 ms. The effective duration is the one passed to onTimeout and carried by the default { kind: 'Timeout', ms } error.
  • A timeout cannot cancel the inner operation: after Err(onTimeout(ms)) the inner run() keeps executing and its settlement is discarded.
  • race policy: the first Ok wins regardless of order; among errors the lowest input index wins; a genuine Err outranks a Promise rejection. A statically non-empty array keeps error type E; a dynamically-sized array widens to E \| EE.
  • See behavior-modes.md §4.8 for the per-export table.
Section titled “Related”
  • async-result — the carrier all wrappers consume or return.
  • primitives — sequenceAsyncResult for ordered batch execution.