import-in-the-middle 3.3.0 → 3.3.2

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## [3.3.2](https://github.com/nodejs/import-in-the-middle/compare/import-in-the-middle-v3.3.1...import-in-the-middle-v3.3.2) (2026-07-20)
+
+
+### Bug Fixes
+
+* delegate tagged modules to their owning loader ([#276](https://github.com/nodejs/import-in-the-middle/issues/276)) ([e0c57bd](https://github.com/nodejs/import-in-the-middle/commit/e0c57bd810d89d74e6a22a14c243d650cbda8a3c))
+* escape loader URL in generated wrappers ([#275](https://github.com/nodejs/import-in-the-middle/issues/275)) ([86ca0e5](https://github.com/nodejs/import-in-the-middle/commit/86ca0e579cb8b592b0ae49cef9bc834b3971592d))
+* skip code generation on broken maglev ([#271](https://github.com/nodejs/import-in-the-middle/issues/271)) ([ae914ac](https://github.com/nodejs/import-in-the-middle/commit/ae914ac41a4cc9215cbaf4fa5ec48fbe3fa8e7b3))
+
+## [3.3.1](https://github.com/nodejs/import-in-the-middle/compare/import-in-the-middle-v3.3.0...import-in-the-middle-v3.3.1) (2026-07-07)
+
+
+### Performance Improvements
+
+* hoist generated wrapper binding runtime ([#267](https://github.com/nodejs/import-in-the-middle/issues/267)) ([4f41140](https://github.com/nodejs/import-in-the-middle/commit/4f41140d44f91448899580cbb97f558539005657))
+* read each wrapped module from disk once ([#265](https://github.com/nodejs/import-in-the-middle/issues/265)) ([22b40aa](https://github.com/nodejs/import-in-the-middle/commit/22b40aa86003934c944b0f586be3889e8c230616))
+
 ## [3.3.0](https://github.com/nodejs/import-in-the-middle/compare/import-in-the-middle-v3.2.0...import-in-the-middle-v3.3.0) (2026-07-02)
 
 

package/README.md

@@ -228,3 +228,12 @@ On Node.js versions where type stripping is not enabled by default, run with
 * While bindings to module exports end up being "re-bound" when modified in a
   hook, dynamically imported modules cannot be altered after they're loaded.
 * Modules loaded via `require` are not affected at all.
+* A module's set of export *names* is assumed to be stable for the lifetime of
+  the process. `import-in-the-middle` reads a module's source once to lex its
+  exports and reuses that export set on later loads of the same URL. An upstream
+  loader that returns a *different set of exports* for the same URL across calls
+  — a stateful codegen loader, or one that varies its output by `context` — is
+  not supported and will be instrumented with the export set from its first
+  load. Idempotent transforms (type stripping, AST instrumentation, minifiers)
+  are unaffected, and the actual module still executes the source its real load
+  returns; only the interceptable export *names* are memoized.

package/create-hook.mjs

@@ -17,7 +17,6 @@ import { supportsSyncHooks } from './supports-sync-hooks.mjs'
 // this file's acorn / cjs-module-lexer dependency graph.
 export { supportsSyncHooks }
 
-const specifiers = new Map()
 const isWin = process.platform === 'win32'
 
 // Depth at which `processModule` starts tracking visited URLs to break an
@@ -37,6 +36,9 @@ const HANDLED_FORMATS = new Set([
 ])
 const TRACE_WARNINGS = process.execArgv.includes('--trace-warnings')
 
+/** @typedef {import('node:module').LoadHookContext} LoadContext */
+/** @typedef {import('node:module').LoadFnOutput} LoadResult */
+
 function hasIitm (url) {
   // Fast path: avoid URL parsing on the hot path when there's clearly no iitm.
   if (typeof url !== 'string' || url.indexOf('iitm') === -1) {
@@ -214,9 +216,9 @@ function buildSetter (n, srcUrl, namespaceVar) {
   const objectKey = JSON.stringify(n)
   const reExportedName = n === 'default' ? n : objectKey
 
-  // `1` makes __bind fall back to namespace['default'] for the module.exports
-  // synthetic export, which builtins don't expose on the native ESM namespace.
-  const fallback = n === 'module.exports' ? ', 1' : ''
+  // Fall back to namespace['default'] for the module.exports synthetic export,
+  // which builtins don't expose on the native ESM namespace.
+  const useFallback = n === 'module.exports'
 
   // Builtins don't expose the module.exports synthetic name, so skip its re-export.
   const reExportLine = (n === 'module.exports' && (srcUrl.startsWith('node:') || builtinModules.includes(srcUrl)))
@@ -224,7 +226,7 @@ function buildSetter (n, srcUrl, namespaceVar) {
     : `export { ${variableName} as ${reExportedName} }`
 
   return `let ${variableName}
-__bind(${objectKey}, ${namespaceVar}, v => { ${variableName} = v }, () => ${variableName}${fallback})
+__binder.bind(${objectKey}, ${namespaceVar}, v => { ${variableName} = v }, () => ${variableName}, ${useFallback})
 ${reExportLine}`
 }
 
@@ -404,7 +406,11 @@ function addIitm (url) {
   return urlObj.href
 }
 
+/**
+ * @param {{ url: string }} meta
+ */
 export function createHook (meta) {
+  const specifiers = new Map()
   let cachedResolve
   const iitmURL = new URL('lib/register.js', meta.url).toString()
   let includeModules, excludeModules
@@ -651,98 +657,16 @@ export function createHook (meta) {
     }
 
     return `
-import { register } from '${iitmURL}'
+import { register, ModuleBinder } from ${JSON.stringify(iitmURL)}
 import * as namespace from ${JSON.stringify(realUrl)}
 ${originImports}
-// Mimic a Module object (https://tc39.es/ecma262/#sec-module-namespace-objects).
-const _ = Object.create(null, { [Symbol.toStringTag]: { value: 'Module' } })
-const set = {}
-const get = {}
-const __overridden = Object.create(null)
-let __pending = []
-
-function __makeUpdater (key, read, assign) {
-  return () => {
-    if (__overridden[key] === true) return true
-    try {
-      const v = read()
-      if (v !== undefined) {
-        assign(v)
-        return true
-      }
-      return false
-    } catch (err) {
-      if (err instanceof ReferenceError) return false
-      throw err
-    }
-  }
-}
-
-function __flushPendingOnce () {
-  if (__pending.length === 0) return
-  const next = []
-  for (const fn of __pending) {
-    // If it still throws ReferenceError, keep it for the (single) next attempt.
-    if (fn() !== true) next.push(fn)
-  }
-  __pending = next
-}
-
-function __bind (key, source, write, read, useFallback) {
-  const readSource = useFallback
-    ? () => source[key] ?? source['default']
-    : () => source[key]
-  __overridden[key] = false
-  let deferred = false
-  try {
-    const v = readSource()
-    write(v)
-    _[key] = v
-  } catch (err) {
-    if (!(err instanceof ReferenceError)) throw err
-    deferred = true
-  }
-  if (deferred || read() === undefined) {
-    __pending.push(__makeUpdater(key, readSource, (v) => { write(v); _[key] = v }))
-  }
-  set[key] = (v) => {
-    __overridden[key] = true
-    write(v)
-    return true
-  }
-  get[key] = read
-}
+const __binder = new ModuleBinder()
 
 ${Array.from(setters.values()).join('\n')}
 
-if (__pending.length > 0) {
-  queueMicrotask(() => {
-    __flushPendingOnce()
-
-    if (__pending.length > 0) {
-      const __retryDelays = [0, 10, 50]
-      const __schedulePending = (i) => {
-        if (__pending.length === 0) return
-        if (i >= __retryDelays.length) {
-          // Give up: leave exports as-is to avoid unbounded retries.
-          __pending = []
-          return
-        }
+__binder.flush()
 
-        const t = setTimeout(() => {
-          __flushPendingOnce()
-          __schedulePending(i + 1)
-        }, __retryDelays[i])
-        // Don't keep the process alive just for best-effort retries.
-        if (t && typeof t.unref === 'function') t.unref()
-      }
-
-      __schedulePending(0)
-    }
-  })
-}
-
-register(${JSON.stringify(realUrl)}, _, set, get, ${JSON.stringify(originalSpecifier)})
+register(${JSON.stringify(realUrl)}, __binder.namespace, __binder.set, __binder.get, ${JSON.stringify(originalSpecifier)})
 `
   }
 
@@ -771,10 +695,19 @@ register(${JSON.stringify(realUrl)}, _, set, get, ${JSON.stringify(originalSpeci
     emitWarning(err)
   }
 
+  /**
+   * @param {string} url
+   * @param {LoadContext} context
+   * @param {(url: string, context?: Partial<LoadContext>) => LoadResult | Promise<LoadResult>} parentGetSource
+   */
   async function getSource (url, context, parentGetSource) {
     if (hasIitm(url)) {
       const realUrl = deleteIitm(url)
       const originalSpecifier = specifiers.get(realUrl)
+      if (originalSpecifier === undefined) {
+        specifiers.delete(url)
+        return parentGetSource(url, context)
+      }
 
       try {
         const { setters, originNamespaces } = await driveAsync(
@@ -795,10 +728,19 @@ register(${JSON.stringify(realUrl)}, _, set, get, ${JSON.stringify(originalSpeci
   // Synchronous counterpart to `getSource`, for `module.registerHooks`. Drives
   // `processModule` straight through; all bookkeeping and source generation is
   // shared with `getSource`.
+  /**
+   * @param {string} url
+   * @param {LoadContext} context
+   * @param {(url: string, context?: Partial<LoadContext>) => LoadResult} nextLoad
+   */
   function getSourceSync (url, context, nextLoad) {
     if (hasIitm(url)) {
       const realUrl = deleteIitm(url)
       const originalSpecifier = specifiers.get(realUrl)
+      if (originalSpecifier === undefined) {
+        specifiers.delete(url)
+        return nextLoad(url, context)
+      }
 
       try {
         const { setters, originNamespaces } = driveSync(

package/lib/get-esm-exports.mjs

@@ -15,8 +15,13 @@ const require = createRequire(import.meta.url)
 // generation from strings is disallowed. Resolve the parser once at load time
 // so the per-module path stays a bare `parse(source)` call.
 const flag = '--disallow-code-generation-from-strings'
+// Node.js versions with broken maglev compiler
+const hasBrokenMaglev = process.version.startsWith('v20.') &&
+  process.version[5] === '.' &&
+  Number(process.version[4]) < 9
 const disallowCodegen = process.execArgv.includes(flag) ||
-  (process.env.NODE_OPTIONS?.includes(flag) ?? false)
+  (process.env.NODE_OPTIONS?.includes(flag) ?? false) ||
+  hasBrokenMaglev
 
 // initSync compiles the Wasm module up front so `parse` can run inside
 // synchronous loader hooks (`module.registerHooks`) as well as the off-thread

package/lib/get-exports.mjs

@@ -73,6 +73,24 @@ function getExportsForNodeBuiltIn (name) {
 
 const urlsBeingProcessed = new Set() // Guard against circular imports.
 
+// Memoizes an ESM module's export names by URL. A leaf reached from several
+// barrels (`export *`) would otherwise be read and lexed once per barrel, and
+// the same URL reached from separate top-level wraps would be lexed once per
+// wrap; the first lex serves every later one.
+//
+// This assumes a module's export names are stable for the process: the memo
+// serves a later, independent scan without re-running the loader chain's
+// `load()`, so a loader that returns a *different export set* for the same URL
+// across calls (a stateful codegen loader, or one keyed off `context`) is a
+// deliberately unsupported case — it would be served the first scan's names.
+// Idempotent transforms (type stripping, AST instrumentation such as
+// OrchestrionJS, minifiers) are stable and unaffected; the wrapper's real
+// namespace `load()` still runs every time, so per-load source differences in
+// the *executed* module are preserved (see the wrapper's `import * as
+// namespace`). Only the pure ESM result is cached: the CommonJS path mutates
+// `context.format` and resolves re-exports, and builtins memoize via BUILT_INS.
+const esmExportsCache = new Map()
+
 /**
  * This function looks for the package.json which contains the specifier trying to resolve.
  * Once the package.json file has been found, we extract the file path from the specifier
@@ -212,6 +230,11 @@ function * getCjsExports (url, context, source) {
  * be included in the result set.
  */
 export function * getExports (url, context) {
+  const cached = esmExportsCache.get(url)
+  if (cached !== undefined) {
+    return cached.exportNames
+  }
+
   // `[LOAD, ...]` gives us the possibility of getting the source from an
   // upstream loader. This doesn't always work though, so later on we fall back
   // to reading it from disk.
@@ -265,6 +288,7 @@ export function * getExports (url, context) {
     const { exportNames, hasModuleSyntax } = lexEsm(source)
 
     if (moduleFormat === 'module') {
+      esmExportsCache.set(url, { exportNames })
       return exportNames
     }
 
@@ -275,6 +299,7 @@ export function * getExports (url, context) {
     if (!exportNames.size && !hasModuleSyntax) {
       return yield * getCjsExports(url, context, source)
     }
+    esmExportsCache.set(url, { exportNames })
     return exportNames
   } catch (cause) {
     const err = new Error(`Failed to parse '${url}'`)

package/lib/register.js

@@ -55,7 +55,143 @@ function register (name, namespace, set, get, specifier) {
   toHook.push([name, proxy, specifier])
 }
 
+// Delays (ms) for re-reading exports that were still in their temporal dead zone
+// when the wrapper first ran (circular imports). Retried on a microtask first,
+// then at these intervals; unref'd so best-effort retries never hold the process
+// open. Frozen once at module load rather than rebuilt per wrapper.
+const RETRY_DELAYS = [0, 10, 50]
+
+/**
+ * Per-wrapped-module state a generated wrapper builds once to expose its exports
+ * through iitm's proxy. Each wrapper holds a local binding per export plus
+ * `write`/`read` closures over it; `bind` seeds that binding from the real
+ * module and installs the proxy's `set`/`get` for the name, and `flush` resolves
+ * any export that was undefined (circular import) once it becomes available.
+ *
+ * This is the boilerplate the wrapper used to inline in full per module. Hoisting
+ * it here compiles it once instead of once per wrapped module and keeps the
+ * per-export bind call site monomorphic.
+ */
+class ModuleBinder {
+  // Mimics a Module namespace object (https://tc39.es/ecma262/#sec-module-namespace-objects).
+  namespace = Object.create(null, { [Symbol.toStringTag]: { value: 'Module' } })
+  set = {}
+  get = {}
+  #overridden = Object.create(null)
+  #pending = []
+
+  /**
+   * Seeds `key` from `source` and installs its proxy accessors. A value that is
+   * undefined or throws `ReferenceError` (temporal dead zone during a circular
+   * import) is deferred to `flush`; any other throw propagates.
+   *
+   * @param {string} key The export name.
+   * @param {object} source The real module namespace to read the value from.
+   * @param {(value: unknown) => void} write Assigns the wrapper's local binding.
+   * @param {() => unknown} read Reads the wrapper's local binding.
+   * @param {boolean} useFallback Fall back to `source.default` (the synthetic
+   * `module.exports` name a builtin does not expose on its ESM namespace).
+   * @returns {void}
+   */
+  bind (key, source, write, read, useFallback) {
+    const readSource = useFallback
+      ? () => source[key] ?? source.default
+      : () => source[key]
+    this.#overridden[key] = false
+    let deferred = false
+    try {
+      const value = readSource()
+      write(value)
+      this.namespace[key] = value
+    } catch (error) {
+      if (!(error instanceof ReferenceError)) throw error
+      deferred = true
+    }
+    if (deferred || read() === undefined) {
+      this.#pending.push(this.#makeUpdater(key, readSource, write))
+    }
+    this.set[key] = (value) => {
+      this.#overridden[key] = true
+      write(value)
+      return true
+    }
+    this.get[key] = read
+  }
+
+  /**
+   * @param {string} key The export name to update.
+   * @param {() => unknown} readSource Reads the current value from the real module.
+   * @param {(value: unknown) => void} write Assigns the wrapper's local binding.
+   * @returns {() => boolean} Updater returning whether the value is now settled.
+   */
+  #makeUpdater (key, readSource, write) {
+    return () => {
+      if (this.#overridden[key] === true) return true
+      try {
+        const value = readSource()
+        if (value !== undefined) {
+          write(value)
+          this.namespace[key] = value
+          return true
+        }
+        return false
+      } catch (error) {
+        if (error instanceof ReferenceError) return false
+        // Only reached if a getter starts throwing a non-ReferenceError after the
+        // initial bind read already succeeded or deferred; surfaces in flush's
+        // microtask. Kept as-is from the inline wrapper.
+        /* c8 ignore next */
+        throw error
+      }
+    }
+  }
+
+  #flushOnce () {
+    const next = []
+    for (const updater of this.#pending) {
+      // If it still throws ReferenceError, keep it for the (single) next attempt.
+      if (updater() !== true) next.push(updater)
+    }
+    this.#pending = next
+  }
+
+  /**
+   * Resolves exports deferred by `bind` (undefined or TDZ at wrapper-eval time).
+   * Retries on a microtask, then at `RETRY_DELAYS`, giving up afterwards to avoid
+   * unbounded retries. A no-op when nothing was deferred.
+   *
+   * @returns {void}
+   */
+  flush () {
+    if (this.#pending.length === 0) return
+    queueMicrotask(() => {
+      this.#flushOnce()
+      this.#scheduleRetry(0)
+    })
+  }
+
+  /**
+   * @param {number} attempt Index into `RETRY_DELAYS` for the next retry.
+   * @returns {void}
+   */
+  #scheduleRetry (attempt) {
+    if (this.#pending.length === 0) return
+    if (attempt >= RETRY_DELAYS.length) {
+      // Give up: leave exports as-is to avoid unbounded retries.
+      this.#pending = []
+      return
+    }
+    const timer = setTimeout(() => {
+      this.#flushOnce()
+      this.#scheduleRetry(attempt + 1)
+    }, RETRY_DELAYS[attempt])
+    // Don't keep the process alive just for best-effort retries.
+    if (timer && typeof timer.unref === 'function') timer.unref()
+  }
+}
+
 exports.register = register
+exports.ModuleBinder = ModuleBinder
 exports.importHooks = importHooks
 exports.specifiers = specifiers
 exports.toHook = toHook

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "import-in-the-middle",
-  "version": "3.3.0",
+  "version": "3.3.2",
   "description": "Intercept imports in Node.js",
   "engines": {
     "node": ">=18"