From 15b8e6b1c43c53400e9c48111969e42216a1a6f2 Mon Sep 17 00:00:00 2001
From: James M Snell <jasnell@gmail.com>
Date: Tue, 6 Apr 2021 10:00:37 -0700
Subject: [PATCH] timers: graduate awaitable timers and improve docs

Signed-off-by: James M Snell <jasnell@gmail.com>

PR-URL: https://github.com/nodejs/node/pull/38112
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Bryan English <bryan@bryanenglish.com>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
---
 doc/api/timers.md | 94 +++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 83 insertions(+), 11 deletions(-)

diff --git a/doc/api/timers.md b/doc/api/timers.md
index 77501fd9fab149..65453a4576b40e 100644
--- a/doc/api/timers.md
+++ b/doc/api/timers.md
@@ -323,16 +323,30 @@ 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]]])`
@@ -340,9 +354,9 @@ const timersPromises = require('timers/promises');
 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.
@@ -350,12 +364,32 @@ added: v15.0.0
   * `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.
@@ -363,6 +397,26 @@ added: v15.0.0
   * `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);