Skip to content

Commit

Permalink
docs(import-bundle): Update bundle source formats, including endoScript
Browse files Browse the repository at this point in the history
  • Loading branch information
kriskowal committed Aug 31, 2024
1 parent 4af8ebf commit 91a7351
Showing 1 changed file with 9 additions and 3 deletions.
12 changes: 9 additions & 3 deletions packages/import-bundle/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,13 +18,19 @@ Each call to `importBundle` creates a new `Compartment`. The globals of the new

## Module Formats

The source can be bundled in a variety of "formats". By default, `bundleSource` uses a format named `getExports`, in which the source tree is linearized into a single CommonJS-style string, and wrapped in a callable function that provides the `exports` and `module.exports` context to which the exports can be attached. `importBundle` recognizes this format, and invokes the function thus defined, to return the namespace object.
The source can be bundled in a variety of "formats".

A more sophisticated format is named `nestedEvaluate`. In this mode, the source tree is converted into a table of evaluable strings, one for each original module. This table is then encoded and wrapped as before. The evaluation process uses a separate evaluator call for each module, providing an opportunity to attach a distinct `sourceMap` to each one. This preserves relative filenames in subsequent debugging information and stack traces.
By default, `bundleSource` uses a format named `endoZipBase64`, in which the source modules and a "compartment map" are captured in a Zip file and base-64 encoded. The compartment map describes how to construct a set of [Hardened JavaScript](https://hardenedjs.org) compartments and how to load and link the source modules between them.

The `endoScript` format captures the sources as a single JavaScript program that completes with the entry module's namespace object.

The `getExport` format captures the sources as a single CommonJS-style string, and wrapped in a callable function that provides the `exports` and `module.exports` context to which the exports can be attached.

More sophisticated than `getExport` is named `nestedEvaluate`. In this mode, the source tree is converted into a table of evaluable strings, one for each original module. This table is then encoded and wrapped as before. The evaluation process uses a separate evaluator call for each module, providing an opportunity to attach a distinct `sourceMap` to each one. This preserves relative filenames in subsequent debugging information and stack traces.

To set a base prefix for these relative filenames, provide the `filePrefix` option.

Note that the `nestedEvaluate` format requires an endowment named `require`, although it will only be called if the source tree imported one of the few modules on the `bundle-source` "external" list.
Note that the `nestedEvaluate` format receives a global endowment named `require`, although it will only be called if the source tree imported one of the few modules on the `bundle-source` "external" list.

## Options

Expand Down

0 comments on commit 91a7351

Please sign in to comment.