AbortController - Reaffirming promise reject & AbortError semantics

[Bnaya]

Per #33528

TL;DR;

• We need that abortable async node api to reject with AbortError.
• On the browser AbortError is instanceof DOMException,
• We don't have DOMException in node, so we need to make it instanceof Error
• abortError = new Error(), abortError.name = "AbortError";
• We need to document that
• unfortunately browser code that uses error instanceof DOMException && error.name === "AbortError" will not detect it

---

On the browser, when async flow is aborted using AbortController, the flow is expected to return rejected promise, with an AbortError ().

Spec words: "APIs that rely upon AbortController are encouraged to respond to abort() by rejecting any unsettled promise with a new "AbortError" DOMException." spec link.

Motivation: Without rejecting and using well-known value, you might end up with never resolving promises up the chain, or with unexpected errors.

currently The only built-in api that supports AbortContoller is fetch, example:

const c = new AbortController();
const p = fetch('', { signal: c.signal });
c.abort();
try {
    await p;
} catch (e) {
    if (e instanceof DOMException && e.name === "AbortError") {
        // aborted by us, no need to do anything
    } else {
        // real error
        console.error(e)
    }
}

On the browser AbortError is not a special constructor, but an instance of DOMException:
new DOMException('Aborted', 'AbortError'), with name=AbortError and a custom message

[addaleax]

• We don't have DOMException in node, so we need to make it instanceof Error

Small correction: We do have DOMException in Node.js:

> new worker_threads.MessageChannel().port1.postMessage(process)
Uncaught:
DOMException [DataCloneError]: function _rawDebug(...args) {
    binding._rawDebug(format.apply(null, args));
  } could not be cloned.

It’s not exposed as a global, but we could change that of course.

[Bnaya]

Good to know :)
I personaly still prefer using plain Error, and document the difference

[jasnell]

It would be fairly easy for us to expose an AbortError using our current internal errors mechanism. I'd prefer not to extend off DOMException tho.

[jasnell]

Now that AbortController has landed and uses DOMException with AbortError, we can close this.