timers: allow promisified timeouts/immediates to be canceled

Using the new experimental AbortController...
Signed-off-by: James M Snell <jasnell@gmail.com>
PR-URL: #33833
Backport-PR-URL: #38386
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Gus Caplan <me@gus.host>

Author: jasnell

doc/api/timers.md

@@ -248,8 +248,47 @@ The [`setImmediate()`][], [`setInterval()`][], and [`setTimeout()`][] methods
 each return objects that represent the scheduled timers. These can be used to
 cancel the timer and prevent it from triggering.
 
-It is not possible to cancel timers that were created using the promisified
-variants of [`setImmediate()`][], [`setTimeout()`][].
+For the promisified variants of [`setImmediate()`][] and [`setTimeout()`][],
+an [`AbortController`][] may be used to cancel the timer. When canceled, the
+returned Promises will be rejected with an `'AbortError'`.
+
+For `setImmediate()`:
+
+```js
+constutil=require('util');
+constsetImmediatePromise=util.promisify(setImmediate);
+
+constac=newAbortController();
+constsignal=ac.signal;
+
+setImmediatePromise('foobar', { signal })
+ .then(console.log)
+ .catch((err) => {
+if (err.message==='AbortError')
+console.log('The immediate was aborted');
+ });
+
+ac.abort();
+```
+
+For `setTimeout()`:
+
+```js
+constutil=require('util');
+constsetTimeoutPromise=util.promisify(setTimeout);
+
+constac=newAbortController();
+constsignal=ac.signal;
+
+setTimeoutPromise(1000, 'foobar', { signal })
+ .then(console.log)
+ .catch((err) => {
+if (err.message==='AbortError')
+console.log('The timeout was aborted');
+ });
+
+ac.abort();
+```
 
 ### `clearImmediate(immediate)`
 <!-- YAML
@@ -280,6 +319,7 @@ added: v0.0.1
 Cancels a `Timeout` object created by [`setTimeout()`][].
 
 [Event Loop]: https://nodejs.org/en/docs/guides/event-loop-timers-and-nexttick/#setimmediate-vs-settimeout
+[`AbortController`]: globals.md#globals_class_abortcontroller
 [`TypeError`]: errors.md#errors_class_typeerror
 [`clearImmediate()`]: timers.md#timers_clearimmediate_immediate
 [`clearInterval()`]: timers.md#timers_clearinterval_timeout

lib/timers.js

@@ -28,6 +28,12 @@ const {
  SymbolToPrimitive
 }=primordials;
 
