timers: graduate awaitable timers and improve docs

Signed-off-by: James M Snell <[email protected]> PR-URL: #38112 Reviewed-By: Antoine du Hamel <[email protected]> Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: Luigi Pinca <[email protected]> Reviewed-By: Bryan English <[email protected]> Reviewed-By: Benjamin Gruenbaum <[email protected]>

Author: jasnell

doc/api/timers.md

@@ -323,46 +323,100 @@ Cancels a `Timeout` object created by [`setTimeout()`][].
 ## Timers Promises API
 <!-- YAML
 added: v15.0.0
+changes:
+ - version: REPLACEME
+ pr-url: https://github.com/nodejs/node/pull/38112
+ description: Graduated from experimental.
 -->
 
-> Stability: 1 - Experimental
-
 The `timers/promises` API provides an alternative set of timer functions
 that return `Promise` objects. The API is accessible via
 `require('timers/promises')`.
 
-```js
-consttimersPromises=require('timers/promises');
+```mjs
+import{
+setTimeout,
+setImmediate,
+setInterval,
+} from'timers/promises';
+```
+
+```cjs
+const{
+setTimeout,
+setImmediate,
+setInterval,
+} =require('timers/promises');
 ```
 
 ### `timersPromises.setTimeout([delay[, value[, options]]])`
 <!-- YAML
 added: v15.0.0
 -->
 
-*`delay`{number} The number of milliseconds to wait before resolving the
-`Promise`. **Default:**`1`.
-*`value`{any} A value with which the `Promise` is resolved.
+*`delay`{number} The number of milliseconds to wait before fulfilling the
+promise. **Default:**`1`.
+*`value`{any} A value with which the promise is fulfilled.
 *`options`{Object}
 *`ref`{boolean} Set to `false` to indicate that the scheduled `Timeout`
  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`.
 
+```mjs
+import{
+setTimeout,
+} from'timers/promises';
+
+constres=awaitsetTimeout(100, 'result');
+
+console.log(res); // Prints 'result'
+```
+
+```cjs
+const{
+setTimeout,
+} =require('timers/promises');
+
+setTimeout(100, 'result').then((res) =>{
+console.log(res); // Prints 'result'
+});
+```
+
 ### `timersPromises.setImmediate([value[, options]])`
 <!-- YAML
 added: v15.0.0
 -->
 
-*`value`{any} A value with which the `Promise` is resolved.
+*`value`{any} A value with which the promise is fulfilled.
 *`options`{Object}
 *`ref`{boolean} Set to `false` to indicate that the scheduled `Immediate`
  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 `Immediate`.
 
+```mjs
+import{
+setImmediate,
+} from'timers/promises';
+
+constres=awaitsetImmediate('result');
+
+console.log(res); // Prints 'result'
+```
+
+```cjs
+const{
+setImmediate,
+} =require('timers/promises');
+
+setImmediate('result').then((res) =>{
+console.log(res); // Prints 'result'
+});
+```
+
 ### `timersPromises.setInterval([delay[, value[, options]]])`
 <!-- YAML
 added: v15.9.0
@@ -381,10 +435,28 @@ Returns an async iterator that generates values in an interval of `delay` ms.
 *`signal`{AbortSignal} An optional `AbortSignal` that can be used to
  cancel the scheduled `Timeout` between operations.
 
-```js
+```mjs
+import{
+setInterval,
+} from'timers/promises';
+
+constinterval=100;
+forawait (conststartTimeofsetInterval(interval, Date.now())){
+constnow=Date.now();
+console.log(now);
+if ((now - startTime) >1000)
+break;
+}
+console.log(Date.now());
+```
+
+```cjs
+const{
+setInterval,
+} =require('timers/promises');
+constinterval=100;
+
 (asyncfunction(){
-const{setInterval } =require('timers/promises');
-constinterval=100;
 forawait (conststartTimeofsetInterval(interval, Date.now())){
 constnow=Date.now();
 console.log(now);