Skip to main content

@rtorcato/js-common / promises

promises

Type Aliases​

RetryOptions​

RetryOptions = object

Defined in: promises/index.ts:53

Options for retry. Every field is optional.

Properties​

retries?​

optional retries?: number

Defined in: promises/index.ts:55

Retries after the first attempt, so retries + 1 attempts in total. Default 3.

minDelay?​

optional minDelay?: number

Defined in: promises/index.ts:57

Base delay in ms; the cap doubles each retry (minDelay * 2 ** (attempt - 1)). Default 100.

maxDelay?​

optional maxDelay?: number

Defined in: promises/index.ts:59

Upper bound on a single wait, in ms. Default 10_000.

jitter?​

optional jitter?: boolean

Defined in: promises/index.ts:61

Full jitter: wait a random 0..cap instead of the full cap. Default true.

shouldRetry?​

optional shouldRetry?: (err, attempt) => boolean

Defined in: promises/index.ts:63

Return false to stop retrying and reject with err. Default: retry every error.

Parameters​
err​

unknown

attempt​

number

Returns​

boolean

signal?​

optional signal?: AbortSignal

Defined in: promises/index.ts:65

Stops further attempts and aborts the wait; the promise rejects with signal.reason.

Functions​

to()​

to<T>(promise): Promise<[unknown, T | undefined]>

Defined in: promises/index.ts:21

Wraps a promise and returns a tuple [error, result]. The error slot is unknown — narrow it at the call site before touching its properties.

Example​

const [err, value] = await to(Promise.resolve(42))
// err = null, value = 42

const [err2, value2] = await to(Promise.reject(new Error('boom')))
const message = err2 instanceof Error ? err2.message : String(err2)
// message = 'boom', value2 = undefined

Type Parameters​

T​

T

Parameters​

promise​

Promise<T>

The promise to wrap.

Returns​

Promise<[unknown, T | undefined]>

withTimeout()​

withTimeout<T>(promise, ms, error?): Promise<T>

Defined in: promises/index.ts:44

Returns a promise that rejects after a timeout if the input promise does not resolve.

Example​

await withTimeout(delay(10).then(() => 'fast'), 100) // 'fast'
await withTimeout(delay(500), 100) // rejects with Error('Timeout')

Type Parameters​

T​

T

Parameters​

promise​

Promise<T>

The promise to race.

ms​

number

Timeout in milliseconds.

error?​

any = ...

Optional error to throw on timeout.

Returns​

Promise<T>

retry()​

retry<T>(fn, opts?): Promise<T>

Defined in: promises/index.ts:86

Runs fn until it resolves, retrying rejections with exponential backoff and full jitter. attempt is 1-based. Rejects with the last error once retries run out or shouldRetry says no, or with signal.reason if the signal aborts.

Example​

const report = await retry((attempt, signal) => fetch('/api/report', { signal }), {
  retries: 4,
  shouldRetry: (err) => !(err instanceof HttpError) || err.status >= 500,
  signal: AbortSignal.timeout(30_000),
})

Type Parameters​

T​

T

Parameters​

fn​

(attempt, signal?) => Promise<T>

The operation to run; receives the attempt number and the caller's signal.

opts?​

RetryOptions = {}

Retry count, backoff bounds, jitter, retry predicate and abort signal.

Returns​

Promise<T>

mapLimit()​

mapLimit<T, R>(items, limit, fn): Promise<R[]>

Defined in: promises/index.ts:127

Maps items through an async fn with at most limit calls in flight, resolving to the results in input order. On the first rejection no new calls are started and the returned promise rejects with that error, like Promise.all; calls already in flight are not cancelled.

Example​

const users = await mapLimit(ids, 4, (id) => getUser(id))

Type Parameters​

T​

T

R​

R

Parameters​

items​

Iterable<T>

The values to map.

limit​

number

Maximum number of concurrent calls — a positive integer.

fn​

(item, index) => Promise<R>

Async mapper, called with each item and its index.

Returns​

Promise<R[]>

Throws​

If limit is not a positive integer (the promise rejects).