lib: add aborted() utility function

Fixes: #37220 Refs: #36607 PR-URL: #46494 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: Benjamin Gruenbaum <[email protected]> Reviewed-By: Antoine du Hamel <[email protected]>

Author: debadree25

doc/api/util.md

@@ -1977,6 +1977,51 @@ 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 is fulfilled when the `signal` is
+aborted. If the passed `resource` is garbage collected before the `signal` is
+aborted, the returned promise shall remain pending indefinitely.
+
+```cjs
+const{aborted } =require('node:util');
+
+constdependent=obtainSomethingAbortable();
+
+aborted(dependent.signal, dependent).then(() =>{
+// Do something when dependent is aborted.
+});
+
+dependent.on('event', () =>{
+dependent.abort();
+});
+```
+
+```mjs
+import{aborted } from'node:util';
+
+constdependent=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

@@ -8,6 +8,7 @@ const{
  ObjectDefineProperties,
  ObjectSetPrototypeOf,
  ObjectDefineProperty,
+ PromiseResolve,
  SafeFinalizationRegistry,
  SafeSet,
  Symbol,
@@ -22,11 +23,13 @@ const{
  kTrustEvent,
  kNewListener,
  kRemoveListener,
+ kWeakHandler,
 }=require('internal/event_target');
 const{
+ createDeferredPromise,
  customInspectSymbol,
- kEnumerableProperty,
  kEmptyObject,
+ kEnumerableProperty,
 }=require('internal/util');
 const{ inspect }=require('internal/util/inspect');
 const{
@@ -38,6 +41,8 @@ const{
 }=require('internal/errors');
 
 const{
+ validateAbortSignal,
+ validateObject,
  validateUint32,
 }=require('internal/validators');
 
@@ -94,7 +99,7 @@ function customInspect(self, obj, depth, options){
 return`${self.constructor.name}${inspect(obj,opts)}`;
 }
 
-functionvalidateAbortSignal(obj){
+functionvalidateThisAbortSignal(obj){
 if(obj?.[kAborted]===undefined)
 thrownewERR_INVALID_THIS('AbortSignal');
 }
@@ -132,15 +137,15 @@ class AbortSignal extends EventTarget{
  * @type{boolean}
  */
 getaborted(){
-validateAbortSignal(this);
+validateThisAbortSignal(this);
 return!!this[kAborted];
 }
 
 /**
  * @type{any}
  */
 getreason(){
-validateAbortSignal(this);
+validateThisAbortSignal(this);
 returnthis[kReason];
 }
 
@@ -202,7 +207,7 @@ class AbortSignal extends EventTarget{
 }
 
 [kTransfer](){
-validateAbortSignal(this);
+validateThisAbortSignal(this);
 constaborted=this.aborted;
 if(aborted){
 constreason=this.reason;
@@ -369,6 +374,24 @@ function transferableAbortController(){
 returnAbortController[kMakeTransferable]();
 }
 
+/**
+ * @param{AbortSignal} signal
+ * @param{any} resource
+ * @returns{Promise<void>}
+ */
+asyncfunctionaborted(signal,resource){
+if(signal===undefined){
+thrownewERR_INVALID_ARG_TYPE('signal','AbortSignal',signal);
+}
+validateAbortSignal(signal,'signal');
+validateObject(resource,'resource',{nullable: false,allowFunction: true,allowArray: true});
+if(signal.aborted)
+returnPromiseResolve();
+constabortPromise=createDeferredPromise();
+signal.addEventListener('abort',abortPromise.resolve,{[kWeakHandler]: resource,once: true});
+returnabortPromise.promise;
+}
+
 ObjectDefineProperties(AbortController.prototype,{
 signal: kEnumerableProperty,
 abort: kEnumerableProperty,
@@ -387,6 +410,7 @@ module.exports ={
  AbortController,
  AbortSignal,
  ClonedAbortSignal,
+ aborted,
  transferableAbortSignal,
  transferableAbortController,
 };

lib/util.js

@@ -400,5 +400,8 @@ module.exports ={
 gettransferableAbortController(){
 returnlazyAbortController().transferableAbortController;
 },
+getaborted(){
+returnlazyAbortController().aborted;
+},
  types
 };

test/parallel/test-aborted-util.js

@@ -0,0 +1,59 @@
+// Flags: --expose-gc
+'use strict';
+
+constcommon=require('../common');
+const{ aborted }=require('util');
+constassert=require('assert');
+const{ getEventListeners }=require('events');
+const{ spawn }=require('child_process');
+
+{
+// Test aborted works when provided a resource
+constac=newAbortController();
+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
+constac=newAbortController();
+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
+Promise.all([{},null,undefined,Symbol(),[],1,0,1n,true,false,'a',()=>{}].map((sig)=>
+assert.rejects(aborted(sig,{}),{
+code: 'ERR_INVALID_ARG_TYPE',
+})
+)).then(common.mustCall());
+}
+
+{
+// Fails if not provided a resource
+constac=newAbortController();
+Promise.all([null,undefined,0,1,0n,1n,Symbol(),'','a'].map((resource)=>
+assert.rejects(aborted(ac.signal,resource),{
+code: 'ERR_INVALID_ARG_TYPE',
+})
+)).then(common.mustCall());
+}
+
+{
+constchildProcess=spawn(process.execPath,['--input-type=module']);
+childProcess.on('exit',common.mustCall((code)=>{
+assert.strictEqual(code,13);
+}));
+childProcess.stdin.end(`
+ import{aborted } from 'node:util'
+ await aborted(new AbortController().signal,{});
+ `);
+}