lib: add aborted() utility function

doc/api/util.md

@@ -1989,6 +1989,53 @@ const channel = new MessageChannel();
 channel.port2.postMessage(signal, [signal]);
 ```
 
+## `util.aborted(signal, resource)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+* `signal` {AbortSignal}
+* `resource` {Object} Any non-null entity, reference to which is held weakly.
+* Returns: {Promise}
+
+Listens to abort event on the provided `signal` and
+returns a promise that resolves when the `signal` is
+aborted. The function is dependent on the `resource` and
+the returned promise shall remain pending if `resource`
+goes out of memory. The function shall automatically
+cleanup any event listeners it attaches to `signal`.
+
+```js
+const { aborted } = require('util');
+
+const dependent = obtainSomethingAbortable();
+
+aborted(dependent.signal, dependent).then(() => {
+  // Do something when dependent is aborted.
+});
+
+dependent.on('event', () => {
+  dependent.abort();
+});
+```
+
+```mjs
+import { aborted } from 'node:util';
+
+const dependent = obtainSomethingAbortable();
+
+aborted(dependent.signal, dependent).then(() => {
+  // Do something when dependent is aborted.
+});
+
+dependent.on('event', () => {
+  dependent.abort();
+});
+```
+
 ## `util.types`
 
 <!-- YAML

lib/internal/abort_controller.js

@@ -13,6 +13,7 @@ const {
   Symbol,
   SymbolToStringTag,
   WeakRef,
+  PromiseResolve,
 } = primordials;
 
 const {
@@ -22,11 +23,13 @@ const {
   kTrustEvent,
   kNewListener,
   kRemoveListener,
+  kWeakHandler,
 } = require('internal/event_target');
 const {
   customInspectSymbol,
   kEnumerableProperty,
   kEmptyObject,
+  createDeferredPromise,
 } = require('internal/util');
 const { inspect } = require('internal/util/inspect');
 const {
@@ -39,6 +42,8 @@ const {
 
 const {
   validateUint32,
+  validateAbortSignal: abortSignalValidator,
+  validateObject,
 } = require('internal/validators');
 
 const {
@@ -357,6 +362,21 @@ function transferableAbortController() {
   return AbortController[kMakeTransferable]();
 }
 
+/**
+ * @param {AbortSignal} signal
+ * @param {any} resource
+ * @returns {Promise<void>}
+ */
+async function aborted(signal, resource) {
+  abortSignalValidator(signal, 'signal');
+  validateObject(resource, 'resource', { nullable: false, allowFunction: true, allowArray: true });
+  if (signal.aborted)
+    return PromiseResolve();
+  const abortPromise = createDeferredPromise();
+  signal.addEventListener('abort', abortPromise.resolve, { [kWeakHandler]: resource, once: true });
+  return abortPromise.promise;
+}
+
 ObjectDefineProperties(AbortController.prototype, {
   signal: kEnumerableProperty,
   abort: kEnumerableProperty,
@@ -377,4 +397,5 @@ module.exports = {
   ClonedAbortSignal,
   transferableAbortSignal,
   transferableAbortController,
+  aborted,
 };

lib/util.js

@@ -393,6 +393,9 @@ module.exports = {
   get transferableAbortController() {
     return lazyAbortController().transferableAbortController;
   },
+  get aborted() {
+    return lazyAbortController().aborted;
+  },
   types
 };
 

test/parallel/test-aborted-util.js

@@ -0,0 +1,44 @@
+// Flags: --expose-gc
+'use strict';
+
+const common = require('../common');
+const { aborted } = require('util');
+const assert = require('assert');
+const { getEventListeners } = require('events');
+
+{
+  // Test aborted works when provided a resource
+  const ac = new AbortController();
+  aborted(ac.signal, {}).then(common.mustCall());
+  ac.abort();
+  assert.strictEqual(ac.signal.aborted, true);
+  assert.strictEqual(getEventListeners(ac.signal, 'abort').length, 0);
+}
+
+{
+  // Test aborted with gc cleanup
+  const ac = new AbortController();
+  aborted(ac.signal, {}).then(common.mustNotCall());
+  setImmediate(() => {
+    global.gc();
+    ac.abort();
+    assert.strictEqual(ac.signal.aborted, true);
+    assert.strictEqual(getEventListeners(ac.signal, 'abort').length, 0);
+  });
+}
+
+{
+  // Fails with error if not provided abort signal
+  const sig = new EventTarget();
+  assert.rejects(aborted(sig, {}), {
+    name: 'TypeError',
+  });
+}
+
+{
+  // Fails if not provided a resource
+  const ac = new AbortController();
+  assert.rejects(aborted(ac.signal, null), {
+    name: 'TypeError',
+  });
+}