a2969ecd27
This commit provides a "system_loader_es5.js" bundle loader which will be added to the bundle when the target is < ES2017, which is the minimum target syntax required for "system_loader.js". Supports #5913 (via Deno.bundle()) with a couple caveats: * Allowing "deno bundle" to take a different target is not supported, as we specifically ignore "target" when passed in a TypeScript config file. This is because deno bundle is really intended to generate bundles that work in Deno. It is an unintentional side effect that some bundles are loadable in browsers. * While a target of "es3" will be accepted, the module loader will still only be compatible with ES5 or later. Realistically no one should be expecting bundles generated by Deno to be used on IE8 and prior, and there is just too much "baggage" to support that at this point. This is a minor variation of 75bb9d, which exposed some sort of internal V8 bug. Ref #6358 This is 100% authored by Kitson Kelly. Github might change the author when landing so I'm leaving this in: Co-authored-by: Kitson Kelly <me@kitsonkelly.com>
4.5 KiB
Deno TypeScript Crate
This crate provides utilities to compile typescript, bundle it up, and create a V8 snapshot, all during build. Snapshots allow the executable to startup fast.
system_loader.js
This is a minimalistic implementation of a
System module loader. It is specifically
designed to load modules that are emitted from TypeScript the module format is
"system" and a single "outfile" is supplied, which is commonly refereed to
as a bundle.
Because this loader becomes part of an emitted bundle under Deno.bundle() and
deno bundle, it has minimal comments and very terse and cryptic syntax, which
isn't very self documenting. Because of this, a guide to this file is provided
here.
A bundle of System modules expects a System.register() function to be in scope
for registering the modules. Modules that are emitted from TypeScript in a
single out file always pass 3 arguments, the module specifier, an array of
strings of modules specifiers that this module depends upon, and finally a
module factory.
The module factory requires two arguments to be passed, a function for exporting
values and a context object. We have to bind to some information in the
environment to provide these, so gC gets the context and gE gets the export
function to be passed to a factory. The context contains information like the
module specifier, a reference to the dynamic import() and the equivalent of
import.meta. The export function takes either two arguments of an named export
and its value, or an object record of keys of the named exports and the values
of the exports.
Currently, TypeScript does not re-write dynamic imports which resolve to static
strings (see
microsoft/TypeScript#37429),
which means the import specifier for a dynamic import which has been
incorporated in the bundle does not automatically match a module specifier that
has been registered in the bundle. The di() function provides the capability
to try to identify relative import specifiers and resolve them to a specifier
inside the bundle. If it does this, it resolves with the exports of the module,
otherwise it simply passes the module specifier to import() and returns the
resulting promise.
The running of the factories is handled by rF(). When the factory is run, it
returns an object with two keys, execute and setters. execute is a
function which finalises that instantiation of the module, and setters which
is an array of functions that sets the value of the exports of the dependent
module.
The gExp() and gExpA() are the recursive functions which returns the exports
of a given module. It will determine if the module has been fully initialized,
and if not, it will gather the exports of the dependencies, set those exports in
the module via the setters and run the modules execute(). It will then
always return or resolve with the exports of the module.
As of TypeScript 3.8, top level await is supported when emitting ES or System
modules. When Deno creates a module bundle, it creates a valid, self-contained
ES module which exports the exports of the "main" module that was used when the
bundle was created. If a module in the bundle requires top-level-await, then the
execute() function is emitted as an async function, returning a promise. This
means that in order to export the values of the main module, the instantiation
needs to utilise top-level-await as well.
At the time of this writing, while V8 and other JavaScript engines have implemented top-level-await, no browsers have it implemented, meaning that most browsers could not consume modules that require top-level-await.
In order to allow more browsers to consume bundles, there is an argument that is
passed to the __instantiate() function which determines if the code is
bootstrapped asynchronously or not. When emitting a bundle that contains a
module that requires top-level-await, Deno will detect this and utilise
await __instantiate(main, true).
The system_loader_es5.js is a transpiled version of system_loader.js that is
designed to work with ES5 or later, and will be used when the bundle target is <
ES2017. While ES3 is still a potential target which can be passed in a
tsconfig.json to Deno, any resulting bundle will not be compatible, as there
is a need to utilise items like Object.defineProperty().