AbortSignal.throwIfAborted()

The throwIfAborted() method throws the signal's abort reason if the signal has been aborted; otherwise it does nothing.

An API that needs to support aborting can accept an AbortSignal object and use throwIfAborted() to test and throw when the abort event is signalled.

This method can also be used to abort operations at particular points in code, rather than passing to functions that take a signal.

None.

The examples below come from the specification.

This example demonstrates how you can use throwIfAborted() to abort a polling operation.

Consider an asynchronous waitForCondition() function that is called with another asynchronous function "func", a target value "targetValue, and an AbortSignal. The method compares the result of func with targetValue in a loop, returning when they match.

async function waitForCondition(func, targetValue, { signal } = {}) {
  while (true) {
    signal?.throwIfAborted();

    const result = await func();
    if (result === targetValue) {
      return;
    }
  }
}

On each iteration of the loop, we use throwIfAborted() to throw the signal's reason if the operation has been aborted (and otherwise do nothing). If the signal is aborted, this will cause the waitForCondition() promise to be rejected .

An API that needs to support aborting can accept an AbortSignal object, and use its state to trigger abort signal handling when needed.

A Promise-based API should respond to the abort signal by rejecting any unsettled promise with the AbortSignal abort reason. For example, consider the following myCoolPromiseAPI, which takes a signal and returns a promise. The promise is rejected immediately if the signal is already aborted, or if the abort event is detected. Otherwise it completes normally and then resolves the promise.

function myCoolPromiseAPI(..., {signal}) {
  return new Promise((resolve, reject) => {
    //If the signal is already aborted, immediately throw in order to reject the promise.
    signal.throwIfAborted();

    // Perform the main purpose of the API
    // Call resolve(result) when done.

    // Watch for 'abort' signals
    signal.addEventListener('abort', () => {
      // Stop the main operation
      // Reject the promise wth the abort reason.
      reject(signal.reason);
    });
  });
}

The API might then be used as shown. Note that AbortController.abort() is called to abort the operation.

const controller = new AbortController();
const signal = controller.signal;

startSpinner();

myCoolPromiseAPI({ ..., signal })
  .then(result => ...)
  .catch(err => {
    if (err.name == 'AbortError') return;
    showUserErrorMessage();
  })
  .then(() => stopSpinner());

controller.abort();

APIs that do not return promises might react in a similar manner. In some cases it may make sense to absorb the signal.

• Fetch API