diff --git a/doc/api/esm.md b/doc/api/esm.md index 7d8decd754b79e..8c3716df74029c 100644 --- a/doc/api/esm.md +++ b/doc/api/esm.md @@ -591,15 +591,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); ``` @@ -616,6 +617,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 @@ -1426,7 +1444,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 @@ -1461,5 +1478,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