Aborting fetch request with AbortController

Introduction

AbortController is an interface for aborting asynchronous processes, and has been available in Node.js since 15.0.0. In this article, we'll explain how to cancel an HTTP request, a typical asynchronous process.

In the past, we used XMLHttpRequest to send HTTP requests, but nowadays we almost use the Promise-based Fetch API.

HTTP client libraries such as axios and ky are highly used, the basic Fetch API cancellation is explained here.

About Fetch API

The Fetch API is available as standard in modern browsers and Deno. Even Node.js has node-fetch, so it's no exaggeration to say that the Fetch API is universally available as an HTTP client. So, first of all, let's make sure you know how to use it with the Fetch API.

The Fetch API takes an object called RequestInit as its second argument. The interface is as follows:

declare function fetch(
  input: Request | URL | string,
  init?: RequestInit
): Promise<Response>

interface RequestInit {
  body?: BodyInit | null
  cache?: RequestCache
  credentials?: RequestCredentials
  headers?: HeadersInit
  integrity?: string
  keepalive?: boolean
  method?: string
  mode?: RequestMode
  redirect?: RequestRedirect
  referrer?: string
  referrerPolicy?: ReferrerPolicy
  signal?: AbortSignal | null
  window?: any
}

The key signal takes an AbortSignal.AbortSignal is a member of class AbortController.

About AbortController

AbortController is a controller that contains a signal object that can abort an asynchronous process. You can create an object from the constructor.

const controller = new AbortController()

declare class AbortController {
  readonly signal: AbortSignal
  abort(): void
}

The AbortController has a reference to the signal object and an abort method. You can abort an HTTP request by passing this signal to fetch and calling the abort method.

The follow example assumes a non-Deno execution environment. Deno does not yet implement cancellation of the Fetch API as of 1.10.3. It has been merged into the main branch and will probably be available soon.

Top-Level Await notation is used.

const url = 'https://google.com'
const controller = new AbortController()

await fetch(url, {
  signal: controller.signal
})

setTimeout(() => {
  controller.abort()
}, 1000)

In the above example, the request will be aborted after 1000 milliseconds. In the UI, user-initiated cancelling can be achieved by binding a call to the abort function to a button click event, for example.

Now that we have aborted, let's think about what to do after the abort.

There are several ways to handle abort. Let's look at each of them.

Rejecting the Fetch API

In the Fetch API, reject is defined to occur in the following two cases. See specification for details.

TypeError
AbortError

TypeError is thrown when a network error occurs. For example, a request for a non-existent URL will raise a TypeError.

await fetch('https://this-is-not-exist.com')
Uncaught TypeError: error sending request for url (https://this-is-not-exist.com/): error trying to connect: dns error: failed to lookup address information: nodename nor servname provided, or not known

And another error is AbortError. This is raised when the request is aborted.

By picking up AbortError, we can handle the error exactly as it should be handled. Also, by picking up TypeError and AbortError, you can make notifications more user-friendly.

try {
  await fetch('https://this-is-not-exist.com')
} catch (e) {
  if (e.name === 'AbortError') {
    // Abort error handling
  } else {
    // Network error handling
  }
}

In the above example, I used the tryCatch statement to catch errors, but of course you can also pick up errors from the reject function of Promise.

Event Handlers and Event Listeners

The interface of AbortSignal is as follows:

interface AbortSignal extends EventTarget {
  readonly aborted: boolean
  onabort: ((this: AbortSignal, ev: Event) => any) | null
  addEventListener<K extends keyof AbortSignalEventMap>(
    type: K,
    listener: (this: AbortSignal, ev: AbortSignalEventMap[K]) => any,
    options?: boolean | AddEventListenerOptions
  ): void
  removeEventListener<K extends keyof AbortSignalEventMap>(
    type: K,
    listener: (this: AbortSignal, ev: AbortSignalEventMap[K]) => any,
    options?: boolean | EventListenerOptions
  ): void
}

AbortSignal has an event handler called onabort. By setting any function to it, the function will be called on abort.

const controller = new AbortController()
controller.signal.onabort = () => {}

You can also monitor for abort event in the same way by setting the type of the event listener to abort.

controller.signal.addEventListener('abort', () => {})

Also, the read-only property aborted indicates whether the AbortSignal has been aborted or not.

Abort multiple HTTP requests

The AboutController can be passed to multiple calls to the fetch function to abort a batch HTTP requests.

const controller = new AbortController()
const { signal } = controller

try {
  await Promise.all(
    [endpoint1, endpoint2, endpoint3].map((url) => {
      fetch(url, { signal })
    })
  )
} catch (e) {}

You can also catch errors in bulk.

Abort multiple times

Once an AbortController calls abort, it can't run the fetch function again that references that AbortSignal.

For example, in Vue, you might end up writing something like this.

<script setup lang="ts">
  const controller = new AbortController()

  const onCancel = () => {
    controller.abort()
  }

  const onClick = async () => {
    await fetch(url, { signal: controller.signal })
  }
</script>

html

In this example, the AbortController instance is not regenerated on every onClick, so you cannot make a second HTTP request. Since you need to make the instance for each fetch, you do so as follows:

<script setup lang="ts">
  let controller

  const onCancel = () => {
    controller?.abort()
  }

  const onClick = async () => {
    controller = new AbortController()
    await fetch(url, { signal: controller.signal })
  }
</script>