Throttle

Add throttle to a stitch when you need to stay under an API's rate limit and keep in-flight requests bounded — it spaces calls to a target rate and caps how many run at once, before any request leaves.

Example

import { stitch } from 'stitchapi';

const search = stitch({
    baseUrl: 'https://api.example.com',
    path: '/search',
    throttle: { rate: '5/s', concurrency: 2, pool: 'host' },
});

Calls to search() are spaced to five per second with at most two running concurrently. When a call has to wait, the stitch emits a progress event with phase throttled, so a waiting call is visible on the event stream rather than silently stalled.

Options

rate is a string like "5/s" — a minimum spacing between successive calls, not a token bucket. concurrency caps simultaneous in-flight calls; either may be set on its own.

When the rate is all you need, pass it directly — a bare string is shorthand for rate, exactly like timeout: '5s' is shorthand for timeout: { total: '5s' }:

import { stitch } from 'stitchapi';

const ping = stitch({
    url: 'https://api.example.com/ping',
    throttle: '1/s', // ≡ { rate: '1/s' }
});

The shorthand expands at compose time, so __config.throttle always reads back as the object form, and a throttle: '1/s' layered over an inherited { rate: '5/s', concurrency: 2 } replaces only the rate.

pool decides what shares the budget: 'stitch' (the default) gives each stitch its own budget, while 'host' pools the budget across every stitch hitting the same host — use it when one API publishes a single account-wide limit. Host pooling works in-process out of the box: separate stitches in the same process draw from one budget per host with no extra configuration. Giving those stitches a shared store extends that single-process budget into a distributed one that spans workers.

See Reference → Config types for every field.

See also