API · Flow

`rateLimit()`

Emit up to a fixed number of values per local time window, delaying rather than dropping excess input.

Example

const apiCalls = exstream(requests).rateLimit({
  limit: 100,
  interval: 60_000,
})

Parameters

options

Type RateLimitOptionsRequired

Named rate-window settings.

options.limit

Type positive integerRequired

Maximum successful values emitted in one window.

options.interval

Type non-negative finite numberRequired

Window duration in milliseconds. Zero effectively allows continuous delivery.

Window behavior

The first successful value after creation or an idle interval starts a local window. Up to limit values in that window pass immediately. The next value waits until the monotonic window deadline, becomes the first value of the next window, and only then allows upstream to continue. Successful values are neither dropped nor reordered.

If input stays idle past the deadline, the next value starts a fresh window. A timer wake-up rechecks the deadline before releasing its waiting value, so an early timer cannot exceed the configured window.

This is a per-operator burst limiter. It does not coordinate quotas across processes or clients, and it does not guarantee a maximum inside every possible sliding interval. For a strict shared, sliding-window, or token-bucket API quota, use a shared limiter or configure this local limit conservatively.

Pressure, errors, and cancellation

At most one excess value and one timer are retained, so operator memory is constant and the wait becomes upstream backpressure. Existing record errors pass immediately and do not consume the successful-value quota. Ending, aborting, or destroying the branch clears a pending timer.

Errors

An invalid options object, limit, or interval throws when the operator is created. The JavaScript runtime performs numeric coercion for both numeric fields; TypeScript accepts numbers only.

Forms

stream.rateLimit({ limit: 100, interval: 60_000 })
exstream.pipeline().rateLimit({ limit: 100, interval: 60_000 })

Signature

interface RateLimitOptions {
  limit: number
  interval: number
}

rateLimit(options: RateLimitOptions): Exstream<T, C>

throttle(), makeAsync(), mapAsync()

rateLimit()