es-module-shims 2.3.0 → 2.4.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.3.0/dist/es-module-shims.js"></script>
+<script async src="https://ga.jspm.io/npm:es-module-shims@2.4.0/dist/es-module-shims.js"></script>
 
 <!-- https://generator.jspm.io/#U2NhYGBkDM0rySzJSU1hKEpNTC5xMLTQM9Az0C1K1jMAAKFS5w0gAA -->
 <script type="importmap">
@@ -701,6 +701,7 @@ Provide a `esmsInitOptions` on the global scope before `es-module-shims` is load
 * [revokeBlobURLs](#revoke-blob-urls)
 * [shimMode](#shim-mode-option)
 * [skip](#skip)
+* [version](#version)
 
 ```html
 <script>
@@ -738,7 +739,9 @@ window.esmsInitOptions = {
   // Hook import.meta construction
   meta: (meta, url) => void // default is noop
   // Hook top-level imports
-  onimport: (url, options, parentUrl) => void // default is noop
+  onimport: (url, options, parentUrl, source) => void // default is noop
+  // Ensure only the exact provided version of es-module-shims registered
+  version: '2.4.0' // default is empty
 }
 </script>
 <script async src="es-module-shims.js"></script>
@@ -888,6 +891,14 @@ When passing an array, relative URLs or paths ending in `/` can be provided:
 <script async src="es-module-shims.js"></script>
 ```
 
+### Version
+
+When there is a risk of multiple versions of ES Module Shims on the same page, deconflicting is managed by logic that will opt-out of initializing ES Module Shims if it has already been initialized. In addition, ES Module Shims itself is frozen and locked from further mutations.
+
+To better support cooporative multi-version cases, as of version 2.4.0, we support a `version` option, which when set will skip initialization if the current version of ES Module Shims does not match this exact expected version.
+
+This way, any other old versions after version 2.4.0 running on the page can effectively be turned off, ensuring only the defined version of the polyfill initiates the polyfill.
+
 ### Revoke Blob URLs
 
 When polyfilling the missing features `es-module-shims` would create in-memory blobs using `URL.createObjectURL()` for each processed module.
@@ -998,8 +1009,11 @@ The import hook is supported for both shim and polyfill modes and provides an as
 ```js
 <script>
   window.esmsInitOptions = {
-    onimport: function (url, options, parentUrl) {
-      console.log(`Top-level import for ${url}`);
+    onimport: function (url, options, parentUrl, source) {
+      if (source !== undefined)
+        console.log(`Top-level inline script with source: ${source}`);
+      else
+        console.log(`Top-level URL import (static or dynamic) for ${url}`);
     }
   }
 </script>