es-module-shims 2.1.1 → 2.2.0

package/README.md

@@ -12,7 +12,7 @@ The following modules features are polyfilled:
 * [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.
+* [TypeScript](#typescript-type-stripping) type stripping.
 
 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 +29,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.1/dist/es-module-shims.js"></script>
+<script async src="https://ga.jspm.io/npm:es-module-shims@2.2.0/dist/es-module-shims.js"></script>
 
 <!-- https://generator.jspm.io/#U2NhYGBkDM0rySzJSU1hKEpNTC5xMLTQM9Az0C1K1jMAAKFS5w0gAA -->
 <script type="importmap">
@@ -188,22 +188,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>
 ```
@@ -254,7 +252,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 +481,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 +501,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 +511,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 +519,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 +544,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,22 +556,65 @@ 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.1/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.
 
 ### Module Workers
@@ -632,7 +673,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')
@@ -671,7 +712,7 @@ window.esmsInitOptions = {
 <script type="esms-options">
 {
   "shimMode": true,
-  "polyfillEnable": ["css-modules", "json-modules"],
+  "polyfillEnable": ["wasm-module-sources"],
   "nonce": "n0nce",
   "onpolyfill": "polyfill"
 }
@@ -700,14 +741,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>
 ```