es-module-shims 1.10.0 → 2.0.0

package/README.md

@@ -2,18 +2,15 @@
 
 Polyfills import maps and other ES Modules features on top of the baseline native ESM support in browsers.
 
-With import maps now supported by all major browsers, ES Module Shims entirely bypasses processing for the [74% of users](https://caniuse.com/import-maps) with native import maps support.
+With import maps now supported by all major browsers, ES Module Shims entirely bypasses processing for the [91% of users](https://caniuse.com/import-maps) with native import maps support.
 
 For the remaining users, the highly performant (see [benchmarks](#benchmarks)) production and [CSP-compatible](#csp-support) shim kicks in to rewrite module specifiers driven by the [Web Assembly ES Module Lexer](https://github.com/guybedford/es-module-lexer).
 
 The following modules features are polyfilled:
 
 * [Import Maps](#import-maps) polyfill.
-* Dynamic `import()` shimming when necessary in eg older Firefox versions.
-* `import.meta` and `import.meta.url`.
 * [JSON](#json-modules) and [CSS modules](#css-modules) with import assertions (when enabled).
 * [Wasm modules](#wasm-modules) with support for Source Phase Imports (when enabled).
-* [`<link rel="modulepreload">` is shimmed](#modulepreload) in browsers without import maps support.
 
 When running in shim mode, module rewriting is applied for all users and custom [resolve](#resolve-hook) and [fetch](#fetch-hook) hooks can be implemented allowing for custom resolution and streaming in-browser transform workflows.
 
@@ -30,7 +27,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@1.10.0/dist/es-module-shims.js"></script>
+<script async src="https://ga.jspm.io/npm:es-module-shims@2.0.0/dist/es-module-shims.js"></script>
 
 <!-- https://generator.jspm.io/#U2NhYGBkDM0rySzJSU1hKEpNTC5xMLTQM9Az0C1K1jMAAKFS5w0gAA -->
 <script type="importmap">
@@ -65,9 +62,9 @@ This error is important - it means that the native browser loader didn't execute
 at link time, and before execution time. And this is what allows the polyfill to be able to reexecute the modules and their dependencies
 without risk of duplicate execution.
 
-The ES Module Shims polyfill will analyze the browser to see if it supports import maps. If it does, it doesn't do anything more,
-otherwise it will analyze all module scripts on the page to see if any of them have bare specifier imports that will fail like this.
-If one is found, it will then be reexecuted through ES Module Shims using its internal shimming of modules features.
+The ES Module Shims polyfill will analyze the browser to check its fine-grained support for various import maps and modules features.
+If it is deeemed to support a baseline set of features, and multiple import maps are not in use, the polyfill will do no further work. Otherwise, it
+will analyze all module scripts on the page to see if any of them have static module syntax that would fail. If found, that graph will then be reexecuted through ES Module Shims using its internal rewriting of import statements to polyfill features.
 
 When the polyfill kicks in another console log message is output(which can be disabled or customized via the [polyfill hook](#polyfill-hook)):
 
@@ -75,6 +72,9 @@ When the polyfill kicks in another console log message is output(which can be di
 ^^ Module error above is polyfilled and can be ignored ^^
 ```
 
+The fetch options used by the polyfill are carefully followed per the spec. In older Firefox and Safari this fetch network cache is
+not fully shared with the polyfill so separate entries can be seen in the network tab, network-level cache coalescing is still seen at the very least.
+
 ### Polyfill Edge Case: Dynamic Import
 
 Only static link-time errors are polyfilled, not runtime errors.
@@ -127,45 +127,52 @@ If a static failure is not possible and dynamic import must be used, one alterna
 
 When running in polyfill mode, it can be thought of that are effectively two loaders running on the page - the ES Module Shims polyfill loader, and the native loader.
 
-Note that instances are not shared between these loaders for consistency and performance, since some browsers do not properly share the fetch cache and native loader cache resulting in a double fetch which would be inefficient.
+Whenever possible, the polyfill loader will share native modules that can be correctly executed, with one exception per the previous section - modules which use dynamic import, which are imported as dependencies of modules which require polyfill features.
 
-As a result, if you have two module graphs - one native and one polyfilled, they will not share the same dependency instance, for example:
+For example consider two shimmed modules, both of which use import maps:
 
-```html
-<script type="importmap">
-{
-  "imports": {
-    "dep": "/dep.js"
-  }
-}
-</script>
-<script type="module">
-import '/dep.js';
-</script>
-<script type="module">
-import 'dep';
-</script>
+`shim-a.js`
+```js
+import 'mapped-dep-a';
 ```
 
-```dep
-console.log('DEP');
+`shim-b.js`
+```js
+import 'mapped-dep-b';
 ```
 
-When polyfilling import maps, ES Module Shims will pick up on the second import failure and reexecute `/dep.js` as a new instance, logging `"DEP"` twice.
+where `mapped-dep-a` resolves to `/dep-a.js` and `mapped-dep-b` resolves to `/dep-b.js`, respectively containing:
 
-For this reason it is important to always ensure all modules hit the polyfill path, either by having all graphs use import maps at the top-level, or via `importShim` directly.
+`/dep-a.js`
+```js
+console.log('dep a');
+```
+
+`/dep-b.js`
+```js
+console.log('dep b');
+import(expr);
+```
+
+While the shim modules are always loaded in the shim loader, the `dep-a.js` module is loaded from the native loader since it does not require any polyfilling.
+
+On th other hand, `dep-b.js` is loaded from the shim loader as well _because it was loaded by a polyfilled parent graph and uses dynamic import_. Within the polyfill loader, the `import(expr)` is replaced with `importShim(expr)` to support import maps. This is in contrast to top-level native graphs which do not get shimmed per the previous section.
+
+As a result, `import('/dep-a.js')` in the native loader is the same instance as the `dep-a.js` loaded by `shim-a.js`, but `dep-b` would be executed twice if passed into `import('/dep-b.js')` - the shim loader and native loader instances are separate, and `dep b` would be logged twice.
 
-If you really need to support instance sharing with the native loader, a useful workaround is to use the [`skip` option](#skip) to list modules which should always be loaded via the native loader:
+Note that this is the ONLY scenario in which instance sharing will not otherwise occur in the polyfill loader.
+
+A workaround to this instance sharing case is to use the [`skip` option](#skip) to list modules which should always be loaded via the native loader (which also saves on analysis work time for performance):
 
 ```html
 <script type="esms-options">
 {
-  "skip": ["/dep.js"]
+  "skip": ["/dep-b.js"]
 }
 </script>
 ```
 
-The above would then fully cause dependency module instance to be shared between ES Module Shims and the native loader, with the polyfill then logging `"DEP"` only once.
+The above would then fully cause dependency module instance of dep-b to be shared between ES Module Shims and the native loader, with the polyfill then logging `"dep b"` only once.
 
 #### No Shim Scripts
 
@@ -215,38 +222,31 @@ Works in all browsers with [baseline ES module support](https://caniuse.com/#fea
 
 Browser Compatibility on baseline ES modules support **with** ES Module Shims:
 
-| ES Modules Features                             | Chrome (61+)                         | Firefox (60+)                        | Safari (10.1+)                       |
+| ES Modules Features                             | Chrome (71+)                         | Firefox (60+)                        | Safari (10.1+)                       |
 | ----------------------------------------------- | ------------------------------------ | ------------------------------------ | ------------------------------------ |
 | [modulepreload](#modulepreload)                 | :heavy_check_mark:                   | :heavy_check_mark:                   | :heavy_check_mark:                   |
-| [Dynamic Import](#dynamic-import)               | :heavy_check_mark:                   | :heavy_check_mark:                   | :heavy_check_mark:                   |
-| [import.meta.url](#importmetaurl)               | :heavy_check_mark:                   | :heavy_check_mark:                   | :heavy_check_mark:                   |
 | [Import Maps](#import-maps)                     | :heavy_check_mark:                   | :heavy_check_mark:                   | :heavy_check_mark:                   |
+| [Import Map Integrity](#import-map-integrity)   | :heavy_check_mark:                   | :heavy_check_mark:                   | :heavy_check_mark:                   |
+| [Multiple Import Maps](#multiple-import-maps)   | :heavy_check_mark:                   | :heavy_check_mark:                   | :heavy_check_mark:                   |
 | [JSON Modules](#json-modules)                   | :heavy_check_mark:                   | :heavy_check_mark:                   | :heavy_check_mark:                   |
-| [CSS Modules](#css-modules)                     | :heavy_check_mark:<sup>1</sup>       | :heavy_check_mark:<sup>1</sup>       | :heavy_check_mark:<sup>1</sup>       |
+| [CSS Modules](#css-modules)                     | :heavy_check_mark:                   | :heavy_check_mark:                   | :heavy_check_mark:                   |
 | [Wasm Modules](#wasm-modules)                   | 89+                                  | 89+                                  | 15+                                  |
-| [import.meta.resolve](#resolve)                 | :heavy_check_mark:                   | :heavy_check_mark:                   | :heavy_check_mark:                   |
-| [Module Workers](#module-workers) (via wrapper) | 63+                                  | ~113+                                | 15+                                  |
-| Top-Level Await (unpolyfilled<sup>3</sup>)      | 89+                                  | 89+                                  | 15+                                  |
-
-* 1: _CSS module support requires a separate [Constructable Stylesheets polyfill](https://github.com/calebdwilliams/construct-style-sheets#readme)._
-* 2: _Top-level await support is not currently polyfilled but is possible for ES Module Shims to implement for intermediate browser versions, with the feature request tracking in https://github.com/guybedford/es-module-shims/issues/5. The compatibility gap with native modules is currently < 5% of users so it may not even be necessary._
 
 Browser compatibility **without** ES Module Shims:
 
-| ES Modules Features                | Chrome             | Firefox            | Safari             |
-| ---------------------------------- | ------------------ | ------------------ | ------------------ |
-| [modulepreload](#modulepreload)    | 66+                | :x:                | :x:                |
-| [Dynamic Import](#dynamic-import)  | 63+                | 67+                | 11.1+              |
-| [import.meta.url](#importmetaurl)  | ~76+               | ~67+               | ~12+ ❕<sup>1</sup> |
-| [Import Maps](#import-maps)        | 89+                | 108+               | 16.4+              |
-| [JSON Modules](#json-modules)      | 91+                | :x:                | :x:                |
-| [CSS Modules](#css-modules)        | 95+                | :x:                | :x:                |
-| [Wasm Modules](#wasm-modules)      | :x:                | :x:                | :x:                |
-| [import.meta.resolve](#resolve)    | :x:                | :x:                | :x:                |
-| [Module Workers](#module-workers)  | ~68+               | ~113+              | 15+                |
-| Top-Level Await                    | 89+                | 89+                | 15+                |
-
-* ❕<sup>1</sup>: On module redirects, Safari returns the request URL in `import.meta.url` instead of the response URL as per the spec.
+| ES Modules Features                           | Chrome             | Firefox            | Safari             |
+| --------------------------------------------- | ------------------ | ------------------ | ------------------ |
+| [modulepreload](#modulepreload)               | 66+                | 115+               | 17.5+              |
+| [import.meta.url](#importmetaurl)             | ~76+               | ~67+               | ~12+               |
+| [Import Maps](#import-maps)                   | 89+                | 108+               | 16.4+              |
+| [Import Map Integrity](#import-map-integrity) | 127+               | :x:                | :x:                |
+| [Multiple Import Maps](#multiple-import-maps) | Pending            | :x:                | :x:                |
+| [JSON Modules](#json-modules)                 | 123+               | :x:                | 17.2+              |
+| [CSS Modules](#css-modules)                   | 123+               | :x:                | :x:                |
+| [Wasm Modules](#wasm-modules)                 | :x:                | :x:                | :x:                |
+| import.meta.resolve                           | 105+               | 106+               | 16.4+              |
+| [Module Workers](#module-workers)             | ~68+               | ~113+              | 15+                |
+| Top-Level Await                               | 89+                | 89+                | 15+                |
 
 ### Import Maps
 
@@ -280,18 +280,6 @@ Using this polyfill we can write:
 
 All modules are still loaded with the native browser module loader, but with their specifiers rewritten then executed as Blob URLs, so there is a relatively minimal overhead to using a polyfill approach like this.
 
-#### Integrity
-
-The `"integrity"` field for import maps is supported when possible, throwing an error in es-module-shims when the integrity does not match the expected value.
-
-#### Multiple Import Maps
-
-Multiple import maps are not currently supported in any native implementation, Chromium support is currently being tracked in https://bugs.chromium.org/p/chromium/issues/detail?id=927119.
-
-In polyfill mode, multiple import maps are therefore not supported.
-
-In shim mode, support for multiple `importmap-shim` scripts follows the [import map extensions](https://github.com/guybedford/import-maps-extensions) proposal.
-
 #### External Import Maps
 
 External import maps (using a `"src"` attribute) are not currently supported in any native implementation.
@@ -300,9 +288,13 @@ In polyfill mode, external import maps are therefore not supported.
 
 In shim mode, external import maps are fully supported.
 
-#### Dynamic Import Maps
+### Multiple Import Maps
+
+Multiple import maps have been recently implemented in Chromium in https://bugs.chromium.org/p/chromium/issues/detail?id=927119, including supporting dynamically loading import maps even after modules have been loaded.
 
-Support for dynamically injecting import maps with JavaScript via eg:
+In polyfill mode, multiple import maps are supported.
+
+Support for dynamically injecting import maps with JavaScript via e.g.:
 
 ```js
 document.body.appendChild(Object.assign(document.createElement('script'), {
@@ -311,11 +303,64 @@ document.body.appendChild(Object.assign(document.createElement('script'), {
 }));
 ```
 
-is supported in Chromium, provided it is injected before any module loads and there is no other import map yet loaded (multiple import maps are not supported).
+is also provided using mutation observers.
+
+The caveat for multiple import map support polyfill support in browsers that only support a single import map is per the usual "polyfill rule" for es-module-shims - only those top-level graphs with static import feailures can be polyfilled.
+
+Therefore, imports that would otherwise be supported fine by the first map can't be polyfilled, for example:
+
+```html
+<script type="importmap">
+{
+  "imports": {
+    "a": "/a.js"
+  }
+}
+</script>
+<script type="importmap">
+{
+  "scopes": {
+    "/": {
+      "a": "/b.js"
+    }
+  }
+}
+</script>
+<script type="module">
+import 'a';
+</script>
+```
 
-Both modes in ES Module Shims support dynamic injection using DOM Mutation Observers.
+In the above, browsers with single import maps support will resolve `/a.js` and the polyfill will not apply, while browsers without any import maps support will be polyfilled to resolve `/b.js`.
 
-While in polyfill mode the same restrictions apply that multiple import maps, import maps with a `src` attribute, and import maps loaded after the first module load are not supported, in shim mode all of these behaviours are fully enabled for `"importmap-shim"`.
+Instead, following the usual advice, make sure to design the app to either have static failures or not on all polyfill environments to get well-defined polyfill behaviour:
+
+```html
+<script type="importmap">
+{
+  "imports": {
+    "a": "/a.js"
+  }
+}
+</script>
+<script type="importmap">
+{
+  "imports": {
+    "b": "/b.js"
+  }
+}
+</script>
+<script type="module">
+import 'a';
+</script>
+<script type="module">
+import 'b';
+</script>
+```
+
+The above will then correctly execute both `a` and `b`, with only the `b` importer being polyfilled.
+
+Note that shimmed graphs will always support correct mappings - the above rules only apply to the initial polyfill engagement.
 
 #### Reading current import map state
 
@@ -337,13 +382,9 @@ const importMap = { imports: {/*...*/}, scopes: {/*...*/} };
 importShim.addImportMap(importMap);
 ```
 
+### Shim Import
 
-### Dynamic Import
-
-> Stability: Stable browser standard
-
-Dynamic `import(...)` within any modules loaded will be rewritten as `importShim(...)` automatically
-providing full support for all es-module-shims features through dynamic import.
+Dynamic `import(...)` within any modules loaded will be rewritten as `importShim(...)` automatically providing full support for all es-module-shims features through dynamic import.
 
 To load code dynamically (say from the browser console), `importShim` can be called similarly:
 
@@ -389,7 +430,9 @@ A full example of such a CSP workflow is provided below:
 <script async src="es-module-shims.js"></script>
 <script type="importmap" nonce="n0nce">
 {
-  "pkg": "/pkg.js"
+  "imports": {
+    "pkg": "/pkg.js"
+  }
 }
 </script>
 <script type="module" nonce="n0nce">
@@ -401,6 +444,28 @@ import pkg from 'pkg';
 
 To use the Web Assembly / non-CSP build of ES Module Shims, this is available as a self-contained single file at `es-module-shims/wasm` or `es-module-shims/dist/es-module-shims.wasm.js` in the package folder.
 
+#### Import Map Integrity
+
+The `"integrity"` field for import maps is supported when possible, throwing an error in es-module-shims when the integrity does not match the expected value:
+
+```html
+<script type="importmap">
+{
+  "imports": {
+    "pkg": "/pkg.js"
+  },
+  "integrity": {
+    "/pkg.js": "sha384-..."
+  }
+}
+</script>
+<script>
+import "/pkg.js";
+</script>
+```
+
+Note integrity can only be validated when in shim mode or when the polyfill is definitely engaging.
+
 ### JSON Modules
 
 > Stability: WhatWG Standard, Single Browser Implementer
@@ -431,14 +496,6 @@ import sheet from 'https://site.com/sheet.css' with { type: 'css' };
 </script>
 ```
 
-To support the polyfill or shim of this feature, the [Constructable Stylesheets polyfill](https://github.com/calebdwilliams/construct-style-sheets#readme) must be separately included in browsers not supporting [Constructable Stylesheets](https://developer.mozilla.org/en-US/docs/Web/API/CSSStyleSheet/CSSStyleSheet) eg via:
-
-```html
-<script async src="https://unpkg.com/construct-style-sheets-polyfill@3.1.0/dist/adoptedStyleSheets.js"></script>
-```
-
-For more information see the [web.dev article](https://web.dev/css-module-scripts/).
-
 In addition CSS modules need to be served with a valid CSS content type.
 
 ### Wasm Modules
@@ -474,27 +531,6 @@ const instance = await WebAssembly.instantiate(mod, { /* ...imports */ });
 
 If using CSP, make sure to add `'unsafe-wasm-eval'` to `script-src` which is needed when the shim or polyfill engages, note this policy is much much safer than eval due to the Wasm secure sandbox. See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/script-src#unsafe_webassembly_execution.
 
-### Resolve
-
-> Stability: Draft HTML PR
-
-`import.meta.resolve` provides a contextual resolver within modules. It is synchronous, changed from being formerly asynchronous due to following the [browser specification PR](https://github.com/whatwg/html/pull/5572).
-
-The second argument to `import.meta.resolve` permits a custom parent URL scope for the resolution (not currently in the browser spec), which defaults to `import.meta.url`.
-
-```js
-// resolve a relative path to a module
-var resolvedUrl = import.meta.resolve('./relative.js');
-// resolve a dependency from a module
-var resolvedUrl = import.meta.resolve('dep');
-// resolve a path
-var resolvedUrlPath = import.meta.resolve('dep/');
-// resolve with a custom parent scope
-var resolvedUrl = import.meta.resolve('dep', 'https://site.com/another/scope');
-```
-
-Node.js also implements a similar API, although it's in the process of shifting to a synchronous resolver.
-
 ### Module Workers
 
 ES Module Shims can be used in module workers in browsers that provide dynamic import in worker environments, which at the moment are Chrome(80+), Edge(80+), Firefox(~113+) and Safari(15+).
@@ -554,10 +590,8 @@ window.esmsInitOptions = {
   polyfillEnable: ['css-modules', 'json-modules'], // default empty
   // Custom CSP nonce
   nonce: 'n0nce', // default is automatic detection
-  // Don't retrigger load events on module scripts (DOMContentLoaded, domready)
+  // Don't retrigger load events on module scripts (DOMContentLoaded, domready, window 'onload')
   noLoadEventRetriggers: true, // default false
-  // Retrigger window 'load' event (will be combined into load event above on next major)
-  globalLoadEventRetrigger: 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
@@ -643,7 +677,7 @@ This option can also be set to `true` to entirely disable the native passthrough
 
 ### Enforce Integrity
 
-When enabled, `enforceIntegrity` will ensure that all modules loaded through ES Module Shims must have integrity defined either on a `<link rel="modulepreload" integrity="...">`, a `<link rel="modulepreload-shim" integrity="...">` preload tag in shim mode, or the `"integrity"` field in the import map. Modules without integrity will throw at fetch time.
+While integrity is always verified and validated when available, when enabled, `enforceIntegrity` will ensure that **all modules must have integrity defined** when loaded through ES Module Shims either on a `<link rel="modulepreload" integrity="...">`, a `<link rel="modulepreload-shim" integrity="...">` preload tag in shim mode, or the `"integrity"` field in the import map. Modules without integrity will throw at fetch time.
 
 For example in the following, only the listed `app.js`, `dep.js` and `another.js` modules will be able to execute with the provided integrity:
 
@@ -684,7 +718,7 @@ Alternatively, add a `blob:` URL policy with the CSP build to get CSP compatibil
 
 ### No Load Event Retriggers
 
-Because of the extra processing done by ES Module Shims it is possible for static module scripts to execute after the `DOMContentLoaded` or `readystatechange` events they expect, which can cause missed attachment.
+Because of the extra processing done by ES Module Shims it is possible for static module scripts to execute after the `DOMContentLoaded`, `readystatechange` or window `load` events they expect, which can cause missed attachment.
 
 In addition, script elements will also have their load events refired when polyfilled.
 
@@ -695,20 +729,13 @@ In such a case, this double event firing can be disabled with the `noLoadEventRe
 ```js
 <script type="esms-options">
 {
-  // do not re-trigger DOM events (onreadystatechange, DOMContentLoaded)
+  // do not re-trigger DOM events (onreadystatechange, DOMContentLoaded, window 'onload')
   "noLoadEventRetriggers": true
 }
 </script>
 <script async src="es-module-shims.js"></script>
 ```
 
-### Global Load Event Retrigger
-
-In ES Module Shims 1.x, load event retriggers only apply to `DOMContentLoaded` and `readystatechange` and not to the window `load` event.
-To enable the window / worker `'load'` event, set `globalLoadEventRetrigger: true`.
-
-In the next major version, this will be the default for load events, at which point only `noLoadEventRetriggers` will remain.
-
 ### Skip
 
 When loading modules that you know will only use baseline modules features, it is possible to set a rule to explicitly opt-out modules from being polyfilled to always load and be referenced through the native loader only. This enables instance sharing with the native loader and also improves performance because those modules then do not need to be processed or transformed at all, so that only local application code is handled and not library code.
@@ -865,10 +892,6 @@ If the resolve hook should apply for all modules in the entire module graph, mak
 </script>
 ```
 
-Support for an asynchronous resolve hook has been deprecated as of 1.5.0 and will be removed in the next major.
-
-Instead async work should be done with the import hook.
-
 #### Meta Hook
 
 The meta hook allows customizing the `import.meta` object in each module scope.