lib: add abortSignal.throwIfAborted()

Refs: whatwg/dom#1034
Signed-off-by: James M Snell <[email protected]>

PR-URL: #40951
Reviewed-By: Benjamin Gruenbaum <[email protected]>

Author: jasnell

doc/api/globals.md

@@ -179,6 +179,14 @@ ac.abort(new Error('boom!'));
 console.log(ac.signal.reason);  // Error('boom!');
 ```
 
+#### `abortSignal.throwIfAborted()`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+If `abortSignal.aborted` is `true`, throws `abortSignal.reason`.
+
 ## Class: `Buffer`
 
 <!-- YAML

lib/internal/abort_controller.js

@@ -141,6 +141,12 @@ class AbortSignal extends EventTarget {
     return this[kReason];
   }
 
+  throwIfAborted() {
+    if (this.aborted) {
+      throw this.reason;
+    }
+  }
+
   [customInspectSymbol](depth, options) {
     return customInspect(this, {
       aborted: this.aborted
@@ -151,7 +157,8 @@ class AbortSignal extends EventTarget {
    * @param {any} reason
    * @returns {AbortSignal}
    */
-  static abort(reason) {
+  static abort(
+    reason = new DOMException('This operation was aborted', 'AbortError')) {
     return createAbortSignal(true, reason);
   }
 
@@ -311,7 +318,7 @@ class AbortController {
   /**
    * @param {any} reason
    */
-  abort(reason) {
+  abort(reason = new DOMException('This operation was aborted', 'AbortError')) {
     validateAbortController(this);
     abortSignal(this[kSignal], reason);
   }

test/parallel/test-abortcontroller.js

@@ -14,6 +14,8 @@ const {
 const {
   kWeakHandler,
 } = require('internal/event_target');
+const { internalBinding } = require('internal/test/binding');
+const { DOMException } = internalBinding('messaging');
 
 const { setTimeout: sleep } = require('timers/promises');
 
@@ -230,3 +232,24 @@ const { setTimeout: sleep } = require('timers/promises');
   // keep the Node.js process open (the timer is unref'd)
   AbortSignal.timeout(1_200_000);
 }
+
+{
+  // Test AbortSignal.reason default
+  const signal = AbortSignal.abort();
+  ok(signal.reason instanceof DOMException);
+  strictEqual(signal.reason.code, 20);
+
+  const ac = new AbortController();
+  ac.abort();
+  ok(ac.signal.reason instanceof DOMException);
+  strictEqual(ac.signal.reason.code, 20);
+}
+
+{
+  // Test abortSignal.throwIfAborted()
+  throws(() => AbortSignal.abort().throwIfAborted(), { code: 20 });
+
+  // Does not throw because it's not aborted.
+  const ac = new AbortController();
+  ac.signal.throwIfAborted();
+}