Typescript: Top Level Await

[kitsonk]

Search Terms

top level await

Suggestion

The ability to utilise await directly at the top level of a module or a script. Currently the compiler does not support this, though it is becoming increasing possible to accomplish it in certain runtimes.

Top level await is currently a Stage 2 TC39 proposal. (I was unable to find any tracking issue for implementation, therefore this issue)

There was this issue #20923, which was marked as a question, but really was this feature request.

Use Cases

There are many patterns the are emerging that require top level await, many which are documented in the TC39 Proposal. The current workaround that is seen a lot in the wild is wrapping an async iife. There are lots instances where the main _thread_ of program wants to utilise await to load resources.

The value of having top level await in Node.js REPL and Chrome debugger is now allowed. There is an outstanding issue to allow it in ts-node.

I know the core team is _really really_ adverse to implementing things that haven't reached Stage 3, but there are sufficient patterns in the wild that allow this and an increasing number for situations where it can be allowed, that allowing it under a flag feels like something that might be entertained until it is delivered under Stage 4. If we in user-land choose the potential 👣 🔫 at our own risk, so be it.

Examples

The following:

async function main() {
  const dynamic = await import('./dynamic-thing.mjs');
  const data = await fetch(dynamic.url);
  console.log(data);
}
main();

Could be rewritten as:

const dynamic = await import('./dynamic-thing');
const data = await fetch(dynamic.url);
console.log(data);

Checklist

Technically, this would allow syntax which would change the runtime behaviour of JavaScript and allows new expression level syntax which is currently not permitted (but specifically reserved by TC39 for this purpose).

My suggestion meets these guidelines:

• [X] This wouldn't be a breaking change in existing TypeScript / JavaScript code
• [ ] This wouldn't change the runtime behavior of existing JavaScript code
• [X] This could be implemented without emitting different JS based on the types of the expressions
• [ ] This isn't a runtime feature (e.g. new expression-level syntax)

[weswigham]

@kitsonk I don't think we can safely implement TLA until at least the variant is decided upon - otherwise how exports work in modules with TLA is liable to change (and thereby typechecking). I get that it's great in a REPL context - but at the top level of a module with exports it is much less straightforward!

[kitsonk]

I understand that it is likely more complicated than just allowing it, because variant A or variant B would have significant impacts on CFA. From a usefulness perspective, the proposed optional constraint of only allowing it in modules without exports would be sufficient for my selfish needs. While there still _might_ be an impact on CFA, the static analysis could/would work as it does now for not top level awaiting and it would be guaranteed to _know_ what the shape of the exports (because it has none). I suspect that restriction would work for most other real world use cases at the moment (and if it didn't there would be good justification of why TypeScript can't know).

@weswigham is it worth at least having a tracking issue at this stage of the proposal?

[sebmck]

Has there been an movement on this issue? @RyanCavanaugh, I see you added the "Waiting for TC39" label. What are you waiting on? The advancement to stage 3? The compromise listed above by @kitsonk seems like a good one that would solve the vast majority of use-cases without an impact on type checking semantics.

[RyanCavanaugh]

We're waiting on stage 3 or 4 since there are possible runtime semantics implications.

"This so reasonable that surely TC39 won't come up with some other behavior" has bitten us enough that we're not really willing to risk it when it comes to runtime behavior.

[kitsonk]

The proposal has gone Stage 3.

[jhpratt]

@RyanCavanaugh Any plans for implementation?

[weswigham]

We can probably put the parsing and typechecking behavior into the backlog at some point, but be aware that ultimately the way TLA executes comes down to the module loader. Webpack can enable it pretty easily by modifying the bundled module loader (although probably not quite to spec, since implementation to spec requires inspecting promise internals to skip event loop turns), but in the context of the cjs loader or pre-TLA esm loader (as we usually consider we emit for), there's really no way to downlevel TLA (although I think amd modules might just support it out of the box, which could be nice). It's just not downlevelable without whole program rewriting, and even then exactly implementing the spec is _almost_ impossible (technically not completely impossible with the inclusion of a native node module to synchronously unwrap a resolved promise) because of the event loop turn behaviors.

We can _probably_ at least tag this as Needs Proposal - minimally we could probably support it when targeting esnext with no downlevel, like import.meta.

[kitsonk]

Allowing it through, with no downlevel emit would be perfect for my use case. Treating it like import.meta makes sense. It needs to be adopted somehow.

[robpalme]

I agree with @kitsonk - there are use-cases today that would benefit from parsing and type-checking without any downlevel with esnext target.

• webpack 5 supports TLA behind a flag
• Acorn has support.
• V8 implementation is in progress
• We have a module loader that could use this today ;-)

[Kingwl]

The part of lexer and parser seems nearly be done... Is there any progress branch or tracking on this one?

[shand-obs]

Is this in typescript@next (dev20191004)?

It seems like TLA works when I have "target": "esnext" (emits await at top level). It does not work when I have "target": "es5" even though I have "module": "esnext". Is this going to emit TLA downlevel? If it's not, it isn't going to be very useful with webpack 5. Unless I'm missing something.

I can ignore the error with // @ts-ignore but it emits "yield" instead of "await".

[CyrusNajmabadi]

@RyanCavanaugh @DanielRosenwasser this mentioned Milestone 3.7. Is this actually available to use in the latest TS builds? If so, is there something i need to do to enable this? Thanks!

[kitsonk]

I spoke to Daniel at TSConf. He said it wasn't going to make 3.7 and he needed to update the IP.

[hayd]

Related: accounting for top-level for-await https://github.com/tc39/proposal-top-level-await/pull/133

[stevefan1999-personal]

https://gist.github.com/Rich-Harris/0b6f317657f5167663b493c722647221

[CyrusNajmabadi]

@stevefan1999-personal

Therefore, a version of TLA that solves the original issue is a valuable addition to the language, and I'm in full support of the current proposal, which you can read here.