es-module-shims 2.5.0 → 2.6.0

package/README.md

@@ -30,7 +30,7 @@ Because we are still using the native module loader the edge cases work out comp
 Include ES Module Shims with a `async` attribute on the script, then include an import map and module scripts normally:
 
 ```html
-<script async src="https://ga.jspm.io/npm:es-module-shims@2.5.0/dist/es-module-shims.js"></script>
+<script async src="https://ga.jspm.io/npm:es-module-shims@2.6.0/dist/es-module-shims.js"></script>
 
 <!-- https://generator.jspm.io/#U2NhYGBkDM0rySzJSU1hKEpNTC5xMLTQM9Az0C1K1jMAAKFS5w0gAA -->
 <script type="importmap">
@@ -520,7 +520,7 @@ In addition CSS files need to be served with a valid CSS content type.
 
 Implements the [WebAssembly ESM Integration](https://github.com/WebAssembly/esm-integration) spec, including support for source phase imports.
 
-In shim mode, Wasm modules are always supported. In polyfill mode, Wasm modules require the `polyfillEnable: ['wasm-module-sources']` (or `'wasm-modules-instances'` for instance imports) [init option](#polyfill-enable-option).
+In shim mode, Wasm modules are always supported. In polyfill mode, Wasm modules require the `polyfillEnable: ['wasm-module-sources']` (or `'wasm-module-instances'` for instance imports) [init option](#polyfill-enable-option).
 
 WebAssembly module exports are made available as module exports and WebAssembly module imports will be resolved using the browser module loader.
 
@@ -686,19 +686,19 @@ const worker = new Worker(getWorkerScriptURL('myEsModule.js'));
 
 Provide a `esmsInitOptions` on the global scope before `es-module-shims` is loaded to configure various aspects of the module loading process:
 
-* [polyfillEnable](#polyfill-enable)
+* [polyfillEnable](#polyfill-enable-option)
+* [polyfillDisable](#polyfill-disable-option)
 * [enforceIntegrity](#enforce-integrity)
 * [fetch](#fetch-hook)
 * [mapOverrides](#overriding-import-map-entries)
 * [nativePassthrough](#native-passthrough)
 * [modulepreload](#modulepreload)
 * [noLoadEventRetriggers](#no-load-event-retriggers)
-* [globalLoadEventRetrigger](#global-load-event-retrigger)
 * [nonce](#nonce)
 * [onerror](#error-hook)
 * [onpolyfill](#polyfill-hook)
 * [resolve](#resolve-hook)
-* [revokeBlobURLs](#revoke-blob-urls)
+* [source](#source-hook)
 * [shimMode](#shim-mode-option)
 * [skip](#skip)
 * [version](#version)
@@ -710,14 +710,14 @@ window.esmsInitOptions = {
   shimMode: true, // default false
   // Enable newer modules features
   polyfillEnable: ['wasm-module-sources'], // default empty
+  // Disable features that are unused
+  polyfillDisable: ['css-modules'], // default empty
   // Custom CSP nonce
   nonce: 'n0nce', // default is automatic detection
   // Don't retrigger load events on module scripts (DOMContentLoaded, domready, window 'onload')
   noLoadEventRetriggers: true, // default false
   // Skip source analysis of certain URLs for full native passthrough
   skip: /^https:\/\/cdn\.com/, // defaults to null
-  // Clean up blob URLs after execution
-  revokeBlobURLs: true, // default false
   // Secure mode to not support loading modules without integrity
   // (integrity is always verified even when disabled though)
   enforceIntegrity: true, // default false
@@ -734,6 +734,8 @@ window.esmsInitOptions = {
   onpolyfill: () => {}, // default logs to the console
   // Hook all module resolutions
   resolve: (id, parentUrl, resolve) => resolve(id, parentUrl), // default is spec resolution
+  // Hook module source loading
+  source: (url, options, parentUrl, defaultSourceHook) => ({ type: 'js', source: 'export var p = 5' }),
   // Hook source fetch function
   fetch: (url, options) => fetch(url, options), // default is native
   // Hook import.meta construction
@@ -794,15 +796,27 @@ In adddition, the `"all"` option will enable all features.
 </script>
 ```
 
-The above is necessary to enable CSS modules and JSON modules alongside TypeScript type stripping support.
+The reason the `polyfillEnable` option is needed is because ES Module Shims implements a performance optimization where if a browser supports modern modules features to an expected baseline of import maps support, it will skip all polyfill source analysis resulting in full native passthrough performance.
 
-#### Baseline Support Analysis Opt-Out
+### Pollyfill Disable Option
 
-The reason the `polyfillEnable` option is needed is because ES Module Shims implements a performance optimization where if a browser supports modern modules features to an expected baseline of import maps support, it will skip all polyfill source analysis resulting in full native passthrough performance.
+Conversely to `polyfillEnable` it can be beneficial to dissable unused features where excluding those features from the baseline allows avoiding unnecessary feature detections or unnecessary analysis of module graphs.
+
+This option effectively lowers the baseline support allowing wider passthrough cases.
 
-If the application code then tries to use modern features like CSS modules beyond this baseline it won't support those features. As a result all modules features which are considered newer or beyond the recommended baseline require explicit enabling. This common baseline itself will change to track the common future modules baseline supported by this project for each release cycle.
+The supported options currently are just `css-modules` and `json-modules`.
+
+For example:
+
+```html
+<script type="esms-options">
+{
+  "polyfillDisable": ["css-modules", "json-modules"]
+}
+</script>
+```
 