+const{
+codes: {ERR_INVALID_ARG_TYPE}
+}=require('internal/errors');
+
+letDOMException;
+
 const{
  immediateInfo,
  toggleImmediateRef
@@ -129,6 +135,11 @@ function enroll(item, msecs) {
  * DOM-style timers
  */
 
+functionlazyDOMException(message){
+if(DOMException===undefined)
+DOMException=internalBinding('messaging').DOMException;
+returnnewDOMException(message);
+}
 
 functionsetTimeout(callback,after,arg1,arg2,arg3){
 validateCallback(callback);
@@ -160,11 +171,40 @@ function setTimeout(callback, after, arg1, arg2, arg3) {
 returntimeout;
 }
 
-setTimeout[customPromisify]=function(after,value){
+setTimeout[customPromisify]=function(after,value,options={}){
 constargs=value!==undefined ? [value] : value;
-returnnewPromise((resolve)=>{
+if(options==null||typeofoptions!=='object'){
+returnPromise.reject(
+newERR_INVALID_ARG_TYPE(
+'options',
+'Object',
+options));
+}
+const{ signal }=options;
+if(signal!==undefined&&
+(signal===null||
+typeofsignal!=='object'||
+!('aborted'insignal))){
+returnPromise.reject(
+newERR_INVALID_ARG_TYPE(
+'options.signal',
+'AbortSignal',
+signal));
+}
+// TODO(@jasnell): If a decision is made that this cannot be backported
+// to 12.x, then this can be converted to use optional chaining to
+// simplify the check.
+if(signal&&signal.aborted)
+returnPromise.reject(lazyDOMException('AbortError'));
+returnnewPromise((resolve,reject)=>{
 consttimeout=newTimeout(resolve,after,args,false,true);
 insert(timeout,timeout._idleTimeout);
+if(signal){
+signal.addEventListener('abort',()=>{
+clearTimeout(timeout);
+reject(lazyDOMException('AbortError'));
+},{once: true});
+}
 });
 };
 
@@ -300,8 +340,39 @@ function setImmediate(callback, arg1, arg2, arg3) {
 returnnewImmediate(callback,args);
 }
 
-setImmediate[customPromisify]=function(value){
-returnnewPromise((resolve)=>newImmediate(resolve,[value]));
+setImmediate[customPromisify]=function(value,options={}){
+if(options==null||typeofoptions!=='object'){
+returnPromise.reject(
+newERR_INVALID_ARG_TYPE(
+'options',
+'Object',
+options));
+}
+const{ signal }=options;
+if(signal!==undefined&&
+(signal===null||
+typeofsignal!=='object'||
+!('aborted'insignal))){
+returnPromise.reject(
+newERR_INVALID_ARG_TYPE(
+'options.signal',
+'AbortSignal',
+signal));
+}
+// TODO(@jasnell): If a decision is made that this cannot be backported
+// to 12.x, then this can be converted to use optional chaining to
+// simplify the check.
+if(signal&&signal.aborted)
+returnPromise.reject(lazyDOMException('AbortError'));
+returnnewPromise((resolve,reject)=>{
+constimmediate=newImmediate(resolve,[value]);
+if(signal){
+signal.addEventListener('abort',()=>{
+clearImmediate(immediate);
+reject(lazyDOMException('AbortError'));
+},{once: true});
+}
+});
 };
 
 functionclearImmediate(immediate){

test/parallel/test-timers-promisified.js

@@ -1,3 +1,4 @@
+// Flags: --no-warnings --experimental-abortcontroller
 'use strict';
 constcommon=require('../common');
 constassert=require('assert');
@@ -36,3 +37,56 @@ const setImmediate = promisify(timers.setImmediate);
 assert.strictEqual(value,'foobar');
 }));
 }
+
+{
+constac=newAbortController();
+constsignal=ac.signal;
+assert.rejects(setTimeout(10,undefined,{ signal }),/AbortError/);
+ac.abort();
+}
+
+{
+constac=newAbortController();
+constsignal=ac.signal;
+ac.abort();// Abort in advance
+assert.rejects(setTimeout(10,undefined,{ signal }),/AbortError/);
+}
+
+{
+constac=newAbortController();
+constsignal=ac.signal;
+assert.rejects(setImmediate(10,{ signal }),/AbortError/);
+ac.abort();
+}
+
+{
+constac=newAbortController();
+constsignal=ac.signal;
+ac.abort();// Abort in advance
+assert.rejects(setImmediate(10,{ signal }),/AbortError/);
+}
+
+{
+Promise.all(
+[1,'',false,Infinity].map((i)=>assert.rejects(setImmediate(10,i)),{
+code: 'ERR_INVALID_ARG_TYPE'
+})).then(common.mustCall());
+
+Promise.all(
+[1,'',false,Infinity,null,{}].map(
+(signal)=>assert.rejects(setImmediate(10,{ signal })),{
+code: 'ERR_INVALID_ARG_TYPE'
+})).then(common.mustCall());
+
+Promise.all(
+[1,'',false,Infinity].map(
+(i)=>assert.rejects(setTimeout(10,null,i)),{
+code: 'ERR_INVALID_ARG_TYPE'
+})).then(common.mustCall());
+
+Promise.all(
+[1,'',false,Infinity,null,{}].map(
+(signal)=>assert.rejects(setTimeout(10,null,{ signal })),{
+code: 'ERR_INVALID_ARG_TYPE'
+})).then(common.mustCall());
+}