|
| 1 | +# import() |
| 2 | + |
| 3 | +This is a work-in-progress repository for a proposal for adding a "function-like" `import()` module loading syntactic form to JavaScript. It has not yet been formally proposed to the committee, but has been discussed with the module-loading community in [whatwg/loader#149](https://github.com/whatwg/loader/issues/149). You can view the in-progress [spec draft](https://domenic.github.io/proposal-import-function/) and take part in the discussions on the [issue tracker](https://github.com/domenic/proposal-import-function/issues). |
| 4 | + |
| 5 | +## Motivation and use cases |
| 6 | + |
| 7 | +The existing syntactic forms for importing modules are static declarations. They accept a string literal as the module specifier, and introduce bindings into the local scope via a pre-runtime "linking" process. This is a great design for the 90% case, and supports important use cases such as static analysis, bundling tools, and tree shaking. |
| 8 | + |
| 9 | +However, it's also desirable to be able to dynamically load parts of a JavaScript application at runtime. This could be because of factors only known at runtime (such as the user's language), or for performance reasons (not loading code until it is likely to be used). Such dynamic code-loading has a long history, especially on the web, but also in Node.js (to delay startup costs). The existing `import` syntax does not support such use cases. |
| 10 | + |
| 11 | +Truly dynamic code loading also enables advanced scenarios, such as racing multiple modules against each other and choosing the first to successfully load. |
| 12 | + |
| 13 | +## Proposed solution |
| 14 | + |
| 15 | +This proposal adds an `import(specifier)` syntactic form, which acts in many ways like a function (but see below). It returns a promise for the module namespace object of the requested module, which is created after fetching, instantiating, and evaluating all of the module's dependencies, as well as the module itself. |
| 16 | + |
| 17 | +Here `specifier` will be interpreted the same way as in an `import` declaration (i.e., the same strings will work in both places). However, while `specifier` is a string it is not necessarily a string literal; thus code like `` import(`./language-packs/${navigator.language}.js`) `` will work—something impossible to accomplish with the usual `import` declarations. |
| 18 | + |
| 19 | +`import()` is proposed to work in both scripts and modules. This gives script code an easy asynchronous entry point into the module world, allowing it to start running module code. |
| 20 | + |
| 21 | +Like the existing JavaScript module specification, the exact mechanism for retrieving the module is left up to the host environment (e.g., web browsers or Node.js). This is done by introducing a new host-environment-implemented abstract operation, HostFetchImportedModule, in addition to reusing and slightly tweaking the existing HostResolveImportedModule. |
| 22 | + |
| 23 | +## Alternative solutions explored |
| 24 | + |
| 25 | +There are a number of other ways of potentially accomplishing the above use cases. Here we explain why we believe `import()` is the best possibility. |
| 26 | + |
| 27 | +### Using host-specific mechanisms |
| 28 | + |
| 29 | +It's possible to dynamically load modules in certain host environments, such as web browsers, by abusing host-specific mechanisms for doing so. Using HTML's `<script type="module">`, the following code would give similar functionality to `import()`: |
| 30 | + |
| 31 | +```js |
| 32 | + |
| 33 | +function importModule(url) { |
| 34 | + return new Promise((resolve, reject) => { |
| 35 | + const script = document.createElement("script"); |
| 36 | + const tempGlobal = "__tempModuleLoadingVariable" + Math.random().toString(32).substring(2); |
| 37 | + script.type = "module"; |
| 38 | + script.textContent = `import * as m from "${url}"; window.${tempGlobal} = m;`; |
| 39 | + |
| 40 | + script.onload = () => { |
| 41 | + resolve(window[tempGlobal]); |
| 42 | + delete window[tempGlobal]; |
| 43 | + script.remove(); |
| 44 | + }; |
| 45 | + |
| 46 | + script.onerror = () => { |
| 47 | + reject(new Error("Failed to load module script with URL " + url)); |
| 48 | + delete window[tempGlobal]; |
| 49 | + script.remove(); |
| 50 | + }; |
| 51 | + |
| 52 | + document.documentElement.appendChild(script); |
| 53 | + }); |
| 54 | +} |
| 55 | +``` |
| 56 | + |
| 57 | +However, this has a number of deficiencies, apart from the obvious ugliness of creating a temporary global variable and inserting a `<script>` element into the document tree only to remove it later. |
| 58 | + |
| 59 | +The most obvious is that it takes a URL, not a module specifier; furthermore, that URL is relative to the document's URL, and not to the script executing. This introduces a needless impedance mismatch for developers, as they need to switch contexts when using the different ways of importing modules, and it makes relative URLs a potential bug-farm. |
| 60 | + |
| 61 | +Another clear problem is that this is host-specific. Node.js code cannot use the above function, and would have to invent its own, which probably would have different semantics (based, likely, on filenames instead of URLs). This leads to non-portable code. |
| 62 | + |
| 63 | +Finally, it isn't standardized, meaning people will need to pull in or write their own version each time they want to add dynamic code loading to their app. This could be fixed by adding it as a standard method in HTML (`window.importModule`), but if we're going to standardize something, let's instead standardize `import()`, which is nicer for the above reasons. |
| 64 | + |
| 65 | +### An actual function |
| 66 | + |
| 67 | +Drafts of the [Loader](https://whatwg.github.io/loader/) ideas collection have at various times had actual functions (not just function-like syntactic forms) named `System.import()` or `System.loader.import()` or similar, which accomplish the same use cases. |
| 68 | + |
| 69 | +The biggest problem here, as previously noted by the spec's editors, is how to interpret the specifier argument to these functions. Since these are just functions, which are the same across the entire Realm and do not vary per script or module, the function must interpret its argument the same no matter from where it is called. (Unless something truly weird like stack inspection is implemented.) So likely this runs into similar problems as the document base URL issue for the `importModule` function above, where relative module specifiers become a bug farm and mismatch any nearby `import` declarations. |
| 70 | + |
| 71 | +## Relation to existing work |
| 72 | + |
| 73 | +So far module work has taken place in three spaces: |
| 74 | + |
| 75 | +- [The JavaScript specification](https://tc39.github.io/ecma262/#sec-modules), which mostly defines the syntax of modules, defering to the host environment via [HostResolveImportedModule](https://tc39.github.io/ecma262/#sec-hostresolveimportedmodule); |
| 76 | +- [The HTML Standard](https://html.spec.whatwg.org/multipage/), which defines [`<script type="module">`](https://html.spec.whatwg.org/multipage/scripting.html#the-script-element), how to [fetch modules](https://html.spec.whatwg.org/multipage/webappapis.html#fetching-scripts), and fulfills its duties as a host environment by specifying [HostResolveImportedModule](https://html.spec.whatwg.org/multipage/webappapis.html#hostresolveimportedmodule(referencingmodule,-specifier)) on top of those foundations; |
| 77 | +- [The Loader specification](https://whatwg.github.io/loader/), which is a collection of interesting ideas prototyping ways of creating a runtime-configurable loading pipeline and creating modules reflectively (i.e. not from source text) |
| 78 | + |
| 79 | +This proposal would be a small expansion of the existing JavaScript and HTML capabilities, using the same framework of specifying syntactic forms in the JavaScript specification, which delegate to the host environment for their heavy lifting. HTML's infrastructure for fetching and resolving modules would be leveraged to define its side of the story. Similarly, Node.js would supply its own definitions for HostFetchImportedModule and HostResolveImportedModule to make this proposal work there. |
| 80 | + |
| 81 | +The ideas in the Loader specification would largely stay the same, although probably this would either supplant the current `System.loader.import()` proposal or make `System.loader.import()` a lower-level version that is used in specialized circumstances. The Loader specification would continue to work on prototyping more general ideas for pluggable loading pipelines and reflective modules, which over time could be used to generalize HTML and Node's host-specific pipelines. |
| 82 | + |
| 83 | +Concretely, this repository is intended as a TC39 proposal to advance through the stages process, specifying the `import()` syntax and the relevant host environment hooks. It will likely also contain an outline of or link to the proposed changes to HTML as a host environment. |
0 commit comments