doc: add note regarding unfinished TLA

PR-URL: #41434 Reviewed-By: Guy Bedford <[email protected]> Reviewed-By: Mohammed Keyvanzadeh <[email protected]> Reviewed-By: Luigi Pinca <[email protected]>
nodejs · Jan 14, 2022 · 60025bd · 60025bd
1 parent 10bdb59
commit 60025bd
Showing 1 changed file with 23 additions and 5 deletions.
diff --git a/doc/api/esm.md b/doc/api/esm.md
@@ -590,15 +590,16 @@ would provide the exports interface for the instantiation of `module.wasm`.
 
 ## Top-level `await`
 
+<!--
+added: v14.8.0
+-->
+
 > Stability: 1 - Experimental
 
-The `await` keyword may be used in the top level (outside of async functions)
-within modules as per the [ECMAScript Top-Level `await` proposal][].
+The `await` keyword may be used in the top level body of an ECMAScript module.
 
 Assuming an `a.mjs` with
 
-<!-- eslint-skip -->
-
 ```js
 export const five = await Promise.resolve(5);
 ```
@@ -615,6 +616,23 @@ console.log(five); // Logs `5`
 node b.mjs # works
 ```
 
+If a top level `await` expression never resolves, the `node` process will exit
+with a `13` [status code][].
+
+```js
+import { spawn } from 'child_process';
+import { execPath } from 'process';
+
+spawn(execPath, [
+  '--input-type=module',
+  '--eval',
+  // Never-resolving Promise:
+  'await new Promise(() => {})',
+]).once('exit', (code) => {
+  console.log(code); // Logs `13`
+});
+```
+
 <i id="esm_experimental_loaders"></i>
 
 ## Loaders
@@ -1425,7 +1443,6 @@ success!
 [Conditional exports]: packages.md#conditional-exports
 [Core modules]: modules.md#core-modules
 [Dynamic `import()`]: https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import#Dynamic_Imports
-[ECMAScript Top-Level `await` proposal]: https://github.com/tc39/proposal-top-level-await/
 [ES Module Integration Proposal for WebAssembly]: https://github.com/webassembly/esm-integration
 [Import Assertions]: #import-assertions
 [Import Assertions proposal]: https://github.com/tc39/proposal-import-assertions
@@ -1460,5 +1477,6 @@ success!
 [percent-encoded]: url.md#percent-encoding-in-urls
 [resolve hook]: #resolvespecifier-context-defaultresolve
 [special scheme]: https://url.spec.whatwg.org/#special-scheme
+[status code]: process.md#exit-codes
 [the official standard format]: https://tc39.github.io/ecma262/#sec-modules
 [url.pathToFileURL]: url.md#urlpathtofileurlpath