[JS] Top-level await

[chrisdavidmills]

Acceptance criteria

1. • The listed features are documented sufficiently on MDN
2. • BCD is updated
3. • Interactive example and data repos are updated if appropriate
4. • The content has been reviewed as needed

Features to document

1. Top-level await. There are a number of pages/resources that could do with being updated to cover this:
   • mention on https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/async_function
   • mention on https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function
   • https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/await
   • https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of
   • https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Asynchronous/Async_await
   • https://github.com/mdn/learning-area/tree/master/javascript/asynchronous/async-await
   • https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script ?
   • Service worker pages?
   • https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules
   • Any other specific JS pages that need creating?

Related Gecko bugs

1. • Implement the Top-level await proposal

For folks helping with Firefox-related documentation features — make sure above AC have been done, but also:

• Set bugs to dev-doc-complete
• Add entry to Firefox release notes if feature is enabled in release
• Add entry to Firefox experimental features page if feature is not yet enabled in release

[chrisdavidmills]

@codehag You said you'd be interested in taking part in this one.

@Elchi3 This one sounds up your street too!

[jpmedley]

For what it's worth, I'm 99% certain this will ship in Chrome 89, which will reach beta the last week of January.

[chrisdavidmills]

@jpmedley feel free to add a "Related Chromium bugs" section, if you think that'd help. I'd love to promote such practices.

[chrisdavidmills]

@Rumyra pinging you on this one, to remind you about it. Consider this one highest priority for now.

@Elchi3 would you be willing and able to assist Ruth in scoping out the pages that need creating/updating for this one?

I also wondered if I could get @sideshowbarker and @jpmedley interested in helping to document this, depending on how much work we think is required here.

Thanks all.

[sideshowbarker]

I also wondered if I could get @sideshowbarker and @jpmedley interested in helping to document this, depending on how much work we think is required here.

I’d be very glad to put some time into it to help

[Rumyra]

Thanks peeps! I imagine the list above is pretty exhaustive, but I'm just going to go through and check.

I've been debating whether to split this up into separate issues, but I'll see what's involved - a check list might suffice 👍

[Rumyra]

Here's a draft todo, in priority order:

(As top level await doesn't involved async I have only included modifications on these pages if necessary.)

• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules Add a 'Top Level Await' section & explainer. Add a working example to the https://github.com/mdn/learning-area/tree/master/javascript/asynchronous/async-await (there doesn't appear to be a module part of this repo) found it

Help needed:

• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/await update text to remove only valid inside async & include info about top level await. Add an example of use in modules
• https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Asynchronous/Async_await amend any info about await only available in async. Possibly include an example of await in modules (or a link to the module example)
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function remove note saying await is only valid inside async functions -> possibly amend to include using await in modules
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of not sure updates are necessary, however possibly an example of use in modules?
• https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script I can't see any updates really needed here, unless a <script> example of a await module is needed

From what I can tell it's been blocked in service workers until peeps make decisions w3c/ServiceWorker#1407 correct me if I'm wrong however.

@chrisdavidmills let me know what you think
@sideshowbarker is there anything particular you would like to do? I think if someone tackles a working example (and updates learning pages) someone else could tackle the copy amends on existing pages (I'm happy with either).

EDIT: I'm making a working example for testing, happy to add that to the repo

Release stuff:

• I'm updating BCD now to reflect chrome flag - else it's fine
• Add entry to experimental FF

[chrisdavidmills]

LGTM, thanks @Rumyra !

[jpmedley]

I also wondered if I could get @sideshowbarker and @jpmedley interested in helping to document this, depending on how much work we think is required here.

I can help too.

[Rumyra]

I've updated the above list and moved some amends to 'help needed' if either @sideshowbarker or @jpmedley would like to pick them up (thanks :) )

[Rumyra]

• I have made an attempt at the above - see this PR Top level await #1677 for most of the content stuff

• Working example pr top level await js-examples#10

• Adding spec data pr Top level await yari#2669

• BCD is in

[Rumyra]

I believe all PRs are in for this now - should just need flag set to dev-doc-complete @chrisdavidmills 👍

[jpmedley]

For what it's worth, I'm 99% certain this will ship in Chrome 89, which will reach beta the last week of January.

It made it into beta. Certainty for Chrome 89 now at 99.9%.

[chrisdavidmills]

@Rumyra sorry for taking so long to check this out! This work looks amazing, thank you so much.

I've set the bug to DDC, and now we can close this.