From 91a7351c0bef8d366161005c9f4f4d3bcda8e147 Mon Sep 17 00:00:00 2001 From: Kris Kowal Date: Fri, 2 Aug 2024 14:18:27 -0700 Subject: [PATCH] docs(import-bundle): Update bundle source formats, including endoScript --- packages/import-bundle/README.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/packages/import-bundle/README.md b/packages/import-bundle/README.md index 03c5cd5668..40b38e2ce4 100644 --- a/packages/import-bundle/README.md +++ b/packages/import-bundle/README.md @@ -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