Cancellation with AbortController

Why cancellation exists

Some JavaScript work takes time, like loading data from a server or waiting for a timer. This is called asynchronous work: it finishes later, while the page keeps running. Sometimes that work stops being useful before it finishes. For example:

• The user typed a newer search.
• The user moved to another page.
• The user pressed a Stop button.
• The work took too long.

Cancellation means telling that old work to stop. When the work hears this, it should do three things:

• Stop as soon as it can.
• Clean up what it started, like a timer.
• Reject its promise, so the code that waits for it can move on.

You already know promises, timers, and try...catch. Cancellation uses all three. The work gets a signal: an object that says whether to stop. The work checks the signal. If the signal says stop, the work rejects its promise with a reason: a value that says why it stopped.

Requests from the browser work the same way. You can stop waiting for an answer. But the server may have done the work already.

const controller = new AbortController();
console.log(controller.signal.aborted);

controller.abort(new DOMException("Too slow", "TimeoutError"));
console.log(controller.signal.aborted, controller.signal.reason.name);

Line 1 makes a new controller. Line 2 prints controller.signal.aborted. aborted is true or false: has this signal been told to stop? It prints false, because nothing has stopped it yet.

Line 4 calls abort() and passes a reason. The reason here is a DOMException: a built-in error object that browsers use. Its first part is a message, "Too slow". Its second part is a name, "TimeoutError".

Line 5 prints true TimeoutError. The signal has stopped, and signal.reason keeps the reason you passed. A signal can stop only once. After that, it stays stopped and keeps its first reason.

Cancellation uses two objects. Each has its own job:

• The AbortController can stop the work. It has the method abort(reason). The reason is optional.
• The AbortSignal is what the work gets. It tells the work about a stop, but it can't cause one.

The signal gives the work four things:

• aborted: true once the signal has stopped, false before.
• reason: the value that says why it stopped.
• An abort event: it fires the moment the signal stops, so the work can react.
• throwIfAborted(): a method that throws the reason if the signal has already stopped.

The rule is: keep the controller, and give out only the signal. Then other code can hear a stop, but it can't stop your work by mistake.

In code, the same rule stops a helper function from cancelling work that it doesn't own. Sort each job into the right group before you try the bigger demo below.

Next, try a pretend download. It doesn't use the network. It uses timers, so you can watch each piece arrive. Each piece is called a chunk. The demo follows the same steps as a real cancellable request:

1. Check the signal before starting.
2. Pass the signal to each wait.
3. When the signal stops, clear the timer that is still waiting.
4. 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}

Look at the reason names in the demo:

• controller.abort() with no reason gives a DOMException named AbortError.
• AbortSignal.timeout(ms) stops by itself with a DOMException named TimeoutError.

A signal stops only once. Its abort event fires right away, during the abort() call, before the next line of code runs.

fetch asks a server for data and returns a promise. It is the most common place to use a signal. You pass the signal inside the options object: fetch(url, { signal }).

If the signal stops before the request finishes, the fetch promise rejects with the signal's reason. After a plain abort(), that reason is an AbortError.

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

A response comes in two parts. The headers arrive first; they describe the response. The body is the data itself, and it can keep arriving after the headers. So a stop can still matter after the headers arrive: if your code is still reading the body, that read fails.

Abort does not undo work on the server. Say your request asks the server to create an order. The server may have created it already. Stopping the request doesn't delete the order.

const controller = new AbortController();
const work = new Promise((resolve) => {
  setTimeout(() => resolve("finished"), 0);
});

controller.abort();
console.log(controller.signal.aborted);
work.then((value) => console.log(value));

Lines 2 to 4 make a promise. Its timer resolves it with "finished". Line 6 stops the controller. Line 7 prints true, so the signal did change. But line 8 still prints finished, because the promise never got the signal. Nothing told it to listen.

This is why cancellation is called cooperative: the work has to help. It must check or listen for the signal, and it must clean up its own timers.

You don't always need to make a controller yourself. AbortSignal has three helpers that make a signal for you:

• AbortSignal.abort(reason) gives a signal that has already stopped.
• AbortSignal.timeout(ms) gives a signal that stops by itself after ms milliseconds.
• AbortSignal.any([...]) joins several signals into one. The joined signal stops as soon as the first of them stops.

AbortSignal.any works in all main browsers since 2024 ("Baseline 2024"), and 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]);

Line 1 makes a signal that has already stopped. Line 3 makes a signal that stops itself after 1000 milliseconds, which is 1 second. Line 6 joins your own controller's signal and the deadline into one signal.

const user = new AbortController();
const deadline = AbortSignal.timeout(1000);
const stop = AbortSignal.any([user.signal, deadline]);

user.abort(new DOMException("Left page", "AbortError"));
console.log(stop.reason.name);

Line 3 joins the user's signal and a 1-second deadline. Line 5 stops the user's signal right away, long before the deadline. So line 6 prints AbortError, not TimeoutError.

When to use each one:

• Use timeout when slow work should fail by itself after a while.
• Use any when several things can stop the same work. For example: the user left the page, or a deadline passed.

Make a timeout signal right before the work it guards. Its clock starts when you call AbortSignal.timeout, not when a later fetch starts. If you want both a user stop and a deadline, make both signals first. Then join them with any, and pass only the joined signal to the work.

Built-in functions like fetch accept a signal. Your own functions should too. The usual way is an options object with a signal property: sleep(800, { signal }). With an options object, you can add more options later, like retries, and the way people call the function stays the same.

The example below is sleep: a function that waits ms milliseconds and then resolves. It writes signal?. with a question mark. That is optional chaining: if no signal was passed, the call is skipped instead of throwing an error.

