API reference

The declaration files shipped with the package document every type with examples. The generated TypeDoc reference renders them.

createValveCopy Anchor Link

function createValve(options: ValveOptions): Valve;

Creates a valve. Throws ValveError with code INVALID_OPTIONS if an option is invalid. At least one of rate or a finite concurrency is required.

ValveOptionsCopy Anchor Link

RateRuleCopy Anchor Link

Unnamed rules cannot share the same algorithm and interval. Set a unique name to distinguish rules with matching algorithms and intervals. Scoped rules require names and select a job identity through scope. Both fields accept 1-64 ASCII letters, digits, underscores or hyphens, beginning with a letter. See Scoped rate limits. Scoped configurations support at most 16 rules and batch 128 (default 32).

ConcurrencyOptionsCopy Anchor Link

Global scope requires a store that implements release and renew. Both built-in stores do.

DurationCopy Anchor Link

A number of milliseconds, or a string ending in ms, s, m, or h. Decimals are allowed.

250; // 250 ms
('1.5s'); // 1500 ms
('10m'); // 600000 ms
('24h'); // 86400000 ms

Negative values, NaN, Infinity, and unknown units are rejected.

ValveCopy Anchor Link

runCopy Anchor Link

run<R>(fn: (ctx: JobContext) => R, options?: RunOptions<Awaited<R>>): Promise<Awaited<R>>

Queues fn and calls it when every rule and the concurrency limit allow. Resolves or rejects with whatever fn returns or throws. fn receives { signal }, the signal from options.signal (or the lease signal under global concurrency). run never throws synchronously, and never calls fn synchronously.

RunOptionsCopy Anchor Link

wrapCopy Anchor Link

wrap<A extends unknown[], R>(fn: (...args: A) => R, options?: Omit<RunOptions, 'signal'>): (...args: A) => Promise<Awaited<R>>

Returns a function with the same parameters as fn. Each call goes through the valve with options.

wrapFetchCopy Anchor Link

wrapFetch<F extends FetchLike = typeof fetch>(fetchImpl?: F, options?: WrapFetchOptions<F>): F

Returns a function with the same type as fetchImpl (default globalThis.fetch). It queues each request, observes each response, and retries eligible rate limit responses for GET, HEAD, OPTIONS, PUT and DELETE by default. See Respect provider feedback.

WrapFetchOptionsCopy Anchor Link

The request's abort signal, from init.signal or the Request, cancels queued attempts and is passed to fetchImpl for running ones. It also cancels a running Request body probe before fetch begins.

retries counts additional attempts after the initial request. The default of 2 permits up to three total requests. Once the retry limit is exhausted, the final response is returned unchanged.

init.method overrides the Request method; otherwise the method defaults to GET. POST, PATCH and unrecognized methods do not retry unless retryUnsafeMethods: true. A supplied idempotency key does not opt in. All responses still update shared cooldowns. Streamed init.body requests never retry, including with the opt-in enabled. Use a dedicated wrapper for verified operations; see the compatibility notes.

Inherited Request bodies retry only if a probe clone fits within maxReplayBodySize. Probing occurs after admission, holds the concurrency slot, and delays upload until the body ends or exceeds the limit. Larger bodies and bodies exceeding 1,024 chunks are sent once. Empty chunks count toward this second limit. The probe can retain the limit plus one source chunk and stream prefetch. Set maxReplayBodySize: 0 to skip probing and send Request bodies once. Explicit init.body overrides bypass probing of the unused body. See Request bodies.

observeCopy Anchor Link

observe(response: ResponseLike): void

Reads a response with the valve's feedback reader. If it asks for a pause, writes a shared pause in the background. Safe to call with any response.

pauseCopy Anchor Link

pause(duration: Duration): Promise<void>

Pauses the valve in every process sharing it. Only extends an existing pause. Resolves once the store records it. Not capped by maxPause.

resumeCopy Anchor Link

resume(): Promise<void>

Ends the current pause in every process sharing the valve.

statsCopy Anchor Link

stats(): ValveStats

Returns a snapshot for this process. See Monitor a valve.

onCopy Anchor Link

on<E extends keyof ValveEventMap>(event: E, listener: (payload: ValveEventMap[E]) => void): () => void

Adds a listener and returns a function that removes it. See Events.

idleCopy Anchor Link

idle(): Promise<void>

Resolves when nothing is queued or running in this process.

closeCopy Anchor Link

close(options?: { drain?: boolean }): Promise<void>

Stops accepting jobs. Without drain, queued jobs reject with CLOSED. With drain: true, they run first. Resolves when running jobs finish. Repeated calls return the same promise. Never closes a client you supplied.

Valves also implement [Symbol.asyncDispose], which calls close().

idCopy Anchor Link

readonly id: string

The id passed to createValve.

Other exportsCopy Anchor Link

memoryStore accepts { clock?: () => number }, a source of epoch milliseconds. It defaults to Date.now.