[WIP] import await

[littledan]

This patch updates the explainer to be in terms of requiring modules
containing top-level await to be imported with import await. Spec
text not yet written.

[littledan]

Thanks to @sokra and everyone at the JSKongress 2019 Deep Track for developing this idea!

[sokra]

What's the difference between import await "module" and await import("module")?

import await starts fetching during the Fetch and Parse phase, while await import() starts fetching during the Evaluation phase.

Multiple import await will run in parallel, while multiple await import() will run sequential.

Exports of import await can be analysed statically and incorrect export names will result in a SyntaxError. Analyzing await import() is harder and incorrect export names will result in undefined and a RuntimeError.

import await is hoisted, await import() is an Expression and not hoisted.

import await can only be placed on top-level, while await import() can be placed at top-level or in async functions at any location where an Expression is allowed.

import await must be used with a String Literal, while await import() can be used with any expression as argument (await import(`./data/${value}.js`))

[littledan]

Thanks for writing this! I added it to the FAQ.

[ljharb]

I like the general direction of this change, but I’m concerned about import await being viral. It’d be great if the only thing that makes a module async is adding TLA.

[domenic]

I would be opposed to the proposal moving forward with this change. By making callers need to know whether they are importing a module which awaits or not, this essentially makes the proposal sugar for the export default async function / await import() antipattern documented in the readme, and obviates its value.

To be clearer about why it's important for callers to be agnostic, one of the major use cases of top-level await is maintaining the module abstraction boundary while allowing the depended-upon module to add asynchronous initialization steps. @wycats has made this point in previous meetings.

Here is an example. Consider a module like so:

const template = `<p>Hello, my name is: <slot></slot></p>`;

customElements.define("name-tag", class extends HTMLElement {
  constructor() {
    super();
    this.attachShadow({ mode: 'open' }).innerHTML = template;
  }
});

which is then imported via

import "./name-tag.mjs";

Then the designer gets their hands on things. "This template is too simple!", they say. They beef it up, with a <style> element, a few wrapper divs, maybe some extra flair. The developer decides it'd be best if the designer worked on that in a separate file, name-tag-template.html. They refactor their code to pull in the template from that file, like so:

const template = await (await fetch(new URL("./name-tag-template.html", import.meta.url))).text();

customElements.define("name-tag", class extends HTMLElement {
  constructor() {
    super();
    this.attachShadow({ mode: 'open' }).innerHTML = template;
  }
});

The point of top-level await is that this is not a breaking change for the consumer of name-tag.mjs. Just like you are able to refactor one module into multiple modules, with top-level await, you can refactor from one module into multiple files, or in general multiple async initialization steps.

With the proposal in the OP, this refactoring becomes a breaking change, for the consumers of name-tag.mjs (recursively, throughout the entire graph).

One way to mitigate this would be if everyone everywhere preemptively replaced all import statements with await import statements. You could see this becoming an ESLint rule, perhaps even a recommended one. It's certainly one we'd enforce on any web projects. But that breaks when cross boundaries between code bases; a package author needs to make a breaking change and broadcast to their users, "any code that imports this package needs to switch their codebase from import to await import." And this of course then propagates, so any indirect dependents also need to update. Etc.

Slowly, gradually, and with much pain, we will either switch the entire JavaScript ecosystem to using await import instead of import, or we will declare that package authors which use top-level await are using a "bad part" of JS, and their packages should not be depended upon, and the feature dies out (except maybe at the top app-level).

Introducing this kind of dynamic into top-level await makes the proposal unusable for me as a package author, and for the cases we are interested in in the web component ecosystem in general.

[littledan]

@ljharb I'm not sure what you mean. What do you think should happen if you import a module which has a TLA? Are you suggesting semantics like #49?

[littledan]

@domenic Yes, this does add friction to the upgrade path; that's the idea of this change. There was an exact opposite concern that it would be unfortunate if a deep dependency became async, now all dependent modules are async. Seems like we just have to make a decision one way or the other on whether this transparent upgrade is desirable or not.

[jhnns]

@domenic @ljharb that's the idea of this change: using top-level await should be a breaking change for the module consumer. I think this is desired since async operations can take a significant amount of time. If anyone in the module graph was able to defer the application startup, it might become hard for application authors to find the cause for long startup times.

Another advantage of this change is that it would not change the way how module evaluation is currently specified. Introducing TLA to the specification would be a non-breaking change.

@domenic regarding your example: native HTML modules would make the module graph synchronous again.

Slowly, gradually, and with much pain, we will either switch the entire JavaScript ecosystem to using await import instead of import, or we will declare that package authors which use top-level await are using a "bad part" of JS, and their packages should not be depended upon, and the feature dies out (except maybe at the top app-level).

I think, this is a valid concern (and it's probably what @ljharb meant with TLA becoming viral). But it's also very speculative and hard to predict. If common things like HTML and CSS can be imported synchronously, I don't think that this pattern will become too popular. It might be a different story with Web Assembly modules though since synchronous compilation is discouraged by some engine implementers. If WASM modules become popular in the JS ecosystem, import await might become the de-facto standard for importing things in JavaScript.

However, I still like that the application developer is in control to decide whether to import await or to await import things. The explicit import await makes it clear which part of the module graph might take more time to initialize.

[ljharb]

@jhnns i have no issue with adding TLA being a breaking change; my issue is with adding import await being one.

[domenic]

@jhnns HTML modules will be async, not sync.

[littledan]

@domenic Good to know that Wasm modules aren't the only one. I can see how it's not so nice that you have to update all the imports to import await if you want to introduce a Wasm or HTML module in your dependency graph.

Do you have any references with more information about HTML modules being async? Maybe we could point to them from the presentation and the explainer here so people can learn more context.

[sokra]

The intention of import await was not to rewrite major parts of the imports to import await. Instead it should only used when needed, and the chain should be broken by using import() and non-top-level awaiting it.

This viral behavior is intentional and will make developers aware bad practices.

For web applications you should avoid that your application/entry point becomes an async module, even when other async modules like WASM are used. When your application becomes an async module this probably means the user will see a white screen until all async modules are resolved (i. e. until WASM is compiled). Instead viral import await makes this problem visible and it can be "solved" by breaking the chain with import() and adding spinners or whatever. I agree that there are also some use cases where it might be fine that the entry point becomes an async modules (i. e. Node.js), but for most things it's not good.

Note that the import await syntax didn't introduce the viral behavior. It was already there in the original proposal. Using the syntax only makes it visible to the developer.

[trotyl]

import statement

Is ImportDeclaration a Statement?

[littledan]

Eh, it's an explainer.

[littledan]

As presented in the March 2019 TC39 meeting, the champion group does not plan to take this approach, so closing the PR.