es-module-shims 2.5.1 → 2.6.1

package/index.d.ts

@@ -1,6 +1,10 @@
 interface ESMSInitOptions {
   /**
-   * Enable Shim Mode
+   * Enable Shim Mode, where only
+   *   <script type="module-shim"></script>
+   * and
+   *   <script type="importmap-shim"></script>
+   * are supported and the native loader is not used directly (no {@link nativePassthrough}).
    */
   shimMode?: boolean;
 
@@ -16,21 +20,59 @@ interface ESMSInitOptions {
 
   /**
    * Enable polyfill features.
-   * 
+   *
    * Currently supports:
    * - 'wasm-modules': Both 'wasm-module-sources' and 'wasm-module-instances'
    * - 'wasm-module-sources': Support for Wasm source phase imports (import source mod from './mod.wasm')
    * - 'wasm-module-instances': Support for Wasm instance phase imports (import * as mod from './mod.wasm')
    * - 'import-defer': Support for import defer syntax (import defer * as ns from './foo.js')
    */
-  polyfillEnable?: Array<'wasm-modules' | 'wasm-module-instances' | 'wasm-module-sources' | 'import-defer'>;
+  polyfillEnable?: Array<'wasm-modules' | 'wasm-module-instances' | 'wasm-module-sources' | 'import-defer' | 'all'>;
 
   /**
-   * Version
-   * 
+   * Disable polyfill features:
+   * - 'css-modules': CSS Module imports of the form `import styles from './source.css' with { type: 'css' }`
+   * - 'json-modules': JSON Module imports of the form `import styles from './source.css' with { type: 'css' }`
+   *
+   * These features are enabled by default but only supported in Chrome 123+, so that disabling these features
+   * allows ES Module Shims to avoid unnecessary feature detections and module analysis,
+   * so this will ensure {@link nativePassthrough} for Chrome 89+, Firefox 108+, Safari 16.4+
+   */
+  polyfillDisable?: Array<'css-modules' | 'json-modules'>;
+
+  /**
+   * @default true
+   *
+   * By default, native passthrough is enabled so that modules will be entirely loaded through the native loader
+   * when it is known to be safe to do so. This happens when:
+   *
+   * 1. Polyfill mode is enabled (which is by default, unless shim mode is explicitly enabled)
+   * 2. No hot reloading or hooks options are in use
+   * 3. Then either of:
+   *   a) The browser supports the minimum baseline features expected by ES Module Shims
+   *      (either by default, or as customized via polyfillEnable / polyfillDisable)
+   *   b) Or if the browser does not support the minimum baseline features, ES Module Shims
+   *      will analyze the entire subgraph of modules and still use passthrough after that analysis
+   *      if every module down the graph is known to be natively supported without causing a static error on load.
+   *
+   * Setting this option to false can avoid some potential double fetching on the polyfill path when modules are
+   * analyzed for support, since the native loader cache is not always shared with the fetch cache in some browser.
+   *
+   * In addition dynamic import() not being polyfilled can also be worked around by using this option since it will
+   * replace all dynamic import() expressions with an importShim() expression by using the polyfill loader instead
+   * of the native loader.
+   *
+   * This option is therefore serving two purposes - firstly to easily disable internally in the case of hot reloading
+   * and hooks, and secondly to allow this kind customization in the case of dynamic import or performance cases.
+   */
+  nativePassthrough?: boolean;
+
+  /**
+   * #### Version
+   *
    * Useful when there are multiple instances of ES Module Shims for whatever reason
    * interacting in an application.
-   * 
+   *
    * When set, ES Module Shims will early exit if its own version is not the expected version.
    * Note that this feature is only supported from version 2.4.0 upwards.
    */
@@ -45,30 +87,39 @@ interface ESMSInitOptions {
   enforceIntegrity?: boolean;
 
   /**
-   * Nonce for CSP build
+   * Nonce for CSP compatibility
+   * 
+   * When set, feature detection scripts that run in a separate feature detection
+   * iframe will use this nonce to ensure CSP compatibility.
    */
   nonce?: boolean;
 
   /**
-   * Disable retriggering of document readystate and DOMContentLoaded
+   * Disable retriggering of document readystate, DOMContentLoaded and the window load event.
+   * 
+   * ES Module Shims will re-trigger these events because normally <script type="module"></script>
+   * runs under static defer semantics and results in delaying these events until it completes.
+   * 
+   * When modules are polyfilled, the top-level load will first complete and the events will trigger
+   * before the modules have run, which may result in missing attachments.
+   * 
+   * By retriggering these events we ensure later attachment.
+   * 
+   * The consequence of this approach is that it does assume that attachments are idempotent, and in
+   * where that is not the case this can result in duplicate DOM injections or attachments.
+   * 
+   * This option can therefore be used to disable this feature when those problems arise.
    */
   noLoadEventRetriggers?: boolean;
 
   /**
-   * Enable retriggering of the Window / global 'load' event
-   */
-  globalLoadEventRetrigger?: boolean;
-
-  /**
-   * #### Skip Processing Stability
-   *
-   * > Non-spec feature
    *
    * 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 rewriting. This 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.
+   * from any analysis and rewriting, effectively forcing {@link nativePassthrough}
+   * only for these modules and their dependencies. This improves performance because
+   * those modules then do not need to be processed or transformed at all, so that
+   * e.g. only local application code is handled and not library code.
    *
    * This can be configured by setting the importShim.skip URL regular
    * expression:
@@ -77,10 +128,8 @@ interface ESMSInitOptions {
    * importShim.skip = /^https:\/\/cdn\.com/;
    * ```
    *
-   * By default, this expression supports jspm.dev, dev.jspm.io and
-   * cdn.pika.dev.
    */
-  skip?: RegExp | string[] | string
+  skip?: RegExp | string[] | string;
 
   /**
    * #### Error hook
@@ -105,11 +154,7 @@ interface ESMSInitOptions {
    *
    * Provide a custom resolver function.
    */
-  resolve?: (
-    id: string,
-    parentUrl: string,
-    resolve: (id: string, parentUrl: string) => string
-  ) => string | Promise<string>;
+  resolve?: (id: string, parentUrl: string, parentResolve: (id: string, parentUrl: string) => string) => string;
 
   /**
    * #### Fetch Hook
@@ -172,15 +217,94 @@ interface ESMSInitOptions {
    *   });
    * }
    * ```
+   *
+   * @deprecated use the {@link source} hook instead.
    */
   fetch?: (input: RequestInfo, init?: RequestInit) => Promise<Response>;
 
+  /**
+   * #### Source Hook
+   *
+   * Source hook used to obtain the module source for a given URL.
+   * Can be used to implement virtual modules.
+   *
+   * Note that only valid fetch scheme URLs are supported - http(s): / data: / blob: / file:
+   *
+   * https: or file: is therefore recommended for virtual module paths.
+   *
+   * @example
+   * ```
+   * <script>
+   * const virtualFs = {
+   *   'index.js': `import './src/dep.js';`,
+   *   'src/dep.js': 'console.log("virtual source execution!")'
+   * };
+   * esmsInitOptions = {
+   *   source (url, fetchOpts, parent, defaultSourceHook) {
+   *     // Only virtualize sources under the URL file:///virtual-pkg/ i.e. via
+   *     // `import 'file:///virtual-pkg/index.js'`.
+   *     if (!url.startsWith('file:///virtual-pkg/')) return defaultSourceHook(url, fetchOpts, parent);
+   *
+   *     // Strip the query string prefix for hot reloading workflow support
+   *     const versionQueryParam = url.match(/\?v=\d+$/);
+   *     if (versionQueryParam) url = url.slice(0, -versionQueryParam[0].length);
+   *
+   *     // Lookup the virtual source from the virtual filesystem and return if found
+   *     const virtualSource = virtualFs[url.slice('file:///virtual-pkg/'.length)];
+   *     if (!virtualSource) throw new Error(`Virtual module ${url} not found, imported from ${parent}`);
+   *     return {
+   *       type: 'js',
+   *       source: virtualSource
+   *     };
+   *   }
+   * };
+   * </script>
+   * ```
+   *
+   * For support in hot reloading workflows, note that the ?v={Number} version query
+   * string suffix will be passed so needs to be checked and removed if applicable.
+   *
+   * For JS, CSS, JSON and TypeScript, it provides the source text string.
+   * For WebAssembly, it provides the compiled WebAssembly.Module record.
+   *
+   * The default implementation uses globalThis.fetch to obtain the response and then
+   * the 'content-type' MIME type header to infer the module type, per HTML semantics.
+   *
+   * URL may be returned differently from the request URL because responseURL
+   * is allowed to be distinct from requestURL in the module system even thoough
+   * requestURL is used as the registry key only.
+   *
+   * @param url The URL of the module source being requested
+   * @param fetchOpts Any custom fetch options (including integrity)
+   * @param parent The parent importer URL for debug messages
+   * @param defaultSourceHook The default source hook, to be used as the fallback
+   */
+  source?: (
+    url: string,
+    fetchOpts: RequestInit,
+    parent: string,
+    defaultSourceHook: (
+      url,
+      fetchOptions,
+      parent
+    ) => Promise<{
+      url: string;
+      type: 'js' | 'wasm' | 'css' | 'json' | 'ts';
+      source: string | WebAssembly.Module;
+    }>
+  ) => Promise<{
+    url?: string | undefined;
+    type: 'js' | 'wasm' | 'css' | 'json' | 'ts';
+    source: string | WebAssembly.Module;
+  }>;
+
   /**
    * #### Revoke Blob URLs
    *
    * Set to *true* to cleanup blob URLs from memory after execution.
    * Can cost some compute time for large loads.
    *
+   * @deprecated this option is now on by default and will be removed in a future version.
    */
   revokeBlobURLs?: boolean;
 
@@ -193,11 +317,13 @@ interface ESMSInitOptions {
   mapOverrides?: boolean;
 
   /**
-  * #### Meta hook
-  *
-  * Register a callback for import.meta construction.
-  *
-  */
+   * #### Meta hook
+   *
+   * Register a callback for import.meta construction.
+   *
+   * @param meta The import.meta object to mutate
+   * @param url The URL of the module
+   */
   meta?: (meta: any, url: string) => void;
 
   /**
@@ -205,8 +331,10 @@ interface ESMSInitOptions {
    *
    * Register a callback for top-level imports.
    *
+   * @param url The top-level module being imported
+   * @param fetchOptions the {@link RequestInit} fetch options to used, to also be used for dependencies as well
    */
-  onimport?: (url: string, options: any, parentUrl: string) => void;
+  onimport?: (url: string, fetchOptions: RequestInit, parentUrl: string) => void;
 }
 
 interface ImportMap {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "es-module-shims",
-  "version": "2.5.1",
+  "version": "2.6.1",
   "description": "Shims for the latest ES module features",
   "main": "dist/es-module-shims.js",
   "exports": {