Cancellation with AbortController

Why cancellation exists

Asynchronous JavaScript lets work continue while your page stays responsive. That is wonderful until the work is no longer useful: the user typed a newer search, moved to another page, pressed Stop, or a request took too long. Cancellation is the pattern for telling that old work, “please stop now, clean up what you started, and reject the promise so the caller can move on.”

You have already met promises, timers, and error handling strategies. Cancellation connects all three: an operation receives a signal, checks it, listens for it, and rejects with a reason when the signal aborts.

The API is split into two objects because ownership matters. The AbortController has the power: abort(reason?). The AbortSignal is what work receives: it exposes aborted, reason, an abort event, and throwIfAborted(). Hand out the signal; keep the controller.

Sort these responsibilities before you run the bigger demo.

Now try a fake chunked download. It uses timers instead of a real network so you can see each chunk, but it follows the same pattern as a cancellable request: check first, pass the signal down, clear pending work when the signal aborts, and reject with the signal’s reason.

1async function downloadFile({ signal }) {2  signal.throwIfAborted();3  for (const chunk of [1, 2, 3, 4]) {4    await wait(350, { signal });5    progress.value = chunk * 25;6  }7  return "download complete";8}

Notice the reason names. controller.abort() without a custom reason creates a DOMException named AbortError in modern platforms. AbortSignal.timeout(ms) aborts with a DOMException named TimeoutError. A signal aborts only once, and the abort event fires synchronously during abort().

fetch is the most common place you will use a signal. You pass it in the options object: fetch(url, { signal }). If the signal aborts before the request completes, modern fetch rejects with signal.reason. Older browsers often reported AbortError for every abort, so production code should care about the broad category more than exact messages.

1const signal = AbortSignal.abort();2 3try {4  await fetch(location.href, { signal });5} catch (error) {6  console.log(error.name);7}

Aborting after response headers arrive can still matter: if your code is reading a large body stream, aborting can make the body read fail. What abort does not do is roll back a server. If you sent a request that creates an order, the server may already have created it.

You do not always need to create a controller yourself. AbortSignal.abort(reason?) returns a signal that is already aborted. AbortSignal.timeout(ms) returns a signal that aborts itself after a deadline. AbortSignal.any([...]) creates a combined signal that follows the first input signal to abort. The any helper is Baseline 2024 in browsers and available in modern Node.

1const alreadyDone = AbortSignal.abort(new DOMException("Nope", "AbortError"));2 3const deadline = AbortSignal.timeout(1000);4 5const controller = new AbortController();6const cancelOrDeadline = AbortSignal.any([controller.signal, deadline]);

Use timeout when slow work should fail automatically. Use any when several events can stop the same operation: user navigated away, component unmounted, or a deadline expired.

Built-in APIs are useful, but your own helpers should cooperate too. The convention is to accept an options object with signal. That keeps the function extensible: later you can add retries, timeout, or other options without changing the call shape.

1export function sleep(ms, { signal } = {}) {2  signal?.throwIfAborted();3  return new Promise((resolve, reject) => {4    const onAbort = () => {5      clearTimeout(timer);6      reject(signal.reason);7    };8    const timer = setTimeout(() => {9      signal?.removeEventListener("abort", onAbort);10      resolve("slept");11    }, ms);12    signal?.addEventListener("abort", onAbort, { once: true });13  });14}15 16const controller = new AbortController();17const promise = sleep(800, { signal: controller.signal });18controller.abort(new DOMException("Stopped", "AbortError"));

1export function sleep(ms, { signal } = {}) {2  signal?.throwIfAborted();3  return new Promise((resolve, reject) => {4    const onAbort = () => {5      clearTimeout(timer);6      reject(signal.reason);7    };8    const timer = setTimeout(() => {9      signal?.removeEventListener("abort", onAbort);10      resolve("slept");11    }, ms);12    signal?.addEventListener("abort", onAbort, { once: true });13  });14}15 16const controller = new AbortController();17const promise = sleep(800, { signal: controller.signal });Run18controller.abort(new DOMException("Stopped", "AbortError"));

The pattern is small but strict:

1. Check up front with signal?.throwIfAborted().
2. Start the real work only after that check.
3. Add an abort listener with { once: true }.
4. On abort, clean up and reject with signal.reason.
5. On success, remove the listener and resolve normally.

Search boxes often fire a request for every few characters. If the request for c is slow and the request for cat is fast, the old c result can finish last and overwrite the fresh result. That is not a promise bug; it is a race condition.

1let currentController;2 3async function runSearch(query) {4  currentController?.abort(new DOMException("Newer search", "AbortError"));5  currentController = new AbortController();6  const { signal } = currentController;7  const results = await fakeSearch(query, { signal });8  render(results);9}

The fix is to keep the previous controller in a variable. Before starting a newer request, abort the previous controller and create a new one. Only the latest request gets to render.

addEventListener accepts a signal option. When the signal aborts, the browser removes that listener. This is a tidy way to clean up temporary UI, drag handles, keyboard shortcuts, or pop-up behavior that attaches several listeners at once.

1const controller = new AbortController();2const { signal } = controller;3 4button.addEventListener("click", countClick, { signal });5button.addEventListener("pointerenter", showHint, { signal });6window.addEventListener("keydown", onKey, { signal });7 8controller.abort(); // removes all three listeners

Where you’ll use this

Cancellation shows up anywhere the user can outpace old work:

• Autocomplete and search-as-you-type requests.
• Route changes: stop loading data for pages the user left.
• Upload, download, import, and export Stop buttons.
• Deadlines for slow operations.
• Temporary event listeners that should disappear together.

1let currentController;2 3export async function loadProfile(userId) {4  currentController?.abort(new DOMException("Newer profile", "AbortError"));5  currentController = new AbortController();6 7  try {8    const response = await fetch("/api/users/" + userId, {9      signal: currentController.signal,10    });11    return await response.json();12  } catch (error) {13    if (currentController.signal.aborted) return null;14    throw error;15  }16}

• “Promises can be cancelled.” Promises report completion. The work behind them must cooperate with a signal.
• “Abort undoes everything.” It does not undo effects already completed, especially on a server.
• “I can reuse one controller.” Create a new controller per operation because a signal aborts only once.
• “Timeouts are just AbortError.” Timeout signals use TimeoutError in modern platforms.
• “If fetch responded, abort no longer matters.” Reading the body stream can still error after abort.

Key takeaways

• Keep the AbortController; pass the AbortSignal.
• A signal aborts once and keeps its first reason.
• Modern fetch rejects with the signal’s reason; handle aborts separately from real failures.
• AbortSignal.timeout creates deadlines; AbortSignal.any combines ways to stop.
• Cancellable APIs check up front, listen once, clean up, reject with signal.reason, and pass signals down.

Cancellation is cooperative: an owner aborts a signal, and well-designed work notices, cleans up, and rejects with the reason.

Up next: Async patterns.