One list, a hundred follow-up calls

The problem

GET /orders returns 100. Each carries a customerId, so you make 100 more calls. It is the most common composition shape in API integration, and every part of it is a decision.

N is unknown until runtime, and every call needs a different input. Then:

• Concurrency — all 100 at once trips a rate limit; one at a time wastes the afternoon. And vendor governance is often concurrency-based, so a requests-per-second cap doesn't protect you.
• Partial failure — Promise.all rejects on the first error and discards the successes.
• The thundering herd — 100 calls that 429 together and back off by the same amount retry together. Deterministic backoff re-clusters the burst.
• Duplicates — 100 orders commonly reference far fewer customers.

The common solutions

What StitchAPI does

cache.coalesce collapses in-flight duplicates, and that is the headline. 100 concurrent calls over 30 distinct ids made 30 requests — one per id, exactly the floor — with every call in flight and not one response landed. Seventy callers were served without a request of their own, from a single cache: { ttl } block and no user code. The same cache with coalesce: false made 100.

Three more things are configuration:

const customer = stitch({
    url: 'https://api.vendor.com/customers/{id}',
    throttle: { concurrency: 8 }, // measured: peak 8 exactly, against 100 unbounded
    cache: { ttl: '60s' }, // the dedupe
    retry: { attempts: 3 }, // jittered by default
});

Measured: bounded concurrency held peak 8 exactly. And the retry default genuinely de-clusters a herd — 100 calls 429'd in the same instant retried across ~98 distinct milliseconds under expo-jitter, where 'fixed' and 'expo' both put all 100 into one millisecond (doubling a constant is still a constant on attempt 2).

linked gives the fan-out one trace — 1 traceId, 1 root, 101 spans covering the list and every lookup, with per-call inputs. Assembled: 45 executable lines against 87 hand-rolled, the difference being the FIFO pool, the retry loop, the retryable-status set and URL assembly, all of which became config.

Where it loses: a coalesced failure is not shared

The leader's failure releases its joiners to re-run. Measured: 100 concurrent calls for one id that 404s made 100 requests in two waves — 1 leader, then 99 followers each re-running the whole chain.

Every joiner gets its own honest HTTP 404, never a leader artefact — the right error at the wrong price. End to end this is the one place the hand-rolled version wins: 44 customer requests against 32, and a deleted customer cost 4 requests against 1. A Map<id, Promise> shares the rejection; the library spends a wasted request per duplicate reference to a broken id — which is exactly the shape a dead foreign key takes.

What StitchAPI does not solve here

1. The combinators cannot express this — and not for the reason you'd guess. The runtime length is fine (all(ids.map(…)) compiles). The input is the wall: all() spreads one StitchInput into every member, so 100 members made 100 requests for one distinct id. It also bounded nothing (peak 100) and fail-fast discarded 99 successful fetches while still paying for them — the auto-cancel prevented zero requests.
2. allSettled semantics are absent, and the documented workaround — compose .safe() members by hand — does not typecheck, because Member is brand-gated.
3. In-flight dedupe of failures, above.
4. A fan-shaped trace over per-call inputs. You get a fan (all(), wrong inputs) or per-call inputs (linked, which chains each call under the previous — measured depth 101, fan-out 1 for calls that ran at peak 100 concurrently). Not both.
5. Deep-copying joined results — see the aliasing callout.
6. A batch endpoint. Nothing can invent one.

See also