Merge pull request #102 from testdouble/support-register

support Node v20.6.0 ability to auto-register loader

Author: giltayar

README.md

@@ -74,11 +74,10 @@ Quibble supports ES Modules. Quibble implements ES module support using [ES Modu
 Loaders](https://nodejs.org/api/esm.html#esm_experimental_loaders) which are the official way to
 "patch" Node.js' module loading mechanism for ESM.
 
-> Note that Loader support is currently experimental and unstable. We will be doing our best
-  to track the changes in the specification for the upcoming Node.js versions. Also note that
-  Quibble ESM support is tested only for versions 13 and above.
+> Note that Loader support is currently experimental and unstable. We are doing our best
+  to track the changes in the specification for the upcoming Node.js versions.
 
-To use Quibble support, you must run Node with the `quibble` package as the loader:
+If you're running a Node.js version smaller than v20.6.0, you must run Node with the `quibble` package as a loader:
 
 ```sh
 node --loader=quibble ...
@@ -93,6 +92,9 @@ mocha --loader=quibble ...
 The `quibble` loader will enable the replacement of the ES modules with the stubs you specify, and
 without it, the stubbing will be ignored.
 
+For versions larger or equal to v20.6.0, there is no need to specify a `--loader`, as registering the loader
+happens automatically once you use the API.
+
 ### Restrictions on ESM
 
 * `defaultFakeCreator` is not yet supported.
@@ -140,7 +142,7 @@ resolves the path to the module that is the package's entry point:
   but returns an object with two properties:
   * `module`: the module returned by `await import(importPath)`.
   * `modulePath`: the full path to the module (file) that is the entry point to the package/module.
-  
+
 > Note that when mocking internal Node.js modules (e.g. "[fs](https://nodejs.org/api/fs.html)")), you need to mock the named exports both as named exports and as properties in the default export, because Node.js exports internal modules both as named exports and as a default object. Example:
 
 ```js

example-esm/package-lock.json

@@ -2,7 +2,8 @@
   "name": "quibble-example",
   "private": true,
   "scripts": {
-    "test": "mocha --loader=quibble test/helper.js --recursive test/lib/"
+    "test": "mocha --loader=quibble test/helper.js --recursive test/lib/",
+    "test-auto-loader": "mocha test/helper.js --recursive test/lib/"
   },
   "devDependencies": {
     "chai": "^4.3.7",

example-esm/package.json

@@ -0,0 +1,9 @@
+function canRegisterLoader () {
+  const [major, minor] = process.versions.node
+    .split('.')
+    .map((m) => parseInt(m, 10))
+
+  return major > 20 || (major === 20 && minor >= 6)
+}
+
+exports.canRegisterLoader = canRegisterLoader

example/package-lock.json

@@ -0,0 +1,6 @@
+import { globalPreload } from './quibble.mjs'
+export * from './quibble.mjs'
+
+export function initialize ({ port }) {
+  globalPreload({ port })
+}

lib/canRegisterLoader.js

@@ -21,14 +21,17 @@ const _ = {
   tap: require('lodash/tap'),
   values: require('lodash/values')
 }
+const { MessageChannel } = require('node:worker_threads')
+const { canRegisterLoader } = require('./canRegisterLoader')
 
 const originalLoad = Module._load
 let config = null
 let quibbles = {}
 let ignoredCallerFiles = []
 let quibble
 
-const quibbleUserToLoaderCommunication = () => globalThis[Symbol.for('__quibbleUserToLoaderCommunication')]
+const quibbleUserToLoaderCommunication = () =>
+  globalThis[Symbol.for('__quibbleUserToLoaderCommunication')]
 
 module.exports = quibble = function (request, stub) {
   request = quibble.absolutify(request)
@@ -79,23 +82,33 @@ quibble.absolutify = function (relativePath, parentFileName) {
 
 quibble.esm = async function (specifier, namedExportStubs, defaultExportStub) {
   checkThatLoaderIsLoaded()
-  if (namedExportStubs != null && !util.types.isProxy(namedExportStubs) && !isPlainObject(namedExportStubs)) {
-    throw new Error('namedExportsStub argument must be either a plain object or null/undefined')
+  if (
+    namedExportStubs != null &&
+    !util.types.isProxy(namedExportStubs) &&
+    !isPlainObject(namedExportStubs)
+  ) {
+    throw new Error(
+      'namedExportsStub argument must be either a plain object or null/undefined'
+    )
   }
 
   let finalNamedExportStubs = namedExportStubs
 
   if (finalNamedExportStubs != null && 'default' in finalNamedExportStubs) {
     if (defaultExportStub !== undefined) {
-      throw new Error("conflict between a named export with the name 'default' and the default export stub. You can't have both")
+      throw new Error(
+        "conflict between a named export with the name 'default' and the default export stub. You can't have both"
+      )
     }
     finalNamedExportStubs = { ...namedExportStubs }
     defaultExportStub = namedExportStubs.default
     delete finalNamedExportStubs.default
   }
 
   const importPathIsBareSpecifier = isBareSpecifier(specifier)
-  const parentUrl = importPathIsBareSpecifier ? undefined : hackErrorStackToGetCallerFile(true, true)
+  const parentUrl = importPathIsBareSpecifier
+    ? undefined
+    : hackErrorStackToGetCallerFile(true, true)
   const moduleUrl = importPathIsBareSpecifier
     ? await importFunctions.dummyImportModuleToGetAtPath(specifier)
     : new URL(specifier, parentUrl).href
@@ -114,7 +127,9 @@ quibble.esmImportWithPath = async function esmImportWithPath (specifier) {
   checkThatLoaderIsLoaded()
 
   const importPathIsBareSpecifier = isBareSpecifier(specifier)
-  const parentUrl = importPathIsBareSpecifier ? undefined : hackErrorStackToGetCallerFile(true, true)
+  const parentUrl = importPathIsBareSpecifier
+    ? undefined
+    : hackErrorStackToGetCallerFile(true, true)
   const moduleUrl = importPathIsBareSpecifier
     ? await importFunctions.dummyImportModuleToGetAtPath(specifier)
     : new URL(specifier, parentUrl).href
@@ -154,10 +169,14 @@ const fakeLoad = function (request, parent, isMain) {
   }
 }
 const stubbingThatMatchesRequest = function (request) {
-  return _.ooFind(quibbles, function (stubbing, stubbedPath) {
-    if (request === stubbedPath) return true
-    if (nodeResolve(request) === stubbedPath) return true
-  }, quibbles)
+  return _.ooFind(
+    quibbles,
+    function (stubbing, stubbedPath) {
+      if (request === stubbedPath) return true
+      if (nodeResolve(request) === stubbedPath) return true
+    },
+    quibbles
+  )
 }
 
 const requireWasCalledFromAFileThatHasQuibbledStuff = function () {
@@ -198,15 +217,20 @@ const nodeResolve = function (request, options) {
   } catch (e) {}
 }
 
-const hackErrorStackToGetCallerFile = function (includeGlobalIgnores = true, keepUrls = false) {
+const hackErrorStackToGetCallerFile = function (
+  includeGlobalIgnores = true,
+  keepUrls = false
+) {
   const originalFunc = Error.prepareStackTrace
   const originalStackTraceLimit = Error.stackTraceLimit
   try {
     Error.stackTraceLimit = Math.max(Error.stackTraceLimit, 30)
     Error.prepareStackTrace = function (e, stack) {
       return stack
     }
-    const conversionFunc = keepUrls ? convertStackPathToUrl : convertStackUrlToPath
+    const conversionFunc = keepUrls
+      ? convertStackPathToUrl
+      : convertStackUrlToPath
     const e = new Error()
     const currentFile = conversionFunc(e.stack[0].getFileName())
     return _.flow([
@@ -230,7 +254,13 @@ const hackErrorStackToGetCallerFile = function (includeGlobalIgnores = true, kee
 
 function checkThatLoaderIsLoaded () {
   if (!quibble.isLoaderLoaded()) {
-    throw new Error('quibble loader not loaded. You cannot replace ES modules without a loader. Run node with `--loader=quibble`.')
+    if (canRegisterLoader()) {
+      registerEsmLoader()
+    } else {
+      throw new Error(
+        'quibble loader not loaded. You cannot replace ES modules without a loader. Run Node.js with `--loader=quibble` or use Node.js v20.6.0 or higher.'
+      )
+    }
   }
 }
 
@@ -267,7 +297,7 @@ function isBareSpecifier (modulePath) {
   try {
     // (yes, we DO use new for side-effects!)
     // eslint-disable-next-line
-    new URL(modulePath)
+    new URL(modulePath);
   } catch (error) {
     if (error.code === 'ERR_INVALID_URL') {
       return false
@@ -278,3 +308,17 @@ function isBareSpecifier (modulePath) {
 
   return true
 }
+
+function registerEsmLoader () {
+  const { port1, port2 } = new MessageChannel()
+
+  Module.register(
+    new URL('./quibble-registered.mjs', pathToFileURL(__filename)),
+    { data: { port: port2 }, transferList: [port2] }
+  )
+
+  require('./thisWillRunInUserThread.js').thisWillRunInUserThread(
+    globalThis,
+    port1
+  )
+}

lib/quibble-registered.mjs

@@ -1,4 +1,5 @@
 import quibble from './quibble.js'
+import { thisWillRunInUserThread } from './thisWillRunInUserThread.js'
 
 export default quibble
 export const reset = quibble.reset
@@ -165,61 +166,6 @@ export const globalPreload = ({ port }) => {
   return `(${thisWillRunInUserThread})(globalThis, port)`
 }
 
-async function thisWillRunInUserThread (globalThis, port) {
-  globalThis[Symbol.for('__quibbleUserState')] = { quibbledModules: new Map() }
-
-  globalThis[Symbol.for('__quibbleUserToLoaderCommunication')] = {
-    reset () {
-      globalThis[Symbol.for('__quibbleUserState')].quibbledModules = new Map()
-
-      if (!loaderAndUserRunInSameThread(globalThis)) {
-        const hasResetHappened = new Int32Array(new SharedArrayBuffer(4))
-        port.postMessage({ type: 'reset', hasResetHappened })
-        Atomics.wait(hasResetHappened, 0, 0)
-      } else {
-        const quibbleLoaderState = globalThis[Symbol.for('__quibbleLoaderState')]
-
-        quibbleLoaderState.quibbledModules = new Map()
-        quibbleLoaderState.stubModuleGeneration++
-      }
-    },
-    async addMockedModule (
-      moduleUrl,
-      { namedExportStubs, defaultExportStub }
-    ) {
-      globalThis[Symbol.for('__quibbleUserState')].quibbledModules.set(moduleUrl, {
-        defaultExportStub,
-        namedExportStubs
-      })
-
-      if (!loaderAndUserRunInSameThread(globalThis)) {
-        const hasAddMockedHappened = new Int32Array(new SharedArrayBuffer(4))
-
-        port.postMessage({
-          type: 'addMockedModule',
-          moduleUrl,
-          namedExports: Object.keys(namedExportStubs || []),
-          hasDefaultExport: defaultExportStub != null,
-          hasAddMockedHappened
-        })
-        Atomics.wait(hasAddMockedHappened, 0, 0)
-      } else {
-        const quibbleLoaderState = globalThis[Symbol.for('__quibbleLoaderState')]
-
-        quibbleLoaderState.quibbledModules.set(moduleUrl, {
-          hasDefaultExport: defaultExportStub != null,
-          namedExports: Object.keys(namedExportStubs || [])
-        })
-        ++quibbleLoaderState.stubModuleGeneration
-      }
-    }
-  }
-
-  function loaderAndUserRunInSameThread (globalThis) {
-    return !!globalThis[Symbol.for('__quibbleLoaderState')]
-  }
-}
-
 function addQueryToUrl (url, query, value) {
   const urlObject = new URL(url)
   urlObject.searchParams.set(query, value)

lib/quibble.js

@@ -0,0 +1,54 @@
+exports.thisWillRunInUserThread = (globalThis, port) => {
+  globalThis[Symbol.for('__quibbleUserState')] = { quibbledModules: new Map() }
+
+  globalThis[Symbol.for('__quibbleUserToLoaderCommunication')] = {
+    reset () {
+      globalThis[Symbol.for('__quibbleUserState')].quibbledModules = new Map()
+
+      if (!loaderAndUserRunInSameThread(globalThis)) {
+        const hasResetHappened = new Int32Array(new SharedArrayBuffer(4))
+        port.postMessage({ type: 'reset', hasResetHappened })
+        Atomics.wait(hasResetHappened, 0, 0)
+      } else {
+        const quibbleLoaderState = globalThis[Symbol.for('__quibbleLoaderState')]
+
+        quibbleLoaderState.quibbledModules = new Map()
+        quibbleLoaderState.stubModuleGeneration++
+      }
+    },
+    async addMockedModule (
+      moduleUrl,
+      { namedExportStubs, defaultExportStub }
+    ) {
+      globalThis[Symbol.for('__quibbleUserState')].quibbledModules.set(moduleUrl, {
+        defaultExportStub,
+        namedExportStubs
+      })
+
+      if (!loaderAndUserRunInSameThread(globalThis)) {
+        const hasAddMockedHappened = new Int32Array(new SharedArrayBuffer(4))
+
+        port.postMessage({
+          type: 'addMockedModule',
+          moduleUrl,
+          namedExports: Object.keys(namedExportStubs || []),
+          hasDefaultExport: defaultExportStub != null,
+          hasAddMockedHappened
+        })
+        Atomics.wait(hasAddMockedHappened, 0, 0)
+      } else {
+        const quibbleLoaderState = globalThis[Symbol.for('__quibbleLoaderState')]
+
+        quibbleLoaderState.quibbledModules.set(moduleUrl, {
+          hasDefaultExport: defaultExportStub != null,
+          namedExports: Object.keys(namedExportStubs || [])
+        })
+        ++quibbleLoaderState.stubModuleGeneration
+      }
+    }
+  }
+
+  function loaderAndUserRunInSameThread (globalThis) {
+    return !!globalThis[Symbol.for('__quibbleLoaderState')]
+  }
+}