From 6ea55ad8dda7352004d82767e140d3d8b72d5bc5 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 1/3] timers: graduate awaitable timers

Signed-off-by: James M Snell <jasnell@gmail.com>
---
 doc/api/timers.md | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/doc/api/timers.md b/doc/api/timers.md
index 77501fd9fab149..4571b87ae08911 100644
--- a/doc/api/timers.md
+++ b/doc/api/timers.md
@@ -323,10 +323,12 @@ 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/00000
+    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')`.

From c6bdd6da895e3056c2d8fae36785c4d1915abf3e Mon Sep 17 00:00:00 2001
From: James M Snell <jasnell@gmail.com>
Date: Tue, 6 Apr 2021 10:09:39 -0700
Subject: [PATCH 2/3] doc: improve awaitable timers docs

Signed-off-by: James M Snell <jasnell@gmail.com>
---
 doc/api/timers.md | 88 ++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 79 insertions(+), 9 deletions(-)

diff --git a/doc/api/timers.md b/doc/api/timers.md
index 4571b87ae08911..f52296e47fed0c 100644
--- a/doc/api/timers.md
+++ b/doc/api/timers.md
@@ -333,8 +333,20 @@ 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]]])`
@@ -342,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.
@@ -352,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.
@@ -365,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
@@ -383,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);

From 8e8a2b4a81f91b29274f61c21b6c00d7a4701304 Mon Sep 17 00:00:00 2001
From: James M Snell <jasnell@gmail.com>
Date: Tue, 6 Apr 2021 11:09:02 -0700
Subject: [PATCH 3/3] [Squash] fixup

Co-authored-by: Antoine du Hamel <duhamelantoine1995@gmail.com>
---
 doc/api/timers.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/api/timers.md b/doc/api/timers.md
index f52296e47fed0c..65453a4576b40e 100644
--- a/doc/api/timers.md
+++ b/doc/api/timers.md
@@ -325,7 +325,7 @@ Cancels a `Timeout` object created by [`setTimeout()`][].
 added: v15.0.0
 changes:
   - version: REPLACEME
-    pr-url: https://github.com/nodejs/node/pull/00000
+    pr-url: https://github.com/nodejs/node/pull/38112
     description: Graduated from experimental.
 -->