es-module-shims 2.1.2 → 2.3.0

package/README.md

@@ -9,10 +9,11 @@ For the remaining ~4% of users, the highly performant (see [benchmarks](#benchma
 The following modules features are polyfilled:
 
 * [Import Maps](#import-maps) polyfill.
-* [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.
-* [Import defer](#import-defer) via syntax stripping to allow usage in modern browsers with a polyfill fallback when enabled.
-* [TypeScript](#typescript-type-stripping) type stripping when enabled.
+* [JSON](#json-modules) and [CSS modules](#css-modules) polyfill with import assertions.
+* [Wasm modules](#wasm-modules) with support for Source Phase Imports, when enabled.
+* [Import defer](#import-defer) via syntax stripping to allow usage in modern browsers with a polyfill fallback, when enabled.
+* [TypeScript](#typescript-type-stripping) type stripping.
+* [Hot Reloading](#hot-reloading) with a Vite-style `import.meta.hot` API.
 
 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.
 
@@ -29,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.1.2/dist/es-module-shims.js"></script>
+<script async src="https://ga.jspm.io/npm:es-module-shims@2.3.0/dist/es-module-shims.js"></script>
 
 <!-- https://generator.jspm.io/#U2NhYGBkDM0rySzJSU1hKEpNTC5xMLTQM9Az0C1K1jMAAKFS5w0gAA -->
 <script type="importmap">
@@ -188,22 +189,20 @@ If the polyfill is analyzing or applying to a module script that doesn't need to
 
 ### Polyfill Features
 
-If using more modern features like CSS Modules or JSON Modules, these need to be manually enabled via the [`polyfillEnable` init option](#polyfill-enable-option) to raise the native baseline from just checking import maps to also checking that browsers support these features:
+If using more modern features like [Import Defer](#import-defer) or [Wasm Modules](#wasm-modules), these need to be manually enabled via the [`polyfillEnable` init option](#polyfill-enable-option) to raise the native baseline from just checking import maps to also checking that browsers support these features:
 
 ```html
 <script>
-window.esmsInitOptions = { polyfillEnable: ['css-modules', 'json-modules', 'wasm-modules', 'typescript'] }
+window.esmsInitOptions = { polyfillEnable: ['wasm-module-sources', 'import-defer'] }
 </script>
 ```
 
-The above polyfill options correspond to `polyfillEnable: 'all'`.
-
-Alternatively options can be set via the `esms-options` script type:
+Alternatively options can be set via the `esms-options` script type JSON:
 
 ```html
 <script type="esms-options">
 {
-  "polyfillEnable": "all"
+  "polyfillEnable": ["wasm-module-sources", "import-defer"]
 }
 </script>
 ```
@@ -224,7 +223,7 @@ ES Module Shims is designed for production performance. A [comprehensive benchma
 
 Benchmark summary:
 
-* [ES Module Shims Chrome Passthrough](bench/README.md#chrome-passthrough-performance) (for [94% of users](https://caniuse.com/import-maps)) results in ~5ms extra initialization time over native for ES Module Shims fetching, execution and initialization, and on a slow connection the additional non-blocking bandwidth cost of its 10KB compressed download as expected.
+* [ES Module Shims Chrome Passthrough](bench/README.md#chrome-passthrough-performance) (for [94% of users](https://caniuse.com/import-maps)) results in ~5ms extra initialization time over native for ES Module Shims fetching, execution and initialization, and on a slow connection the additional non-blocking bandwidth cost of its 13KB compressed download as expected.
 * [ES Module Shims Polyfilling](bench/README.md#native-v-polyfill-performance) (for the remaining [3% of users](https://caniuse.com/import-maps)) is on average 1.4x - 1.5x slower than native module loading, and up to 1.8x slower on slow networks (most likely due to the browser preloader), both for cached and uncached loads, and this result scales linearly up to 10MB and 20k modules loaded executing on the fastest connection in just over 2 seconds in Firefox.
 * [Very large import maps](bench/README.md#large-import-maps-performance) (100s of entries) cost only a few extra milliseconds upfront for the additional loading cost.
 
@@ -254,7 +253,7 @@ Browser compatibility **without** ES Module Shims:
 | [modulepreload](#modulepreload)               | 66+                | 115+               | 17.5+              |
 | [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:                |
+| [Multiple Import Maps](#multiple-import-maps) | 135+               | :x:                | :x:                |
 | [JSON Modules](#json-modules)                 | 123+               | :x:                | 17.2+              |
 | [CSS Modules](#css-modules)                   | 123+               | :x:                | :x:                |
 | [Wasm Modules](#wasm-modules)                 | Pending            | :x:                | :x:                |
@@ -483,11 +482,13 @@ Note integrity can only be validated when in shim mode or when the polyfill is d
 
 ### JSON Modules
 
-> Stability: WhatWG Standard, Single Browser Implementer
+> Stability: WhatWG Standard, Stable, Multiple Browser Implementers
 
-In shim mode, JSON modules are always supported. In polyfill mode, JSON modules require the `polyfillEnable: ['json-modules']` [init option](#polyfill-enable-option).
+JSON modules are now enabled by default in ES Module Shims with 85% browser support for native where the polyfill won't engage at all.
 
-JSON Modules are currently supported in Chrome when using them via an import assertion:
+In shim mode, JSON modules are always supported.
+
+JSON Modules are supported in Chrome and Safari when using them via an import assertion:
 
 ```html
 <script type="module">
@@ -501,9 +502,9 @@ In addition JSON modules need to be served with a valid JSON content type.
 
 > Stability: WhatWG Standard, Single Browser Implementer
 
-In shim mode, CSS modules are always supported. In polyfill mode, CSS modules require the `polyfillEnable: ['css-modules']` [init option](#polyfill-enable-option).
+CSS imports are fully supported in both polyfill and shim mode with native passthrough applying in Chrome.
 
-CSS Modules are currently supported in Chrome when using them via an import assertion:
+Use them by adding the `type: 'css'` import assertion when importing a CSS file:
 
 ```html
 <script type="module">
@@ -511,7 +512,7 @@ import sheet from 'https://site.com/sheet.css' with { type: 'css' };
 </script>
 ```
 
-In addition CSS modules need to be served with a valid CSS content type.
+In addition CSS files need to be served with a valid CSS content type.
 
 ### Wasm Modules
 
@@ -519,13 +520,11 @@ In addition CSS modules 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-modules']` [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-modules-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.
 
-By default Wasm support will look for both source phase syntax as well as instance Wasm imports, resulting in full analysis of the module graph when either is unsupported.
-
-If only using Wasm modules in the source phase set `polyfillEnable: ['wasm-module-sources']` [init option](#polyfill-enable-option) to ensure full native passthrough without the extra code analysis when Chrome ships the source phase.
+If only using Wasm modules in both the instance and source phase set `polyfillEnable: ['wasm-modules']` [init option](#polyfill-enable-option) to enable both modes.
 
 When enabling the source phase feature either way, `WebAssembly.Module` is also polyfilled to extend from `AbstractModuleSource` per the source phase proposal.
 
@@ -546,7 +545,7 @@ const instance = await WebAssembly.instantiate(mod, { /* ...imports */ });
 </script>
 ```
 
-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.
+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 safer than normal 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.
 
 ### Import Defer
 
@@ -558,24 +557,100 @@ The polyfill is simply just a defer syntax stripping, allowing environments that
 
 ### TypeScript Type Stripping
 
-Node.js recently [added support for automatically executing TypeScript with type stripping](https://nodejs.org/api/typescript.html). We support the exact same approach in ES Module Shims.
+TypeScript type stripping is supported like [in Node.js](https://nodejs.org/api/typescript.html).
 
-Once enabled, the separate `es-module-shims-typescript.js` extension must be available as a sibling asset to `es-module-shims.js` and will then be loaded on demand when a `.ts`, `.mts` file is loaded or when a file is served with the `application/typescript` MIME type.
+To trigger TypeScript type stripping, make sure to either use shim mode, or to add the non-standard `lang="ts"` option to the top-level evaluator. This ensures that the polyfill processing will engage on this graph, while usually module graphs are not processed at all in browsers with full native support.
 
-Example:
+Modules will then be interpreted as TypeScript when one of the following applied:
+
+* It is served with the `application/typescript` MIME type.
+* It ends in `.ts` or `.mts` and is not served with a valid module script MIME type.
+* Or, if it is an inline `lang="ts"` module script.
+
+For example the following are all valid TypeScript usage patterns:
+
+Shim mode - no `lang=ts` is necessary:
 
 ```html
-<script async src="https://ga.jspm.io/npm:es-module-shims@2.1.2/dist/es-module-shims.js"></script>
-<script type="esms-options">
+<script type="module-shim" src="app.ts">
+```
+
+Polyfill mode via `lang=ts`:
+
+```html
+<script type="module" lang="ts" src="app.ts"></script>
+```
+
+Inline TypeScript with `lang=ts`:
+
+```html
+<script type="module" lang="ts">
+import './dep.ts';
+const ts: boolean = true;
+console.log('TypeScript!');
+</script>
+```
+
+Indirect static import to a TypeScript module via `lang="ts"`:
+
+```html
+<script type="importmap">
 {
-  "polyfillEnable": "all"
+  "imports": {
+    "app": "/app.mts"
+  }
 }
 </script>
-<script type="module" src="test.ts"></script>
+<script type="module" lang="ts">
+import 'app';
+</script>
 ```
 
+Loading TypeScript dynamically:
+
+```html
+<script type="module" lang="ts">
+importShim('./app.ts', { lang: 'ts' });
+</script>
+```
+
+When processing a TypeScript module, the `es-module-shims-typescript.js` extension must be available as a sibling asset to `es-module-shims.js`. It will then be loaded on-demand to provide the type stripping processing.
+
 Note that runtime TypeScript features such as enums are not supported, and type only imports should be used where possible, per the Node.js guidance for TypeScript.
 
+### Hot Reloading
+
+Hot reloading is supported in both shim and polyfill modes, when explicitly enabled. To enable hot-reloading, enable the `hotReload` init option:
+
+test.html
+```html
+<script type="esms-options">
+{
+  "hotReload": true,
+  "hotReloadInterval": 100
+}
+</script>
+<script async src="es-module-shims.js"></script>
+<script type="module" src="/app.js"></script>
+```
+
+In polyfill mode, all modules will be initialized twice when hot reloading to reinitiate with `import.meta.hot`. To avoid this, shim mode is recommended for hot reloading workflows whenever possible.
+
+The `hotReloadInterval` option can also be configured which is the interval at which hot reload events are batched together as a single reload operation, with the default of `100`.
+
+When enabled, [native passthrough](#native-passthrough) will be automatically disabled, and all modules will be provided with the `import.meta.hot` API fully supporting [Vite's `import.meta.hot`](https://vite.dev/guide/api-hmr), supporting the following methods except for the event handlers:
+
+* `hot.accept(cb)`: Accept a hot update.
+* `hot.accept(dep, cb)`: Accept a hot update of a dependency specifier string.
+* `hot.accept(deps, cb)`: Accept a hot update of a list of dependency specifier strings.
+* `hot.dispose(cb)`: Provide a dispose function for when this module is expected to be accepted by others.
+* `hot.data`: Shared data object between hot reload instances.
+* `hot.invalidate()`: Fully invalidate the current module, without accepting. Can be called within accept itself.
+
+To trigger a hot reload, call the `importShim.hotReload(url)` API with the URL of the module that has changed. All of CSS, JSON, Wasm and TypeScript imports are supported in hot reloading.
+
+This hot reload API can then be attached to a Web Socket, Server Side Events emitter or any other event source to provide a native hot reloading development environment.
+
 ### 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+).
@@ -615,6 +690,7 @@ Provide a `esmsInitOptions` on the global scope before `es-module-shims` is load
 * [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)
@@ -632,7 +708,7 @@ window.esmsInitOptions = {
   // Enable Shim Mode
   shimMode: true, // default false
   // Enable newer modules features
-  polyfillEnable: ['css-modules', 'json-modules'], // default empty
+  polyfillEnable: ['wasm-module-sources'], // default empty
   // Custom CSP nonce
   nonce: 'n0nce', // default is automatic detection
   // Don't retrigger load events on module scripts (DOMContentLoaded, domready, window 'onload')
@@ -646,6 +722,9 @@ window.esmsInitOptions = {
   enforceIntegrity: true, // default false
   // Permit overrides to import maps
   mapOverrides: true, // default false
+  // Whether es-module-shims will defer to the native module loader whenever it can
+  // Automatically disabled in hot reloading workflows
+  nativePassthrough: false, // default true
 
   // -- Hooks --
   // Module load error
@@ -671,7 +750,7 @@ window.esmsInitOptions = {
 <script type="esms-options">
 {
   "shimMode": true,
-  "polyfillEnable": ["css-modules", "json-modules"],
+  "polyfillEnable": ["wasm-module-sources"],
   "nonce": "n0nce",
   "onpolyfill": "polyfill"
 }
@@ -700,14 +779,14 @@ DOM `load` events are fired for all `"module-shim"` scripts both for success and
 
 The `polyfillEnable` option allows enabling polyfill features which are newer and would otherwise result in unnecessary polyfilling in modern browsers that haven't yet updated.
 
-This options supports `"css-modules"`, `"json-modules"`, `"wasm-modules"`, `"wasm-module-sources"`, `"wasm-module-instances"` and `"import-defer"`.
+This options supports `"wasm-modules"`, `"wasm-module-sources"`, `"wasm-module-instances"` and `"import-defer"`.
 
-In adddition, the `"all"` option will enable all features and the `"latest"` option will implement the latest supported browser features (currently `"css-modules"` and `"json-modules"`).
+In adddition, the `"all"` option will enable all features.
 
 ```html
 <script type="esms-options">
 {
-  "polyfillEnable": ["latest", "typescript"]
+  "polyfillEnable": ["all"]
 }
 </script>
 ```
@@ -863,6 +942,17 @@ document.body.appendChild(Object.assign(document.createElement('script'), {
 
 This can be useful for HMR workflows.
 
+### Native Passthrough
+
+By default, ES Module Shims will always use the native passthrough of calling the native `import()` mechanism to load module graphs, when it has analyzed that that module graph is fully supported in the current environment. This way, the native module registry is fully shared between polyfilled and non-polyfilled graphs,
+and we lean into the native support as much as popssible.
+
+In Shim mode, ES Module Shims never uses native pass through regardless of this option - it only applies to polyfill mode.
+
+This option is enabled by default, so by turning it off it is possible to ensure that ES Module Shims is rewriting and processing all sources itself.
+
+Native passthrough is automatically disabled when using [hot reloading](#hot-reloading).
+
 ### Hooks
 
 #### Polyfill hook