How can I use async/await at the top level?
I can't seem to wrap my head around why this does not work.
Because main
returns a promise; all async
functions do.
At the top level, you must either:
Use a top-level
async
function that never rejects (unless you want "unhandled rejection" errors), orUse
then
andcatch
, or(Coming soon!) Use top-level
await
, a proposal that has reached Stage 3 in the process that allows top-level use ofawait
in a module.
#1 - Top-level async
function that never rejects
(async () => { try { var text = await main(); console.log(text); } catch (e) { // Deal with the fact the chain failed }})();
Notice the catch
; you must handle promise rejections / async exceptions, since nothing else is going to; you have no caller to pass them on to. If you prefer, you could do that on the result of calling it via the catch
function (rather than try
/catch
syntax):
(async () => { var text = await main(); console.log(text);})().catch(e => { // Deal with the fact the chain failed});
...which is a bit more concise (I like it for that reason).
Or, of course, don't handle errors and just allow the "unhandled rejection" error.
#2 - then
and catch
main() .then(text => { console.log(text); }) .catch(err => { // Deal with the fact the chain failed });
The catch
handler will be called if errors occur in the chain or in your then
handler. (Be sure your catch
handler doesn't throw errors, as nothing is registered to handle them.)
Or both arguments to then
:
main().then( text => { console.log(text); }, err => { // Deal with the fact the chain failed });
Again notice we're registering a rejection handler. But in this form, be sure that neither of your then
callbacks doesn't throw any errors, nothing is registered to handle them.
#3 top-level await
in a module
You can't use await
at the top level of a non-module script, but the top-level await
proposal (Stage 3) allows you to use it at the top level of a module. It's similar to using a top-level async
function wrapper (#1 above) in that you don't want your top-level code to reject (throw an error) because that will result in an unhandled rejection error. So unless you want to have that unhandled rejection when things go wrong, as with #1, you'd want to wrap your code in an error handler:
// In a module, once the top-level `await` proposal landstry { var text = await main(); console.log(text);} catch (e) { // Deal with the fact the chain failed}
Note that if you do this, any module that imports from your module will wait until the promise you're await
ing settles; when a module using top-level await
is evaluated, it basically returns a promise to the module loader (like an async
function does), which waits until that promise is settled before evaluating the bodies of any modules that depend on it.
Top-Level await
has moved to stage 3, so the answer to your question How can I use async/await at the top level? is to just add await
the call to main()
:
async function main() { var value = await Promise.resolve('Hey there'); console.log('inside: ' + value); return value;}var text = await main(); console.log('outside: ' + text)
Or just:
const text = await Promise.resolve('Hey there');console.log('outside: ' + text)
Compatibility
- v8 since Oct 2019
- the REPL in Chrome DevTools, Node.js and Safari web inspector
- Node v13.3+ behind the flag
--harmony-top-level-await
- TypeScript 3.8+ (issue)
- Deno since Oct 2019
- Webpack@v5.0.0-alpha.15
To give some further info on top of current answers:
The contents of a node.js
file are currently concatenated, in a string-like way, to form a function body.
For example if you have a file test.js
:
// Amazing test file!console.log('Test!');
Then node.js
will secretly concatenate a function that looks like:
function(require, __dirname, ... perhaps more top-level properties) { // Amazing test file! console.log('Test!');}
The major thing to note, is that the resulting function is NOT an async function. So you cannot use the term await
directly inside of it!
But say you need to work with promises in this file, then there are two possible methods:
- Don't use
await
directly inside the function - Don't use
await
Option 1 requires us to create a new scope (and this scope can be async
, because we have control over it):
// Amazing test file!// Create a new async function (a new scope) and immediately call it!(async () => { await new Promise(...); console.log('Test!');})();
Option 2 requires us to use the object-oriented promise API (the less pretty but equally functional paradigm of working with promises)
// Amazing test file!// Create some sort of promise...let myPromise = new Promise(...);// Now use the object-oriented APImyPromise.then(() => console.log('Test!'));
It would be interesting to see node add support for top-level await
!