lib: add aborted() utility function

doc/api/util.md

@@ -1989,6 +1989,35 @@ const channel = new MessageChannel();
 channel.port2.postMessage(signal, [signal]);
 ```
 
+## `util.aborted(signal, resource)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+* `signal` {AbortSignal}
+* `resource` {any} Any non-null entity
+* Returns: {Promise}
+
+Listens to abort event on the provided `signal` and returns a promise which is
+resolved if an abort event is triggered. The function cleans up any
+event listeners depending on when the provided `resource` is garbage collected.
+
+```js
+const { aborted } = require('util');
+
+const ac = new AbortController();
+const dependent = {};
+
+aborted(ac.signal, dependent).then(() => {
+  // Do something when the abort event is triggered.
+});
+
+doSomething(dependent, ac.signal); // Can trigger the abort event
+```
+
 ## `util.types`
 
 <!-- YAML

lib/internal/abort_controller.js

@@ -14,7 +14,6 @@ const {
   SymbolToStringTag,
   WeakRef,
   PromiseResolve,
-  PromiseReject,
 } = primordials;
 
 const {
@@ -44,6 +43,7 @@ const {
 const {
   validateUint32,
   validateAbortSignal: abortSignalValidator,
+  validateObject,
 } = require('internal/validators');
 
 const {
@@ -367,12 +367,9 @@ function transferableAbortController() {
  * @param {any} resource
  * @returns {Promise<void>}
  */
-function aborted(signal, resource = null) {
-  try {
-    abortSignalValidator(signal, 'signal');
-  } catch (err) {
-    return PromiseReject(err);
-  }
+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();

test/parallel/test-aborted-util.js

@@ -6,15 +6,6 @@ const { aborted } = require('util');
 const assert = require('assert');
 const { getEventListeners } = require('events');
 
-{
-  // Test aborted works
-  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 works when provided a resource
   const ac = new AbortController();
@@ -39,7 +30,15 @@ const { getEventListeners } = require('events');
 {
   // Fails with error if not provided abort signal
   const sig = new EventTarget();
-  assert.rejects(aborted(sig), {
+  assert.rejects(aborted(sig, {}), {
+    name: 'TypeError',
+  });
+}
+
+{
+  // Fails if not provided a resource
+  const ac = new AbortController();
+  assert.rejects(aborted(ac.signal, null), {
     name: 'TypeError',
   });
 }