From ed808f903213f326914d65b1d53aa1c32b034ad2 Mon Sep 17 00:00:00 2001
From: James M Snell <jasnell@gmail.com>
Date: Tue, 27 Apr 2021 19:38:50 -0700
Subject: [PATCH] repl: document top level await limitation with const/let

Fixes: https://github.com/nodejs/node/issues/17669
Signed-off-by: James M Snell <jasnell@gmail.com>

PR-URL: https://github.com/nodejs/node/pull/38449
Reviewed-By: Jiawen Geng <technicalcute@gmail.com>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Darshan Sen <raisinten@gmail.com>
Reviewed-By: Yongsheng Zhang <zyszys98@gmail.com>
---
 doc/api/repl.md | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/doc/api/repl.md b/doc/api/repl.md
index a8c63291a5a719..bc2d74edde1573 100644
--- a/doc/api/repl.md
+++ b/doc/api/repl.md
@@ -233,6 +233,23 @@ undefined
 undefined
 ```
 
+One known limitation of using the `await` keyword in the REPL is that
+it will invalidate the lexical scoping of the `const` and `let`
+keywords.
+
+For example:
+
+```console
+> const m = await Promise.resolve(123)
+undefined
+> m
+123
+> const m = await Promise.resolve(234)
+undefined
+> m
+234
+```
+
 ### Reverse-i-search
 <!-- YAML
 added: v13.6.0