diff --git a/doc/api/esm.md b/doc/api/esm.md index ec4c7b1ce650c2..f74ab2f16b17cb 100644 --- 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` + + > 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 - - ```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` +}); +``` + ## 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