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]>

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
-const timersPromises = 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';
+
+const res = await setTimeout(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';
+
+const res = await setImmediate('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';
+
+const interval = 100;
+for await (const startTime of setInterval(interval, Date.now())) {
+  const now = Date.now();
+  console.log(now);
+  if ((now - startTime) > 1000)
+    break;
+}
+console.log(Date.now());
+```
+
+```cjs
+const {
+  setInterval,
+} = require('timers/promises');
+const interval = 100;
+
 (async function() {
-  const { setInterval } = require('timers/promises');
-  const interval = 100;
   for await (const startTime of setInterval(interval, Date.now())) {
     const now = Date.now();
     console.log(now);