lib: add AbortSignal.timeout

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

Author: jasnell

doc/api/globals.md

@@ -104,6 +104,17 @@ changes:
 
 Returns a new already aborted `AbortSignal`.
 
+#### Static method: `AbortSignal.timeout(delay)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `delay` {number} The number of milliseconds to wait before triggering
+  the AbortSignal.
+
+Returns a new `AbortSignal` which will be aborted in `delay` milliseconds.
+
 #### Event: `'abort'`
 
 <!-- YAML

lib/internal/abort_controller.js

@@ -8,8 +8,10 @@ const {
   ObjectDefineProperties,
   ObjectSetPrototypeOf,
   ObjectDefineProperty,
+  SafeFinalizationRegistry,
   Symbol,
   SymbolToStringTag,
+  WeakRef,
 } = primordials;
 
 const {
@@ -29,9 +31,24 @@ const {
   }
 } = require('internal/errors');
 
+const {
+  validateUint32,
+} = require('internal/validators');
+
+const {
+  DOMException,
+} = internalBinding('messaging');
+
+const {
+  clearTimeout,
+  setTimeout,
+} = require('timers');
+
 const kAborted = Symbol('kAborted');
 const kReason = Symbol('kReason');
 
+const clearTimeoutRegistry = new SafeFinalizationRegistry(clearTimeout);
+
 function customInspect(self, obj, depth, options) {
   if (depth < 0)
     return self;
@@ -48,6 +65,29 @@ function validateAbortSignal(obj) {
     throw new ERR_INVALID_THIS('AbortSignal');
 }
 
+// Because the AbortSignal timeout cannot be canceled, we don't want the
+// presence of the timer alone to keep the AbortSignal from being garbage
+// collected if it otherwise no longer accessible. We also don't want the
+// timer to keep the Node.js process open on it's own. Therefore, we wrap
+// the AbortSignal in a WeakRef and have the setTimeout callback close
+// over the WeakRef rather than directly over the AbortSignal, and we unref
+// the created timer object. Separately, we add the signal to a
+// FinalizerRegistry that will clear the timeout when the signal is gc'd.
+function setWeakAbortSignalTimeout(weakRef, delay) {
+  const timeout = setTimeout(() => {
+    const signal = weakRef.deref();
+    if (signal !== undefined) {
+      abortSignal(
+        signal,
+        new DOMException(
+          'The operation was aborted due to timeout',
+          'TimeoutError'));
+    }
+  }, delay);
+  timeout.unref();
+  return timeout;
+}
+
 class AbortSignal extends EventTarget {
   constructor() {
     throw new ERR_ILLEGAL_CONSTRUCTOR();
@@ -82,6 +122,19 @@ class AbortSignal extends EventTarget {
   static abort(reason) {
     return createAbortSignal(true, reason);
   }
+
+  /**
+   * @param {number} delay
+   * @returns {AbortSignal}
+   */
+  static timeout(delay) {
+    validateUint32(delay, 'delay', true);
+    const signal = createAbortSignal();
+    clearTimeoutRegistry.register(
+      signal,
+      setWeakAbortSignalTimeout(new WeakRef(signal), delay));
+    return signal;
+  }
 }
 
 ObjectDefineProperties(AbortSignal.prototype, {

test/parallel/test-abortcontroller.js

@@ -1,10 +1,11 @@
-// Flags: --no-warnings
+// Flags: --no-warnings --expose-gc
 'use strict';
 
 const common = require('../common');
 const { inspect } = require('util');
 
 const { ok, strictEqual, throws } = require('assert');
+const { setTimeout: sleep } = require('timers/promises');
 
 {
   // Tests that abort is fired with the correct event type on AbortControllers
@@ -153,3 +154,33 @@ const { ok, strictEqual, throws } = require('assert');
   const signal = AbortSignal.abort('reason');
   strictEqual(signal.reason, 'reason');
 }
+
+{
+  // Test AbortSignal timeout
+  const signal = AbortSignal.timeout(10);
+  ok(!signal.aborted);
+  setTimeout(common.mustCall(() => {
+    ok(signal.aborted);
+    strictEqual(signal.reason.name, 'TimeoutError');
+    strictEqual(signal.reason.code, 23);
+  }), 20);
+}
+
+{
+  (async () => {
+    // Test AbortSignal timeout doesn't prevent the signal
+    // from being garbage collected.
+    let ref;
+    {
+      ref = new globalThis.WeakRef(AbortSignal.timeout(1_200_000));
+    }
+
+    await sleep(10);
+    globalThis.gc();
+    strictEqual(ref.deref(), undefined);
+  })().then(common.mustCall());
+
+  // Setting a long timeout (20 minutes here) should not
+  // keep the Node.js process open (the timer is unref'd)
+  AbortSignal.timeout(1_200_000);
+}