-This option can also be set to `true` to entirely disable the native passthrough system and ensure all sources are fetched and analyzed through ES Module Shims. This will still avoid duplicate execution since module graphs are still only reexecuted when they use unsupported native features, but there is a small extra cost in doing the analysis.
+will disable the CSS and JSON feature detections, and lower the baseline passthrough modules support from Chrome 123, Firefox 138 and Safari 17.2 down to Chrome 64, Safari 11.1 and Firefox 67.
 
 ### Enforce Integrity
 
@@ -989,6 +1003,8 @@ Overriding this hook with an empty function will disable the default polyfill lo
 
 In the above, running in latest Chromium browsers, nothing will be logged, while running in an older browser that does not support newer features like import maps the console log will be output.
 
+> As this hook does not affect execution, it is recommended for use in polyfill mode.
+
 #### Error hook
 
 You can provide a function to handle errors during the module loading process by providing an `onerror` option:
@@ -1002,6 +1018,8 @@ You can provide a function to handle errors during the module loading process by
 <script async src="es-module-shims.js"></script>
 ```
 
+> As this hook does not affect execution, it is recommended for use in polyfill mode.
+
 #### Import Hook
 
 The import hook is supported for both shim and polyfill modes and provides an async hook which can ensure any necessary work is done before a top-level module import or dynamic `import()` starts further processing.
@@ -1019,15 +1037,12 @@ The import hook is supported for both shim and polyfill modes and provides an as
 </script>
 ```
 
+> It is usually recommended to use shim mode with module customization hooks. When the resolve hook is enabled in polyfill mode (or any other hooks), native passthrough will be disabled and modules may be executed twice if they correctly execute without the hook.
+
 #### Resolve Hook
 
 The resolve hook is supported for both shim and polyfill modes and allows full customization of the resolver, while still having access to the original resolve function.
 
-Note that in polyfill mode the resolve hook may not be called for all modules when native passthrough is occurring and that it still will not affect
-the native passthrough executions.
-
-If the resolve hook should apply for all modules in the entire module graph, make sure to set `polyfillEnable: true` to [disable the baseline support analysis opt-out](#baseline-support-analysis-opt-out).
-
 ```js
 <script>
   window.esmsInitOptions = {
@@ -1043,6 +1058,59 @@ If the resolve hook should apply for all modules in the entire module graph, mak
 </script>
 ```
 
+> It is usually recommended to use shim mode with module customization hooks. When the resolve hook is enabled in polyfill mode (or any other hooks), native passthrough will be disabled and modules may be executed twice if they correctly execute without the hook.
+
+#### Source Hook
+
+The source hook used to obtain the module source for a given URL, allowing for the implementation
+of virtual module sources.
+
+Note that only valid fetch scheme URLs are supported - `http:` / `https:` / `data:` / `blob:` / `file:`.
+`https:` or `file:` is therefore recommended for virtual module paths.
+
+For example:
+
+```html
+<script>
+const virtualFs = {
+  'index.js': `import './src/dep.js';`,
+  'src/dep.js': 'console.log("virtual source execution!")'
+};
+esmsInitOptions = {
+  source (url, fetchOpts, parent, defaultSourceHook) {
+    // Only virtualize sources under the URL file:///virtual-pkg/ (i.e. via
+    // `import 'file:///virtual-pkg/index.js'`.
+    if (!url.startsWith('file:///virtual-pkg/')) return defaultSourceHook(url, fetchOpts, parent);
+
+    // Strip the query string prefix for hot reloading workflow support
+    const versionQueryParam = url.match(/\?v=\d+$/);
+    if (versionQueryParam) url = url.slice(0, -versionQueryParam[0].length);
+
+    // Lookup the virtual source from the virtual filesystem and return if found
+    const virtualSource = virtualFs[url.slice('file:///virtual-pkg/'.length)];
+    if (!virtualSource) throw new Error(`Virtual module ${url} not found, imported from ${parent}`);
+    return {
+      type: 'js',
+      source: virtualSource
+    };
+  }
+};
+</script>
+```
+
+For support in hot reloading workflows, note that the ?v={Number} version query
+string suffix will be passed so needs to be checked and removed if applicable.
+
+For JS, CSS, JSON and TypeScript, it provides the source text string.
+For WebAssembly, it provides the compiled WebAssembly.Module record.
+
+The default implementation uses globalThis.fetch to obtain the response and then
+the 'content-type' MIME type header to infer the module type, per HTML semantics.
+
+URL may be returned differently from the request URL because responseURL
+is allowed to be distinct from requestURL in the module system even thoough
+requestURL is used as the registry key only.
+
 #### Meta Hook
 
 The meta hook allows customizing the `import.meta` object in each module scope.
@@ -1069,6 +1137,8 @@ import assert from 'assert';
 assert.ok(import.meta.custom.startsWith('custom value'));
 ```
 
+> It is usually recommended to use shim mode with module customization hooks. When the resolve hook is enabled in polyfill mode (or any other hooks), native passthrough will be disabled and modules may be executed twice if they correctly execute without the hook.
+
 #### Fetch Hook
 
 The fetch hook is supported for shim mode only.
@@ -1126,6 +1196,8 @@ window.esmsInitOptions = {
 }
 ```
 
+> It is usually recommended to use shim mode with module customization hooks. When the resolve hook is enabled in polyfill mode (or any other hooks), native passthrough will be disabled and modules may be executed twice if they correctly execute without the hook.
+
 ## Implementation Details
 
 ### Import Rewriting