timers: introduce setInterval async iterator

Added setInterval async generator to timers\promises.
Utilises async generators to provide an iterator compatible with
`for await`.
Co-Authored-By: Fabian Cook <hello@fabiancook.dev>
fix message
PR-URL: #37153
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>

Author: Linkgoron

doc/api/timers.md

@@ -363,6 +363,38 @@ added: v15.0.0
 *`signal` {AbortSignal} An optional `AbortSignal` that can be used to
  cancel the scheduled `Immediate`.
 
+### `timersPromises.setInterval([delay[, value[, options]]])`
+<!-- YAML
+added: REPLACEME
+-->
+
+Returns an async iterator that generates values in an interval of `delay` ms.
+
+*`delay` {number} The number of milliseconds to wait between iterations.
+**Default**: `1`.
+*`value` {any} A value with which the iterator returns.
+*`options` {Object}
+*`ref` {boolean} Set to `false` to indicate that the scheduled `Timeout`
+ between iterations should not require the Node.js event loop to
+ remain active.
+**Default**: `true`.
+*`signal` {AbortSignal} An optional `AbortSignal` that can be used to
+ cancel the scheduled `Timeout` between operations.
+
+```js
+(asyncfunction() {
+const { setInterval } =require('timers/promises');
+constinterval=100;
+forawait (conststartTimeofsetInterval(interval, Date.now())) {
+constnow=Date.now();
+console.log(now);
+if ((now - startTime) >1000)
+break;
+ }
+console.log(Date.now());
+})();
+```
+
 [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

lib/timers/promises.js

@@ -18,7 +18,11 @@ const {
 codes: {ERR_INVALID_ARG_TYPE}
 }=require('internal/errors');
 
-const{ validateAbortSignal }=require('internal/validators');
+const{
+ validateAbortSignal,
+ validateBoolean,
+ validateObject,
+}=require('internal/validators');
 
 functioncancelListenerHandler(clear,reject){
 if(!this._destroyed){
@@ -111,7 +115,59 @@ function setImmediate(value, options = {}) {
 ()=>signal.removeEventListener('abort',oncancel)) : ret;
 }
 
+asyncfunction*setInterval(after,value,options={}){
+validateObject(options,'options');
+const{ signal, ref =true}=options;
+validateAbortSignal(signal,'options.signal');
+validateBoolean(ref,'options.ref');
+
+if(signal?.aborted)
+thrownewAbortError();
+
+letonCancel;
+letinterval;
+try{
+letnotYielded=0;
+letcallback;
+interval=newTimeout(()=>{
+notYielded++;
+if(callback){
+callback();
+callback=undefined;
+}
+},after,undefined,true,true);
+if(!ref)interval.unref();
+insert(interval,interval._idleTimeout);
+if(signal){
+onCancel=()=>{
+// eslint-disable-next-line no-undef
+clearInterval(interval);
+if(callback){
+callback(PromiseReject(newAbortError()));
+callback=undefined;
+}
+};
+signal.addEventListener('abort',onCancel,{once: true});
+}
+
+while(!signal?.aborted){
+if(notYielded===0){
+awaitnewPromise((resolve)=>callback=resolve);
+}
+for(;notYielded>0;notYielded--){
+yieldvalue;
+}
+}
+thrownewAbortError();
+}finally{
+// eslint-disable-next-line no-undef
+clearInterval(interval);
+signal?.removeEventListener('abort',onCancel);
+}
+}
+
 module.exports={
  setTimeout,
  setImmediate,
+ setInterval,
 };