node-esm-mock 0.1.0

package/README.md

@@ -0,0 +1,83 @@
+# esm-mock
+
+Mock ES modules in Node.js using `registerHooks` (Node >=22.7.0).
+
+No loader flags, no `--experimental-loader`.
+
+## Install
+
+```sh
+npm install esm-mock
+```
+
+## Usage
+
+```ts
+import { mock } from 'esm-mock';
+import assert from 'node:assert';
+import sinon from 'sinon';
+
+const handler = sinon.stub().returns('mocked!');
+
+const mod = await mock({
+    './module.ts': { greet: handler },
+}).for<typeof import('./module.ts')>('./module.ts');
+
+mod.greet();
+assert.equal(handler.callCount, 1);
+```
+
+Without mocks, `for()` imports the module cleanly (cache-busted):
+
+```ts
+const mod = await mock().for('./module.ts');
+```
+
+### API
+
+#### `mock(mocks?)`
+
+| Param | Type | Default | Description |
+|---|---|---|---|
+| `mocks` | `Record<string, Record<string, unknown>>` | `{}` | A map of module specifiers to their replacement exports |
+
+Returns an object with a `for()` method.
+
+#### `mock(mocks).for<T>(specifier): Promise<T>`
+
+| Param | Type | Description |
+|---|---|---|
+| `specifier` | `string` | Module specifier to import (cache-busted with a timestamp query) |
+| `T` (generic) | — | Type of the imported module (optional) |
+
+Imports the given specifier with the configured mocks active. After the import resolves, mock registrations are automatically cleaned up.
+
+### Examples
+
+**Mock a built-in module:**
+
+```ts
+const { Worker } = await mock({
+    'node:worker_threads': { Worker: FakeWorker },
+}).for<typeof import('../worker.js')>('../worker.js');
+```
+
+**No mocks (plain import with cache busting):**
+
+```ts
+const { Worker } = await mock().for('../worker.js');
+assert.ok(Worker instanceof worker_threads.Worker);
+```
+
+## How it works
+
+`esm-mock` registers a [`registerHooks`](https://nodejs.org/api/module.html#moduleregisterhooksoptions) instance at module scope that intercepts `resolve` and `load` for any module URL registered via `add()`. When a mocked module is requested, resolution short-circuits to a synthetic `mock-facade:` URL and `load` serves auto-generated ES module source that re-exports the replacement values.
+
+Each `mock(mocks).for(specifier)` call:
+1. Registers each mock entry via the internal `add()` function.
+2. Dynamically imports the specifier with a cache-busting query parameter.
+3. Cleans up all mock registrations after the import resolves.
+
+## Requirements
+
+- **Node.js >= 22.7.0** (for `module.registerHooks`)

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export declare const mockedModules: Map<any, any>;
+export declare function mock(mocks?: Record<string, Record<string, unknown>>): {
+    for<T = any>(specifier: string): Promise<T>;
+};

package/dist/index.js

@@ -0,0 +1,94 @@
+import { registerHooks } from 'node:module';
+const mockedModuleExports = new Map();
+let mainImportURL = import.meta.url;
+registerHooks({
+    resolve(specifier, context, nextResolve) {
+        var _a;
+        const def = nextResolve(specifier, context);
+        if (!((_a = context.parentURL) === null || _a === void 0 ? void 0 : _a.startsWith('mock-facade:'))) {
+            if (mockedModuleExports.has(def.url)) {
+                return {
+                    shortCircuit: true, url: `mock-facade:${encodeURIComponent(def.url)}`,
+                };
+            }
+        }
+        return def;
+    }, load(url, context, nextLoad) {
+        if (url.startsWith('mock-facade:')) {
+            const encodedTargetURL = url.slice(url.lastIndexOf(':') + 1);
+            return {
+                shortCircuit: true, source: generateModule(encodedTargetURL), format: 'module',
+            };
+        }
+        return nextLoad(url, context);
+    }
+});
+function generateModule(encodedTargetURL) {
+    const exports = mockedModuleExports.get(decodeURIComponent(encodedTargetURL));
+    const body = [
+        `import { mockedModules } from ${JSON.stringify(mainImportURL)};`,
+        'export {};',
+        'let mapping = {__proto__: null};',
+        `const mock = mockedModules.get(${JSON.stringify(encodedTargetURL)});`,
+    ];
+    for (const [i, name] of Object.entries(exports)) {
+        const key = JSON.stringify(name);
+        body.push(`var _${i} = mock.namespace[${key}];`);
+        body.push(`Object.defineProperty(mapping, ${key}, { enumerable: true, set(v) {_${i} = v;}, get() {return _${i};} });`);
+        body.push(`export {_${i} as ${name}};`);
+    }
+    body.push(`mock.listeners.push(() => {
+        for (var k in mapping) {
+            mapping[k] = mock.namespace[k];
+        }
+    });`);
+    return body.join('\n');
+}
+export const mockedModules = new Map();
+function add(resolved, replacementProperties) {
+    const exportNames = Object.keys(replacementProperties);
+    const namespace = { __proto__: null };
+    const listeners = [];
+    for (const name of exportNames) {
+        let currentValueForPropertyName = replacementProperties[name];
+        Object.defineProperty(namespace, name, {
+            // @ts-ignore
+            __proto__: null,
+            enumerable: true,
+            get() {
+                return currentValueForPropertyName;
+            }, set(v) {
+                currentValueForPropertyName = v;
+                for (const fn of listeners) {
+                    try {
+                        fn(name);
+                    }
+                    catch (_a) {
+                        /* noop */
+                    }
+                }
+            },
+        });
+    }
+    mockedModules.set(encodeURIComponent(resolved), {
+        namespace, listeners,
+    });
+    mockedModuleExports.set(resolved, exportNames);
+    return namespace;
+}
+export function mock(mocks = {}) {
+    const mockedModules = new Map();
+    return {
+        for(specifier) {
+            try {
+                for (const spec in mocks) {
+                    mockedModules.set(spec, add(spec, mocks[spec]));
+                }
+                return import(`${specifier}?${+new Date()}`);
+            }
+            finally {
+                mockedModules.forEach((_, mockedModule) => mockedModuleExports.delete(mockedModule));
+            }
+        }
+    };
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "node-esm-mock",
+  "version": "0.1.0",
+  "description": "Mock ES modules in Node.js using registerHooks",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "mock",
+    "module",
+    "esm",
+    "test",
+    "node",
+    "registerHooks"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=22.7.0"
+  },
+  "dependencies": {
+    "typescript": "^5.5.3"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.3",
+    "@types/sinon": "^21.0.1",
+    "sinon": "^22.0.0",
+    "ts-node": "^10.9.2"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "node --test test/index.ts"
+  }
+}