Streaming Bodies and AbortController

## Why there is no timeout option `fetch()` is specified in terms of a single, general cancellation primitive rather than a bespoke option per concern. Anything that wants to stop a request — a deadline, a user pressing Cancel, a view being torn down, a newer request superseding this one — goes through the same door: the `signal` init option. So the answer to "how do I add a timeout" is really "how do I abort on a timer". ## The short form ```js const res = await fetch('/api/report', { signal: AbortSignal.timeout(5000) }); ``` `AbortSignal.timeout(ms)` is a static that returns a signal which aborts itself after `ms` milliseconds. There is no controller to hold and no timer to clear — the signal owns both. When it fires, the request is torn down and the abort surfaces as a `DOMException` whose `name` is `TimeoutError`, which is how you tell a deadline apart from a cancel you triggered yourself. One subtlety: the clock starts when the **signal is created**, not when `fetch()` is called. Creating signals up front and using them later burns part of the budget before the request begins, so create the signal at the call site. ## The manual form ```js const controller = new AbortController(); const timer = setTimeout(() => controller.abort(), 5000); try { const res = await fetch(url, { signal: controller.signal }); return await res.json(); } finally { clearTimeout(timer); } ``` Three details matter. The `clearTimeout` belongs in a `finally` so it runs on both paths — a stray timer that fires later is harmless for the request but keeps a closure alive and, in a reused-controller design, can abort the wrong thing. The `return await` inside the `try` is deliberate: without `await`, the `finally` runs before the JSON body has been read, and the timer is cleared while the transfer is still in flight. And each request needs its **own** controller: a signal that has aborted stays aborted forever, so a reused controller makes every subsequent `fetch()` reject immediately. ## What the deadline actually covers This is where candidates go wrong. It is not a connect timeout, not a read timeout, and not an inactivity timeout. It is a wall-clock deadline over the entire operation. A response that begins streaming at 200 ms and is still streaming at 5 s will be cut off, mid-body, at the deadline. If you want an inactivity timeout instead — "abort only if nothing has arrived for two seconds" — you have to build it: read the body chunk by chunk and re-arm your own timer on each chunk, aborting the controller when it expires. ## Where the failure appears `fetch()` resolves once the headers are in. If the deadline fires before that, the `fetch()` promise itself rejects. If it fires afterwards, the promise has already settled and the abort lands on the **body**: the response's stream is errored, so a pending `reader.read()`, or the `response.json()` you were awaiting, rejects instead. Code that wraps only the `fetch()` call in a `try` and reads the body outside it will let that rejection escape. ## Race is not cancel A very common wrong answer is to race the fetch against a timer promise. That makes your code stop waiting, but the request keeps running: bytes keep arriving, the connection stays busy, and the response handler may still execute. Only an abort signal actually stops the browser's work. Racing is a control-flow trick; aborting is cancellation. ## Practical shape In real applications the timeout usually belongs in one shared request helper rather than at every call site, because a per-call default is where inconsistency creeps in. It also needs to compose with whatever forwards a caller-supplied signal — a helper that ignores the signal it was handed, and only applies its own deadline, silently removes the caller's ability to cancel.