Cancellation & races: AbortController and latest-only requests

Promises have no built-in "cancel". The platform's answer is a pair of objects:

• AbortController, the button. Whoever decides to cancel keeps it and calls abort().
• AbortSignal (controller.signal), the wire. You pass it to the work. The work watches it and stops when it fires.

const controller = new AbortController();

fetch("/api/report", { signal: controller.signal })
  .then((res) => res.json())
  .then(showReport)
  .catch((err) => {
    if (err.name === "AbortError") return; // we cancelled it: not a failure
    showError(err);
  });

cancelButton.onclick = () => controller.abort();

When abort() is called, fetch stops the request and its promise rejects with an AbortError DOMException. If the response headers have already arrived, reading the body (res.json(), res.text()) rejects instead.

Four facts about the pair:

• Aborting is one-way and once. The first abort() sets signal.aborted = true and fires the abort event. Later calls do nothing, and the signal stays aborted forever.
• So use one controller per operation. A signal that's already aborted makes every new fetch reject immediately. Create a fresh controller for each request you might cancel.
• signal.reason says why. With no argument it's an AbortError DOMException. abort(someValue) makes someValue the reason, and fetch rejects with exactly that value.
• Cancellation is cooperative. A signal does nothing by itself. It only stops work that takes it and listens to it. fetch does. Your own async functions must be written to (medium tier).

fetch honours a signal because it was written to. Your own async functions only become cancellable if you write them the same way. The DOM Standard spells out the contract for any promise-returning API that can be aborted: take the signal as a signal option, reject immediately if it's already aborted, and otherwise reject with signal.reason when it aborts.

Pass it down to everything that waits.

async function loadReport(id, { signal } = {}) {
  const res = await fetch(`/api/reports/${id}`, { signal });
  const report = await res.json(); // also aborted by the same signal
  await sleep(250, signal);        // your own wait: make it abortable too
  signal?.throwIfAborted();        // a checkpoint before expensive CPU work
  return summarise(report);
}

Each step that doesn't receive the signal is a hole: an abort during that step goes unnoticed until the next step that does check.

Make your own waits abortable.

function sleep(ms, signal) {
  return new Promise((resolve, reject) => {
    signal?.throwIfAborted(); // already aborted: reject right away
    const timer = setTimeout(() => {
      signal?.removeEventListener("abort", onAbort); // done: stop listening
      resolve();
    }, ms);
    function onAbort() {
      clearTimeout(timer);   // stop the work itself…
      reject(signal.reason); // …and settle with the caller's reason
    }
    signal?.addEventListener("abort", onAbort, { once: true });
  });
}

The details carry the weight:

• throwIfAborted() first. A listener added to a signal that's already aborted never fires, so without this check the promise would wait out the whole delay.
• reject(signal.reason), not new Error("aborted"). The caller chose the reason (an AbortError by default, a TimeoutError from AbortSignal.timeout, or their own value). Pass it through unchanged so their checks still work.
• Stop the work, not just the promise. clearTimeout (or abort on an inner request) is the part that saves resources. Rejecting alone just means nobody waits for the result.
• Remove the listener when you finish normally. A long-lived signal (one per page, say) would otherwise collect a listener from every call.

A reusable wrapper that makes any signal-taking request "latest only". Each call aborts the one before it, adds an optional deadline, and reports the outcome as data, so callers never need a try/catch to tell "superseded" from "failed":

function latestOnly(request, { timeoutMs } = {}) {
  let current; // the controller of the newest call

  return async function run(...args) {
    current?.abort();                    // 1. the previous call is stale now
    const controller = new AbortController();
    current = controller;
    const deadline = timeoutMs ? AbortSignal.timeout(timeoutMs) : undefined;
    const signal = deadline ? AbortSignal.any([controller.signal, deadline]) : controller.signal;

    try {
      const value = await request(...args, signal);
      if (controller !== current) return { status: "superseded" }; // 2. finished, but too late
      return { status: "ok", value };
    } catch (error) {
      if (controller !== current) return { status: "superseded" }; // 3. aborted by a newer call
      if (deadline?.aborted) return { status: "timeout" };         // 4. our deadline passed
      return { status: "error", error };
    }
  };
}

const search = latestOnly(
  (q, signal) => fetchJson(`/search?q=${encodeURIComponent(q)}`, { signal }),
  { timeoutMs: 5000 },
);
const outcome = await search("rea");
if (outcome.status === "ok") render(outcome.value);

Why both mechanisms? The abort (1) stops the network work, but it can only stop steps that take the signal. Anything else in request still runs to completion: a cache lookup, a third-party SDK call, a JSON.parse of a big payload, an await enrich(data) that ignores the signal. And an abort can't un-fulfil a promise that has already fulfilled. The identity check (2, 3) is what guarantees that only the newest call's result is ever used, whatever the request does with its signal.

Why compare controllers instead of checking error.name? "Was this superseded?" is a question about our bookkeeping, not about the error. A newer call might abort with a custom reason, and a request may wrap the abort in its own error type. The controller identity answers it exactly. "Did it time out?" is bookkeeping too: keep the timeout signal and ask whether it aborted (4). A wrapped error has no TimeoutError name to find.

Superseded is not an error. Return it as its own status, and have the UI ignore it. Shown as an error, every fast typist sees a "Search failed" flash.