es-module-shims 0.13.0 → 0.15.1

package/CHANGELOG.md

@@ -0,0 +1,208 @@
+ES Module Shims 0.15.1 (2021/09/18)
+* Significant performance improvements to CSP build via asm.js (https://github.com/guybedford/es-module-shims/pull/190) and direct dynamic import (https://github.com/guybedford/es-module-shims/pull/191)
+
+ES Module Shims 0.15.0 (2021/09/17)
+* Various perf and behaviour polishing (https://github.com/guybedford/es-module-shims/pull/188)
+* Revert DOM mutator nested queryString checks (https://github.com/guybedford/es-module-shims/pull/189)
+* Fetch pooling (https://github.com/guybedford/es-module-shims/pull/184)
+
+ES Module Shims 0.14.0 (2021/09/13)
+* CSP compatible ES Module Shims build (https://github.com/guybedford/es-module-shims/pull/183)
+
+ES Module Shims 0.13.1 (2021/09/10)
+* Fix to ensure global script errors always propagate to the console (https://github.com/guybedford/es-module-shims/pull/182)
+
+ES Module Shims 0.13.0 (2021/09/07)
+* Breaking Change: Polyfill mode restricts behaviours to native baseline support (https://github.com/guybedford/es-module-shims/pull/173)
+* Breaking Change: JSON and CSS modules require explicit enabling (https://github.com/guybedford/es-module-shims/pull/172)
+* Breaking Change: Adds the "exports" field to encapsulate the package entry point (https://github.com/guybedford/es-module-shims/pull/177)
+* Feature: Support script DOM "load" events (https://github.com/guybedford/es-module-shims/pull/170)
+* Improve browser compatibility for Weixin browser (https://github.com/guybedford/es-module-shims/pull/165, @xxgjzftd)
+* Fix dynamic import polyfill recursion in Firefox 60 (https://github.com/guybedford/es-module-shims/pull/176)
+* Change compat to Edge 17+ (https://github.com/guybedford/es-module-shims/pull/178)
+
+ES Module Shims 0.12.8 (2021/08/24)
+* Fix preload deduping for re-injection of preloads (https://github.com/guybedford/es-module-shims/pull/164)
+
+ES Module Shims 0.12.7 (2021/08/23)
+* Support re-triggering DOM load events for static script executions (https://github.com/guybedford/es-module-shims/pull/162)
+
+ES Module Shims 0.12.6 (2021/08/20)
+* Fix regression where inline scripts in polyfill mode on supported browsers would throw an unnecessary error (https://github.com/guybedford/es-module-shims/pull/159)
+
+ES Module Shims 0.12.5 (2021/08/19)
+* Support CSS module scripts (https://github.com/guybedford/es-module-shims/pull/154)
+
+ES Module Shims 0.12.4 (2021/08/18)
+* Fix eager modulepreload preloading bug from 0.12.3 (https://github.com/guybedford/es-module-shims/pull/152)
+
+ES Module Shims 0.12.3 (2021/08/17)
+* Support resolve hook (https://github.com/guybedford/es-module-shims/pull/146, @zhoukekestar)
+* Internal preload cache to avoid double network requests (https://github.com/guybedford/es-module-shims/pull/149)
+
+ES Module Shims 0.12.2 (2021/07/23)
+* Support processing nested tags in mutaton observer (https://github.com/guybedford/es-module-shims/pull/144, @dbackeus)
+
+ES Module SHims 0.12.1 (2021/06/29)
+* Fixup dynamic injection of modulepreload (f231485)
+
+ES Module Shims 0.12.0 (2021/06/29)
+* Support modulepreload polyfilling (https://github.com/guybedford/es-module-shims/pull/141)
+
+ES Module Shims 0.11.1 (2021/06/17)
+* Fixup replacement offset regression (https://github.com/guybedford/es-module-shims/pull/140)
+
+ES Module Shims 0.11.0 (2021/06/15)
+* Support for JSON modules and import assertions (https://github.com/guybedford/es-module-shims/commit/2d7eb193986d51733fa6394ad699ee70e5060a13)
+* Fix dynamic import bug in Firefox <67 (https://github.com/guybedford/es-module-shims/commit/3f3d71fc3dd76ba1a965ae00285823672f34c138)
+
+ES Module Shims 0.10.7 (2021/06/10)
+* Fix import map feature detection in Safari (https://github.com/guybedford/es-module-shims/pull/131, @heypiotr)
+
+ES Module Shims 0.10.6 (2021/06/05)
+* Support for revoking blob URLs (https://github.com/guybedford/es-module-shims/pull/124, @vovacodes)
+* Include typescript types in published package (https://github.com/guybedford/es-module-shims/pull/125, @vovacodes)
+* Fix support for dynamic import in inline scripts (https://github.com/guybedford/es-module-shims/pull/128)
+* Polyfill bug fixes (https://github.com/guybedford/es-module-shims/pull/130)
+
+ES Module Shims 0.10.5 (2021/05/14)
+* Fix immediately added dynamic import maps (https://github.com/guybedford/es-module-shims/pull/123, @vovacodes)
+* Handle relative sourceURL and sourceMappingURL (https://github.com/guybedford/es-module-shims/pull/122, @vovacodes)
+
+ES Module Shims 0.10.4 (2021/04/11)
+* Fix cycle handling regression (https://github.com/guybedford/es-module-shims/issues/119)
+
+ES Module Shims 0.10.3 (2021/03/22)
+* Fix shim mode execution bug (https://github.com/guybedford/es-module-shims/issues/117)
+
+ES Module Shims 0.10.2 (2021/03/18)
+* Fix inline module-shim execution in non-polyfill mode (https://github.com/guybedford/es-module-shims/issues/115)
+* Bug fix for scope key resolution to be relative to baseURL not scopeURL (https://github.com/guybedford/es-module-shims/pull/116)
+
+ES Module Shims 0.10.1 (2021/02/27)
+* Various bug fixes for polyfill mode
+
+ES Module Shims 0.10.0 (2021/02/27)
+* Feature: Comprehensive polyfill mode (https://github.com/guybedford/es-module-shims/pull/113)
+
+ES Module Shims 0.9.0 (2021/01/23)
+* Breaking: New initialOptions global API instead of hooking importShims properties (https://github.com/guybedford/es-module-shims/pull/109, @lewisl9029)
+* Fix inline script double execution issue (https://github.com/guybedford/es-module-shims/pull/111)
+
+ES Module Shims 0.8.0 (2020/12/23)
+* Fix URL to URL import map mappings (https://github.com/guybedford/es-module-shims/pull/107, @vovacodes)
+* Include TypeScript types (https://github.com/guybedford/es-module-shims/pull/104, @ifiokjr)
+* Fix processScripts to permit dynamic additions (https://github.com/guybedford/es-module-shims/pull/102, @ifiokjr)
+* Remove unnecessary sourceMappingURL rebase (https://github.com/guybedford/es-module-shims/pull/98)
+
+ES Module Shims 0.7.1 (2020/10/30)
+* Update to es-module-shims@0.3.26
+* Fixup onerror hook to throw by default (#96)
+
+ES Module Shims 0.7.0 (2020/10/06)
+* Process scripts in order, global importShims.onerror hook (a3e3f639e835d6)
+
+ES Module Shims 0.6.0 (2020/09/17)
+* Resolve scopes to the baseURL not the scopeURL (d2893159e4b66c43)
+
+ES Module Shims 0.5.2 (2020/08/07)
+* import.meta.resolve (https://github.com/guybedford/es-module-shims/pull/89)
+
+ES Module Shims 0.5.0 (2020/07/24)
+* Dynamic import map support (https://github.com/guybedford/es-module-shims/pull/85)
+* Remove support for array fallbacks, builtin modules, workers, CSS modules, JSON modules, Wasm modules (https://github.com/guybedford/es-module-shims/pull/84)
+* Depcache implementation (https://github.com/guybedford/es-module-shims/pull/78)
+
+ES Module Shims 0.4.6 (2019/10/21)
+* Implement fetch hook (https://github.com/guybedford/es-module-shims/pull/73)
+
+ES Module Shims 0.4.5 (2019/09/18)
+* Fixup incorrect pageBaseUrl reference (7391880e836712)
+* Fixup hasDocument check for Firefox (https://github.com/guybedford/es-module-shims/issues/62)
+
+ES Module Shims 0.4.4 (2019/09/09)
+* Fix to ensure build against latest es-module-lexer
+
+ES Module Shims 0.4.3 (2019/09/08)
+* Remove unnecessary Object.assign polyfill (https://github.com/guybedford/es-module-shims/commit/6bc90c059377e254e71b6695368215ce6ebff7d7)
+* Rework standard module detection (https://github.com/guybedford/es-module-shims/pull/62)
+
+ES Module Shims 0.4.2 (2019/08/31)
+* Fixes a critical Edge bug with parallel execution using a graph inlining to ensure execution order (https://github.com/guybedford/es-module-shims/pull/57, https://github.com/microsoft/ChakraCore/issues/6261)
+* `x-javascript` MIME type support (https://github.com/guybedford/es-module-shims/pull/56)
+
+ES Module Shims 0.4.1 (2019/08/30)
+* Support text/javascript MIME type (https://github.com/guybedford/es-module-shims/pull/53)
+
+ES Module Shims 0.4.0 (2019/08/29)
+* Support for cascading import maps (https://github.com/guybedford/es-module-shims/pull/49)
+* Use strict Content-Type checks for modules (https://github.com/guybedford/es-module-shims/pull/47)
+
+ES Module Shims 0.3.2 (2019/08/29)
+* Update to ES module lexer 0.3.12
+
+ES Module Shims 0.3.1 (2019/08/28)
+* Updates to ES module lexer 0.3.11 including better errors and invalid syntax handling (https://github.com/guybedford/es-module-shims/pull/46)
+
+ES Module Shims 0.3.0 (2019/08/25)
+* Implement CSS modules (https://github.com/guybedford/es-module-shims/pull/41)
+* Upgrade to Wasm-based ES module lexer for performance (https://github.com/guybedford/es-module-shims/38)
+* Fix sourceMappingURL support in Firefox (https://github.com/guybedford/es-module-shims/pull/37, @MicahZoltu)
+* Separate ES module lexer into its own project (https://github.com/guybedford/es-module-shims/pull/36, @LarsDenBakker)
+
+ES Module Shims 0.2.15 (2019/07/28)
+* Early import map resolution (https://github.com/guybedford/es-module-shims/pull/32)
+
+ES Module Shims 0.2.14 (2019/07/17)
+* Support import map fallbacks by ignoring std modules (https://github.com/guybedford/es-module-shims/pull/28, @thepassle)
+* Support path separators in module URLs containing hashes and query strings (https://github.com/guybedford/es-module-shims/pull/30, @LarsDenBakker)
+
+ES Module Shims 0.2.13 (2019/06/29)
+* Support JSON module imports (https://github.com/guybedford/es-module-shims/pull/27)
+
+ES Module Shims 0.2.12 (2019/06/29)
+* Support `<base>` tag for baseURL (https://github.com/guybedford/es-module-shims/pull/26, @LarsDenBakker)
+
+ES Module Shims 0.2.11 (2019/06/26)
+* Fix use of object spread in Edge (https://github.com/guybedford/es-module-shims/pull/25, @LarsDenBakker)
+
+ES Module Shims 0.2.10 (2019/06/25)
+* Fix Worker constructor options bug (https://github.com/guybedford/es-module-shims/pull/23)
+
+ES Module Shims 0.2.9 (2019/06/24)
+* Fixup WorkerShim worker output
+
+ES Module Shims 0.2.8 (2019/06/24)
+* Support WorkerShim module workers (https://github.com/guybedford/es-module-shims/pull/17 by @costingeana)
+
+ES Module Shims 0.2.7 (2019/05/04)
+* Fix imports minification case (https://github.com/guybedford/es-module-shims/issues/11)
+
+ES Module Shims 0.2.6 (2019/04/30)
+* Fixup dynamic import regression
+
+ES Module Shims 0.2.5 (2019/04/30)
+* Fix various lexing edge cases around dynamic import
+
+ES Module Shims 0.2.4
+* Add "type": "module" to package.json
+
+ES Module Shims 0.2.3 (2019/03/29)
+* Fixup minification build
+* Further lexer adjustments (2ca2589b1)
+
+ES Module Shims 0.2.2 (2019/03/28)
+* Fixup export syntax parser bug (51396799)
+
+ES Module Shims 0.2.1 (2019/02/25)
+* Fix support for URL imports
+
+ES Module Shims 0.2.0 (2019/01/12)
+* Update to latest import maps spec (e6e64748)
+
+ES Module Shims 0.1.15 (2018/10/09)
+* Use responseURL for resolution for spec compliant redirects (689aed0)
+
+ES Module Shims 0.1.14 (2018/10/06)
+* Fix Safari WASM support (7cf31ac4)
+* add sourceURL to cycle shells for debugging (80438731)

package/README.md

@@ -6,7 +6,7 @@
 
 But modules features like Import Maps will take a while to be supported in browsers.
 
-_It turns out that we can actually polyfill new modules features on top of these baseline implementations in a performant 7KB shim._
+_It turns out that we can actually polyfill new modules features on top of these baseline implementations in a performant 9.5KB shim._
 
 This includes support for:
 
@@ -34,10 +34,10 @@ For example, from CDN:
 
 ```html
 <!-- UNPKG -->
-<script async src="https://unpkg.com/es-module-shims@0.13.0/dist/es-module-shims.js"></script>
+<script async src="https://unpkg.com/es-module-shims@0.15.1/dist/es-module-shims.js"></script>
 
 <!-- JSPM.IO -->
-<script async src="https://ga.jspm.io/npm:es-module-shims@0.13.0/dist/es-module-shims.js"></script>
+<script async src="https://ga.jspm.io/npm:es-module-shims@0.15.1/dist/es-module-shims.js"></script>
 ```
 
 Then there are two ways to use ES Module Shims: Polyfill Mode and [Shim Mode](#shim-mode).
@@ -177,22 +177,20 @@ In shim mode, external import maps are fully supported.
 
 #### Dynamic Import Maps
 
-Support for dynamically injecting import maps with JavaScript via
+Support for dynamically injecting import maps with JavaScript via eg:
 
 ```js
 document.body.appendChild(Object.assign(document.createElement('script'), {
   type: 'importmap',
-  innerHTML: JSON.stringify({ imports: { x: './y.js' } })
+  innerHTML: JSON.stringify({ imports: { x: './y.js' } }),
 }));
 ```
 
-is supported in Chromium, provided it is injected before any module loads and there is no other import map.
+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).
 
-Both modes in ES Module Shims thus support dynamic injection using DOM Mutation Observers.
+Both modes in ES Module Shims support dynamic injection using DOM Mutation Observers.
 
-In polyfill mode, a best effort is made to support the same timing constraints.
-
-In shim mode, full support for dynamic injection of `"importmap-shim"` is provided.
+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"`.
 
 ### Dynamic Import
 
@@ -342,7 +340,9 @@ Adding the `"noshim"` attribute to the script tag will also ensure that ES Modul
 
 Native module scripts only fire `'load'` events but not `'error'` events per the specification.
 
-In polyfill mode, DOM `'load'` events are always retriggered, such that the second load event can be reliably considered the polyfill completion, fired for both success and failure completions like the native loader, and always twice (once from the native loader, secondly by the polyfill), whether or not the polyfill actually resulted in execution.
+In polyfill mode, DOM `'load'` events are always retriggered, such that the second load event can be reliably considered the polyfill completion, fired for both success and failure completions like the native loader (except in Safari which uniquely fires the module script error event), and always twice (once from the native loader, secondly by the polyfill), whether or not the polyfill actually resulted in execution.
+
+This behaviour can be disabled via the [`noLoadEventRetriggers` option](#no-load-event-retriggers).
 
 To dynamically load a module and get a callback once its execution has been triggered or failed, the following code snippet can therefore be used:
 
@@ -350,13 +350,19 @@ To dynamically load a module and get a callback once its execution has been trig
 function loadModuleScript (src) {
   return new Promise(resolve => {
     let first = true;
+    function callback () {
+      if (first) first = false;
+      else resolve();
+    }
     document.head.appendChild(Object.assign(document.createElement('script'), {
       type: 'module',
       src,
-      onload () {
-        if (first) first = false;
-        else resolve();
-      }
+      onload: callback,
+
+      // Safari Fix:
+      // Safari is the only browser that triggers "error" events instead of "load" events
+      // for both error and success like Firefox and Chrome
+      onerror: callback
     }));
   });
 }
@@ -364,15 +370,43 @@ function loadModuleScript (src) {
 
 Where native module script errors are propagated via `window.onerror`, [`esmsInitOptions.onerror`](#error-hook) can be used to catch polyfill errors.
 
+## CSP Build
+
+ES Module Shims uses a Web Assembly lexer to execute blob URLs. Web Assembly currently always requires the `unsafe-eval` CSP policy to be set which can weaken the security requirements of an application.
+
+For better CSP compatibility an alternative build that uses a JS-based lexer is provided, which offers [comporable performance](https://github.com/guybedford/es-module-lexer#js-build) although with a slower cold start due to leaning more heavily on the JS compiler to kick in for the lexer as opposed to the AOT compilation benefits of using Wasm.
+
+This build is exported as `es-module-shims/csp` located at the `dist/es-module-shims.csp.js` file path.
+
+CSP compatibility is enabled by adding the `'nonce-...'` CSP nonce rule.
+
+The nonce will then be read from the preceding module scripts in the page, or alternatively via the [`nonce` init option](#nonce).
+
+A full example of such a CSP workflow is provided below:
+
+```html
+<meta http-equiv="Content-Security-Policy" content="script-src 'self' 'nonce-n0nce'" />
+<script async src="es-module-shims.csp.js"></script>
+<script type="importmap" nonce="n0nce">
+{
+  "pkg": "/pkg.js"
+}
+</script>
+<script type="module" nonce="n0nce">
+import pkg from 'pkg';
+</script>
+```
+
 ## Init Options
 
 Provide a `esmsInitOptions` on the global scope before `es-module-shims` is loaded to configure various aspects of the module loading process:
-
+o
 ```html
 <script>
 window.esmsInitOptions = {
   shimMode: true, // default false
   polyfillEnable: ['css-modules', 'json-modules'], // default empty
+  nonce: 'n0nce', // default null
   noLoadEventRetriggers: true, // default false
   skip: /^https:\/\/cdn\.com/, // defaults to `/^https?:\/\/(cdn\.skypack\.dev|jspm\.dev)\//`
   onerror: (e) => { /*...*/ }, // default noop
@@ -384,17 +418,31 @@ window.esmsInitOptions = {
 <script async src="es-module-shims.js"></script>
 ```
 
+If only setting JSON-compatible options, the `<script type="esms-options">` can be used instead:
+
+```html
+<script type="esms-options">
+{
+  "shimMode": true,
+  "polyfillEnable": ["css-modules", "json-modules"],
+  "nonce": "n0nce"
+}
+</script>
+```
+
+This can be convenient when using the [CSP build](#csp-build).
+
 See below for a detailed description of each of these options.
 
 ### Shim Mode Option
 
 [Shim Mode](#shim-mode) can be overridden using the `shimMode` option:
 
-```js
-<script>
-  window.esmsInitOptions = {
-    shimMode: true
-  }
+```html
+<script type="esms-options">
+{
+  "shimMode": true
+}
 </script>
 ```
 
@@ -408,11 +456,25 @@ The `polyfillEnable` option allows enabling polyfill features which are newer an
 
 Currently this option supports just `"css-modules"` and `"json-modules"`.
 
+```html
+<script type="esms-options">
+{
+  "polyfillEnable": ["css-modules", "json-modules"]
+}
+</script>
+```
+
+### Nonce
+
+The `nonce` option allows setting a CSP nonce to be used with all script injections for full CSP compatibility supported by the [CSP build](#csp-build) of ES Module Shims.
+
+Alternatively, add a `blob:` URL policy with the CSP build to get CSP compatibility.
+
 ```js
-<script>
-  window.esmsInitOptions = {
-    polyfillEnable: ['css-modules', 'json-modules']
-  };
+<script type="esms-options">
+{
+  "nonce": "n0nce"
+}
 </script>
 ```
 
@@ -420,18 +482,16 @@ Currently this option supports just `"css-modules"` and `"json-modules"`.
 
 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.
 
-In order to ensure libraries that rely on these event still behave correctly, ES Module Shims will double trigger these events when there are script executions that would normally have executed before the document ready state transition to completion.
-
-These events are carefully only triggered when there definitely were modules that would have missed attachment but there is still the risk that this can result in double attachments when mixing modules and scripts where the scripts might get two events firing.
+In order to ensure libraries that rely on these event still behave correctly, ES Module Shims will always double trigger these events that would normally have executed before the document ready state transition to completion.
 
 In such a case, this double event firing can be disabled with the `noLoadEventRetriggers` option:
 
 ```js
-<script>
-  window.esmsInitOptions = {
-    // do not re-trigger the onreadystatechange and DOMContentLoaded DOM events
-    noLoadEventRetriggers: true
-  }
+<script type="esms-options">
+{
+  // do not re-trigger DOM events (onreadystatechange, DOMContentLoaded and load events on scripts)
+  "noLoadEventRetriggers": true
+}
 </script>
 <script async src="es-module-shims.js"></script>
 ```
@@ -443,10 +503,10 @@ When loading modules that you know will only use baseline modules features, it i
 This can be configured by providing a URL regular expression for the `skip` option:
 
 ```js
-<script>
-  window.esmsInitOptions = {
-    skip: /^https:\/\/cdn\.com/ // defaults to `/^https?:\/\/(cdn\.skypack\.dev|jspm\.dev)\//`
-  }
+<script type="esms-options">
+{
+  skip: "/^https:\/\/cdn\.com/" // defaults to `/^https?:\/\/(cdn\.skypack\.dev|jspm\.dev)\//`
+}
 </script>
 <script async src="es-module-shims.js"></script>
 ```
@@ -518,6 +578,7 @@ Streaming support is also provided, for example here is a hook with streaming su
 
 ```js
 window.esmsInitOptions = {
+  shimMode: true,
   fetch: async function (url) {
     const response = await fetch(url);
     if (!response.ok)
@@ -557,10 +618,10 @@ you might want to reduce the growth of memory usage by revoking those blob URLs
 You can do that by enabling the `revokeBlobURLs` init option:
 
 ```js
-<script>
-  window.esmsInitOptions = {
-    revokeBlobURLs: true
-  }
+<script type="esms-options">
+{
+  "revokeBlobURLs": true
+}
 </script>
 <script type="module" src="es-module-shims.js"></script>
 ```
@@ -573,7 +634,6 @@ cause janks, we recommend enabling this option only if you have done the measure
 ### Import Rewriting
 
 * Sources are fetched, import specifiers are rewritten to reference exact URLs, and then executed as BlobURLs through the whole module graph.
-* CSP is not supported as we're using fetch and modular evaluation.
 * The [lexer](https://github.com/guybedford/es-module-lexer) handles the full language grammar including nested template strings, comments, regexes and division operator ambiguity based on backtracking.
 * When executing a circular reference A -> B -> A, a shell module technique is used to "shim" the circular reference into an acyclic graph. As a result, live bindings for the circular parent A are not supported, and instead the bindings are captured immediately after the execution of A.