1function 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"));

Step through it below. Pick when the caller stops the work, then click through it one line at a time.

1function 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();Run17const promise = sleep(800, { signal: controller.signal });18controller.abort(new DOMException("Stopped", "AbortError"));

The pattern has five steps, in this order:

1. Check first with signal?.throwIfAborted() (line 2). If the signal has already stopped, this throws, and nothing starts.
2. Start the real work, here a timer (line 8).
3. Listen for the abort event (line 12). { once: true } removes the listener after it runs once.
4. On abort, clear the timer and reject with signal.reason (lines 5 and 6).
5. On success, remove the listener and resolve as usual (lines 9 and 10).

const signal = AbortSignal.abort(new DOMException("Too slow", "TimeoutError"));

try {
  signal.throwIfAborted();
  console.log("started");
} catch (error) {
  console.log(error.name);
}

The signal on line 1 has already stopped, with a TimeoutError reason. So throwIfAborted() on line 4 throws that reason. Line 5 never runs, so started is never printed. The catch block prints TimeoutError on line 7.

This check stops a cancelled call before it starts a timer or a request.

function waitForTea(ms, { signal } = {}) {
  signal?.throwIfAborted();
  return new Promise((resolve, reject) => {
    const timer = setTimeout(() => resolve("tea ready"), ms);
    signal?.addEventListener("abort", () => {
      clearTimeout(timer);
      reject(signal.reason);
    }, { once: true });
  });
}

const controller = new AbortController();
const tea = waitForTea(1000, { signal: controller.signal });
controller.abort();
tea.catch((error) => console.log(error.name));

Line 4 starts a timer that would resolve with "tea ready" after 1 second. Line 14 stops the controller right away. The listener on lines 5 to 8 runs: it clears the timer and rejects the promise. Line 15 catches the rejection and prints AbortError, the name of the default reason.

A search box often sends a request as you type. Say the request for c is slow, and the request for cat is fast. Then the old c answer can arrive last. It replaces the newer cat results on the screen.

This bug is called a race condition: the result depends on which request finishes first. The promises work fine. The problem is the order.

In the demo, you "type" c, then ca, then cat, 120 milliseconds apart. Each search takes a fixed time, so the bug shows up every time. Run it with "Abort previous" off, then on.

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 last controller in a variable. Before you start a new search, stop the old controller. Then make a new one. Only the newest search can show its results.

function fakeSearch(query, { signal }) {
  return new Promise((resolve, reject) => {
    const timer = setTimeout(() => resolve("Results for " + query), 0);
    signal.addEventListener("abort", () => {
      clearTimeout(timer);
      reject(signal.reason);
    }, { once: true });
  });
}

let currentController;

async function searchLatest(query) {
  currentController?.abort(new DOMException("Newer search", "AbortError"));
  currentController = new AbortController();
  const { signal } = currentController;

  try {
    const results = await fakeSearch(query, { signal });
    console.log(results);
  } catch (error) {
    if (signal.aborted) return;
    throw error;
  }
}

const oldSearch = searchLatest("cat");
const newSearch = searchLatest("cats");
Promise.all([oldSearch, newSearch]);

Line 27 starts a search for cat. Line 28 starts a search for cats. That second call stops the first search on line 14. So only the newer search prints Results for cats.

Line 16 copies the signal into a local variable, signal. Each call gets its own. So on line 22, the old search checks its own signal, sees that it stopped, and quietly returns.

addEventListener also accepts a signal option. When that signal stops, the browser removes the listener for you.

This helps when you add several listeners for a short time. For example:

• a pop-up menu,
• dragging something across the page,
• a keyboard shortcut that only works for a while.

Give all of them the same signal. Then one abort() call removes them all.

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

Where you’ll use this

Use cancellation wherever old work can stop being useful before it finishes:

• Search boxes that send a request as you type.
• Page changes: stop loading data for a page the user left.
• Stop buttons for uploads, downloads, imports, and exports.
• Time limits for slow work.
• Short-lived event listeners that should all go away together.

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

Line 4 stops the request for the previous profile. Line 5 makes a fresh controller for this request, and line 6 keeps its signal in a local variable. Line 9 passes that signal to fetch. Line 12 returns null when this request was stopped on purpose. Line 13 throws any other error again.

Each row compares two ideas that are easy to mix up. Read it as: which ideas, what is true, and what mistake to avoid.

A good question to ask about any function is: "What is still running after this function stops?"

• A timer: clear it with clearTimeout.
• A listener: remove it, or add it with a signal in the first place.
• A fetch: pass it the signal, and handle the rejection.
• Work on the server: abort can't undo it. The server needs its own safety check, for example ignoring the same order when it arrives twice.

• "Promises can be cancelled." A promise only reports when work ends. The work itself must listen to a signal.
• "Abort undoes everything." It doesn't undo work that already finished, especially on a server.
• "I can reuse one controller." A signal stops only once. Make a new controller for each piece of work.
• "A timeout is just an AbortError." Timeout signals use a reason named TimeoutError.
• "Once fetch has a response, abort doesn't matter." Reading the response body can still fail after a stop.

Key takeaways

• Keep the AbortController. Give out only the AbortSignal.
• A signal stops only once, and it keeps its first reason.
• fetch rejects with the signal's reason. Handle a stop apart from real errors.
• AbortSignal.timeout makes a time limit. AbortSignal.any joins several ways to stop.
• A cancellable function checks first, listens once, cleans up, rejects with signal.reason, and passes the signal on.

Cancellation is teamwork: your code stops a signal, and the work notices, cleans up, and rejects with the reason.

Up next: Async patterns.