@unrift/core 0.3.0 → 0.5.0

package/dist/esm/mock/fetch.js

@@ -0,0 +1,149 @@
+/**
+ * `mock.fetch` - stub `globalThis.fetch` for HTTP testing.
+ *
+ * Handlers are matched against requests in registration order; the first
+ * matching handler wins. `mock.fetchOnce()` registers a single-use handler
+ * that's consumed after its first match.
+ *
+ * Restoration:
+ *   - `mock.fetch.restore()` un-patches global fetch and clears handlers
+ *   - `mock.restoreAll()` does the same as part of bulk cleanup
+ */
+import { activeRestorers } from "./spy.js";
+import { regexTest } from "../utils/helpers.js";
+/** Brand applied to `mock.fetch` so matchers can verify their received value. */
+export const FETCH_MOCK_BRAND = Symbol.for("unrift.fetchMock");
+// Process-global singleton state. Correct because unrift runs spec files
+// sequentially in one process and afterEach(restoreAll) resets between tests.
+// Parallel per-file execution (see ISSUES.md) would need per-worker isolation.
+const handlers = [];
+const calls = [];
+let originalFetch;
+// Whether globalThis had a `fetch` at install time. If it didn't (older Node,
+// custom runtimes), restore must DELETE our patch rather than leave it - the
+// original state was "fetch is absent", and `originalFetch` being undefined
+// must not be mistaken for "nothing to restore".
+let fetchWasDefined = false;
+let installed = false;
+function urlOf(req) {
+    return req.url;
+}
+async function matches(handler, req) {
+    if (handler.consumed)
+        return false;
+    const m = handler.matcher;
+    if (typeof m === "string")
+        return urlOf(req) === m;
+    if (m instanceof RegExp)
+        return regexTest(m, urlOf(req));
+    if (typeof m === "function")
+        return Boolean(await m(req));
+    return false;
+}
+async function buildResponse(spec, req) {
+    let resolved;
+    if (typeof spec === "function") {
+        resolved = await spec(req);
+    }
+    else {
+        resolved = spec;
+    }
+    if (resolved instanceof Response)
+        return resolved;
+    const init = resolved;
+    let body = init.body;
+    const headers = new Headers(init.headers);
+    if (init.json !== undefined) {
+        body = JSON.stringify(init.json);
+        if (!headers.has("Content-Type")) {
+            headers.set("Content-Type", "application/json");
+        }
+    }
+    return new Response(body ?? null, {
+        status: init.status ?? 200,
+        statusText: init.statusText,
+        headers,
+    });
+}
+function patchedFetch(input, init) {
+    /**
+     * Normalize all call shapes - `fetch(url)`, `fetch(url, init)`,
+     * `fetch(new Request(...))`, `fetch(new Request(...), init)` into a
+     * single Request object that handlers can introspect.
+     */
+    const req = input instanceof Request
+        ? new Request(input, init)
+        : new Request(input, init);
+    calls.push(req);
+    return (async () => {
+        for (const handler of handlers) {
+            if (await matches(handler, req)) {
+                if (handler.once)
+                    handler.consumed = true;
+                return buildResponse(handler.response, req);
+            }
+        }
+        throw new Error(`No mock.fetch handler matched: ${req.method} ${req.url}`);
+    })();
+}
+function install() {
+    if (installed)
+        return;
+    installed = true;
+    // `in` checks presence without triggering Node's lazy fetch getter.
+    fetchWasDefined = "fetch" in globalThis;
+    originalFetch = globalThis.fetch;
+    globalThis.fetch = patchedFetch;
+    activeRestorers.add(restoreFetch);
+}
+function restoreFetch() {
+    if (!installed)
+        return;
+    installed = false;
+    if (fetchWasDefined) {
+        globalThis.fetch = originalFetch;
+    }
+    else {
+        // fetch didn't exist before we patched it - remove our patch so the
+        // environment reads `undefined` again, rather than leaking the stale mock.
+        delete globalThis.fetch;
+    }
+    originalFetch = undefined;
+    fetchWasDefined = false;
+    handlers.length = 0;
+    calls.length = 0;
+    activeRestorers.delete(restoreFetch);
+}
+function register(matcher, response, once) {
+    install();
+    handlers.push({ matcher, response, once, consumed: false });
+}
+// Type guard used by toHaveFetched / toHaveFetchedTimes matchers.
+export function isFetchMock(value) {
+    return (typeof value === "function" &&
+        value[FETCH_MOCK_BRAND] === true);
+}
+const mockFetchImpl = ((matcher, response) => register(matcher, response, false));
+mockFetchImpl.once = (matcher, response) => register(matcher, response, true);
+mockFetchImpl.reset = () => {
+    handlers.length = 0;
+    calls.length = 0;
+};
+mockFetchImpl.restore = restoreFetch;
+Object.defineProperty(mockFetchImpl, "calls", {
+    // Return a snapshot copy, not the internal array, so callers can't mutate
+    // recorded state (e.g. push/splice) and corrupt later assertions.
+    get: () => calls.slice(),
+    enumerable: true,
+    configurable: false,
+});
+Object.defineProperty(mockFetchImpl, FETCH_MOCK_BRAND, {
+    value: true,
+    enumerable: false,
+    configurable: false,
+    writable: false,
+});
+export const mockFetch = mockFetchImpl;
+export function mockFetchOnce(matcher, response) {
+    mockFetch.once(matcher, response);
+}

package/dist/esm/mock/fs.d.ts

@@ -0,0 +1,54 @@
+/**
+ * File system mocking - `mock.fs()`.
+ *
+ * Backed by `memfs` today (private implementation detail behind the
+ * `FakeFsBackend` interface). The plan is to swap memfs for a hand-rolled
+ * package later; consumers of this module should only depend on the public
+ * `FakeFsHandle` surface, not on memfs types directly.
+ *
+ * Interception is layered on Tier A module mocking - `mock.doMock` is
+ * called for `node:fs` and `node:fs/promises`, so the fake takes effect
+ * when test code does `await import("node:fs")` or `await import("node:fs/promises")`.
+ * Static `import { readFileSync } from "node:fs"` is NOT intercepted in
+ * Tier A (planned for Tier B). See the docs page for the explicit limit
+ * list and workarounds.
+ */
+/**
+ * `Volume.fromJSON()` accepts a path-to-content map. `null` represents an
+ * empty directory; strings are file contents.
+ */
+export type FakeFsState = Record<string, string | null>;
+/** Public handle returned by `mock.fs()`. */
+export interface FakeFsHandle {
+    /** Dump the current state as a path-to-content map. */
+    toJSON(): FakeFsState;
+    /** Replace the current state with the given map. */
+    fromJSON(state: FakeFsState): void;
+    /** Read a file's contents, or null if it doesn't exist. */
+    read(path: string): string | null;
+    /** Write a file, creating parent directories as needed. */
+    write(path: string, content: string): void;
+    /** Check whether a path exists in the fake fs. */
+    exists(path: string): boolean;
+    /** Delete a file. Returns true if something was removed. */
+    delete(path: string): boolean;
+    /** List entries in a directory. Returns an empty array if missing. */
+    list(dir: string): string[];
+    /**
+     * Unpatch node:fs and node:fs/promises for this handle's interception.
+     * Idempotent, and a no-op if a later mock.fs() call has already superseded
+     * this handle - so holding an old handle for snapshotting can't tear down
+     * the current volume's interception.
+     */
+    restore(): void;
+}
+/**
+ * Install an in-memory file system as `node:fs` and `node:fs/promises`
+ * for the duration of the test. Subsequent `await import("node:fs")`
+ * calls return the fake.
+ *
+ * Calling `mock.fs()` while a fake is already installed swaps in a fresh
+ * volume - the previous handle's references stop receiving updates.
+ */
+export declare function fs(initial?: FakeFsState): FakeFsHandle;
+//# sourceMappingURL=fs.d.ts.map

package/dist/esm/mock/fs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs.d.ts","sourceRoot":"","sources":["../../../src/mock/fs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAOH;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;AAqFxD,6CAA6C;AAC7C,MAAM,WAAW,YAAY;IAC3B,uDAAuD;IACvD,MAAM,IAAI,WAAW,CAAC;IACtB,oDAAoD;IACpD,QAAQ,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAAC;IACnC,2DAA2D;IAC3D,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAClC,2DAA2D;IAC3D,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3C,kDAAkD;IAClD,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAC9B,4DAA4D;IAC5D,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAC9B,sEAAsE;IACtE,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC5B;;;;;OAKG;IACH,OAAO,IAAI,IAAI,CAAC;CACjB;AAeD;;;;;;;GAOG;AACH,wBAAgB,EAAE,CAAC,OAAO,CAAC,EAAE,WAAW,GAAG,YAAY,CAkCtD"}

package/dist/esm/mock/fs.js

@@ -0,0 +1,125 @@
+/**
+ * File system mocking - `mock.fs()`.
+ *
+ * Backed by `memfs` today (private implementation detail behind the
+ * `FakeFsBackend` interface). The plan is to swap memfs for a hand-rolled
+ * package later; consumers of this module should only depend on the public
+ * `FakeFsHandle` surface, not on memfs types directly.
+ *
+ * Interception is layered on Tier A module mocking - `mock.doMock` is
+ * called for `node:fs` and `node:fs/promises`, so the fake takes effect
+ * when test code does `await import("node:fs")` or `await import("node:fs/promises")`.
+ * Static `import { readFileSync } from "node:fs"` is NOT intercepted in
+ * Tier A (planned for Tier B). See the docs page for the explicit limit
+ * list and workarounds.
+ */
+import { Volume, createFsFromVolume } from "memfs";
+import { doMock, unmock } from "./module.js";
+import { activeRestorers } from "./spy.js";
+/**
+ * The current implementation factory. Swap this single line when replacing
+ * memfs with a hand-rolled backend - no other code changes needed.
+ */
+function createBackend(initial) {
+    const vol = Volume.fromJSON(initial ?? {});
+    const fsExports = createFsFromVolume(vol);
+    // memfs's createFsFromVolume returns the fs surface; .promises is on it.
+    const fsPromisesExports = fsExports
+        .promises;
+    return {
+        fsExports,
+        fsPromisesExports,
+        toJSON: () => vol.toJSON(),
+        fromJSON: (state) => {
+            vol.reset();
+            vol.fromJSON(state);
+        },
+        readFile: (path) => {
+            try {
+                return vol.readFileSync(path, "utf8");
+            }
+            catch {
+                return null;
+            }
+        },
+        writeFile: (path, content) => {
+            // memfs throws if the parent directory doesn't exist; create it for
+            // ergonomic test code.
+            const lastSlash = path.lastIndexOf("/");
+            if (lastSlash > 0) {
+                vol.mkdirSync(path.slice(0, lastSlash), { recursive: true });
+            }
+            vol.writeFileSync(path, content);
+        },
+        exists: (path) => vol.existsSync(path),
+        remove: (path) => {
+            try {
+                vol.unlinkSync(path);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+        list: (dir) => {
+            try {
+                return vol.readdirSync(dir);
+            }
+            catch {
+                return [];
+            }
+        },
+    };
+}
+// Process-global singleton: only one fake fs interception is active at a time.
+// Safe under sequential per-file execution + afterEach(restoreAll); parallel
+// per-file execution (see ISSUES.md) would need per-worker isolation.
+let activeBackend;
+const restoreFakeFs = () => {
+    if (!activeBackend)
+        return;
+    unmock("node:fs");
+    unmock("node:fs/promises");
+    activeBackend = undefined;
+    activeRestorers.delete(restoreFakeFs);
+};
+/**
+ * Install an in-memory file system as `node:fs` and `node:fs/promises`
+ * for the duration of the test. Subsequent `await import("node:fs")`
+ * calls return the fake.
+ *
+ * Calling `mock.fs()` while a fake is already installed swaps in a fresh
+ * volume - the previous handle's references stop receiving updates.
+ */
+export function fs(initial) {
+    // Tear down any existing fake before installing the new one so the
+    // module-mocking registrations don't stack.
+    if (activeBackend) {
+        unmock("node:fs");
+        unmock("node:fs/promises");
+    }
+    const backend = createBackend(initial);
+    activeBackend = backend;
+    doMock("node:fs", () => backend.fsExports);
+    doMock("node:fs/promises", () => backend.fsPromisesExports);
+    activeRestorers.add(restoreFakeFs);
+    const handle = {
+        toJSON: () => backend.toJSON(),
+        fromJSON: (state) => backend.fromJSON(state),
+        read: (path) => backend.readFile(path),
+        write: (path, content) => backend.writeFile(path, content),
+        exists: (path) => backend.exists(path),
+        delete: (path) => backend.remove(path),
+        list: (dir) => backend.list(dir),
+        // Only tear down the interception if THIS handle still owns it. A later
+        // mock.fs() call orphans this handle - its volume lives on for snapshot
+        // inspection, but restoring it must not rip out the newer volume's
+        // interception. On an orphaned handle this is a no-op (also makes restore
+        // idempotent: a second call finds activeBackend already cleared).
+        restore: () => {
+            if (activeBackend === backend)
+                restoreFakeFs();
+        },
+    };
+    return handle;
+}

package/dist/esm/mock/index.d.ts

@@ -0,0 +1,70 @@
+/**
+ * `mock` namespace - single entry point for all mocking utilities.
+ *
+ * Both forms are supported:
+ *   import { mock } from "unrift";
+ *   mock.fn();
+ *   mock.spyOn(obj, "method");
+ *
+ *   import { spy, spyOn } from "unrift";
+ *   spy();
+ *
+ * They produce identical objects.
+ */
+import { spy, spyOn, isSpy, clearAllMocks, resetAllMocks, restoreAllMocks } from "./spy";
+import { mockObject, mockClass } from "./auto";
+import { stub, mockGlobal } from "./stub";
+import { mockFetch, mockFetchOnce } from "./fetch";
+import { useFakeTimers, useRealTimers, advanceTimersByTime, advanceTimersByTimeAsync, runAllTimers, runAllTimersAsync, runOnlyPendingTimers, runOnlyPendingTimersAsync, getTimerCount, setSystemTime, getRealSystemTime } from "./timers";
+import { doMock, unmock, listMockedSpecs, fromModule } from "./module";
+import { fs as mockFs } from "./fs";
+export { spy, spyOn, isSpy, mockObject, mockClass, stub, mockGlobal, mockFetch, mockFetchOnce, useFakeTimers, useRealTimers, advanceTimersByTime, advanceTimersByTimeAsync, runAllTimers, runAllTimersAsync, runOnlyPendingTimers, runOnlyPendingTimersAsync, getTimerCount, setSystemTime, getRealSystemTime, doMock, unmock, listMockedSpecs, fromModule, mockFs, clearAllMocks, resetAllMocks, restoreAllMocks, };
+export type { Spy, MockState, MockResult, AnyFn } from "./spy";
+export type { MockFetch, FetchMatcher, MockResponseInit, MockFetchResponse, } from "./fetch";
+export type { UseFakeTimersOptions, FakeableApi } from "./timers";
+export type { LoaderMessage } from "./module";
+export type { FakeFsHandle, FakeFsState } from "./fs";
+/**
+ * Unified mock namespace. Mirrors Jest / Vitest naming so existing test
+ * code reads naturally:
+ *
+ *   mock.fn(impl?)            // spy()
+ *   mock.spyOn(obj, key)
+ *   mock.object(obj)          // auto-spy every method
+ *   mock.class(Ctor)          // auto-spy every method on instances
+ *   mock.global(key, value)   // stub on globalThis
+ *   mock.stub(target, key, value)
+ *   mock.clearAll()
+ *   mock.resetAll()
+ *   mock.restoreAll()
+ */
+export declare const mock: {
+    readonly fn: typeof spy;
+    readonly spyOn: typeof spyOn;
+    readonly object: typeof mockObject;
+    readonly class: typeof mockClass;
+    readonly global: typeof mockGlobal;
+    readonly stub: typeof stub;
+    readonly fetch: import("./fetch").MockFetch;
+    readonly fetchOnce: typeof mockFetchOnce;
+    readonly useFakeTimers: typeof useFakeTimers;
+    readonly useRealTimers: typeof useRealTimers;
+    readonly advanceTimersByTime: typeof advanceTimersByTime;
+    readonly advanceTimersByTimeAsync: typeof advanceTimersByTimeAsync;
+    readonly runAllTimers: typeof runAllTimers;
+    readonly runAllTimersAsync: typeof runAllTimersAsync;
+    readonly runOnlyPendingTimers: typeof runOnlyPendingTimers;
+    readonly runOnlyPendingTimersAsync: typeof runOnlyPendingTimersAsync;
+    readonly getTimerCount: typeof getTimerCount;
+    readonly setSystemTime: typeof setSystemTime;
+    readonly getRealSystemTime: typeof getRealSystemTime;
+    readonly doMock: typeof doMock;
+    readonly unmock: typeof unmock;
+    readonly fromModule: typeof fromModule;
+    readonly listMockedSpecs: typeof listMockedSpecs;
+    readonly fs: typeof mockFs;
+    readonly clearAll: typeof clearAllMocks;
+    readonly resetAll: typeof resetAllMocks;
+    readonly restoreAll: typeof restoreAllMocks;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/mock/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/mock/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EACL,GAAG,EACH,KAAK,EACL,KAAK,EACL,aAAa,EACb,aAAa,EACb,eAAe,EAChB,MAAM,OAAO,CAAC;AACf,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AAC/C,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EACL,aAAa,EACb,aAAa,EACb,mBAAmB,EACnB,wBAAwB,EACxB,YAAY,EACZ,iBAAiB,EACjB,oBAAoB,EACpB,yBAAyB,EACzB,aAAa,EACb,aAAa,EACb,iBAAiB,EAClB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACvE,OAAO,EAAE,EAAE,IAAI,MAAM,EAAE,MAAM,MAAM,CAAC;AAEpC,OAAO,EACL,GAAG,EACH,KAAK,EACL,KAAK,EACL,UAAU,EACV,SAAS,EACT,IAAI,EACJ,UAAU,EACV,SAAS,EACT,aAAa,EACb,aAAa,EACb,aAAa,EACb,mBAAmB,EACnB,wBAAwB,EACxB,YAAY,EACZ,iBAAiB,EACjB,oBAAoB,EACpB,yBAAyB,EACzB,aAAa,EACb,aAAa,EACb,iBAAiB,EACjB,MAAM,EACN,MAAM,EACN,eAAe,EACf,UAAU,EACV,MAAM,EACN,aAAa,EACb,aAAa,EACb,eAAe,GAChB,CAAC;AAEF,YAAY,EAAE,GAAG,EAAE,SAAS,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC;AAC/D,YAAY,EACV,SAAS,EACT,YAAY,EACZ,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,SAAS,CAAC;AACjB,YAAY,EAAE,oBAAoB,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAClE,YAAY,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAC9C,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,MAAM,CAAC;AAEtD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkCP,CAAC"}

package/dist/esm/mock/index.js

@@ -0,0 +1,70 @@
+/**
+ * `mock` namespace - single entry point for all mocking utilities.
+ *
+ * Both forms are supported:
+ *   import { mock } from "unrift";
+ *   mock.fn();
+ *   mock.spyOn(obj, "method");
+ *
+ *   import { spy, spyOn } from "unrift";
+ *   spy();
+ *
+ * They produce identical objects.
+ */
+import { spy, spyOn, isSpy, clearAllMocks, resetAllMocks, restoreAllMocks, } from "./spy.js";
+import { mockObject, mockClass } from "./auto.js";
+import { stub, mockGlobal } from "./stub.js";
+import { mockFetch, mockFetchOnce } from "./fetch.js";
+import { useFakeTimers, useRealTimers, advanceTimersByTime, advanceTimersByTimeAsync, runAllTimers, runAllTimersAsync, runOnlyPendingTimers, runOnlyPendingTimersAsync, getTimerCount, setSystemTime, getRealSystemTime, } from "./timers.js";
+import { doMock, unmock, listMockedSpecs, fromModule } from "./module.js";
+import { fs as mockFs } from "./fs.js";
+export { spy, spyOn, isSpy, mockObject, mockClass, stub, mockGlobal, mockFetch, mockFetchOnce, useFakeTimers, useRealTimers, advanceTimersByTime, advanceTimersByTimeAsync, runAllTimers, runAllTimersAsync, runOnlyPendingTimers, runOnlyPendingTimersAsync, getTimerCount, setSystemTime, getRealSystemTime, doMock, unmock, listMockedSpecs, fromModule, mockFs, clearAllMocks, resetAllMocks, restoreAllMocks, };
+/**
+ * Unified mock namespace. Mirrors Jest / Vitest naming so existing test
+ * code reads naturally:
+ *
+ *   mock.fn(impl?)            // spy()
+ *   mock.spyOn(obj, key)
+ *   mock.object(obj)          // auto-spy every method
+ *   mock.class(Ctor)          // auto-spy every method on instances
+ *   mock.global(key, value)   // stub on globalThis
+ *   mock.stub(target, key, value)
+ *   mock.clearAll()
+ *   mock.resetAll()
+ *   mock.restoreAll()
+ */
+export const mock = {
+    fn: spy,
+    spyOn,
+    object: mockObject,
+    class: mockClass,
+    global: mockGlobal,
+    stub,
+    fetch: mockFetch,
+    fetchOnce: mockFetchOnce,
+    useFakeTimers,
+    useRealTimers,
+    advanceTimersByTime,
+    advanceTimersByTimeAsync,
+    runAllTimers,
+    runAllTimersAsync,
+    runOnlyPendingTimers,
+    runOnlyPendingTimersAsync,
+    getTimerCount,
+    setSystemTime,
+    getRealSystemTime,
+    // Tier A module mocking - dynamic imports of external specs only.
+    // The hoisted `mock.module(spec, factory)` for static imports is
+    // planned for Tier B and intentionally not exposed yet.
+    doMock,
+    unmock,
+    fromModule,
+    listMockedSpecs,
+    // File system mocking - backed by memfs, layered on Tier A module
+    // mocking. Works with `await import("node:fs")`; static imports of
+    // node:fs are not intercepted yet (planned for Tier B).
+    fs: mockFs,
+    clearAll: clearAllMocks,
+    resetAll: resetAllMocks,
+    restoreAll: restoreAllMocks,
+};

package/dist/esm/mock/module-loader.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Node module customization hook for unrift module mocking (Tier A).
+ *
+ * Registered by `bin/unrift.mjs` via `module.register()`. Runs in a
+ * worker thread (Node 20.6+ / 18.19+ behavior). Communicates with the
+ * main thread via a `MessagePort` to learn which specs have been mocked.
+ *
+ * Why we use `receiveMessageOnPort()` instead of `port.on("message")`:
+ * the resolve hook runs synchronously from the perspective of the
+ * import pipeline, but Worker `MessagePort` listeners are async.
+ * `receiveMessageOnPort()` (Node 18.7+) drains pending messages
+ * synchronously so registrations posted from the main thread are
+ * visible by the time the corresponding `await import(spec)` reaches
+ * us.
+ *
+ * The generated synthetic module source runs back in the MAIN thread
+ * (Node's loader output is evaluated in the importing thread, not the
+ * loader thread). That source reads exports from `globalThis.__unriftMocks`,
+ * which the main thread populates in `mock.doMock()`.
+ *
+ * Source compiled by tsc and shipped at `dist/esm/mock/module-loader.js`.
+ */
+import { type MessagePort } from "node:worker_threads";
+interface InitializeData {
+    port: MessagePort;
+}
+/**
+ * Generate ESM source for a mocked spec. The source executes in the
+ * MAIN thread (not the loader thread) - that's where the actual mock
+ * object lives, keyed in `globalThis.__unriftMocks`.
+ *
+ * Pure function so future tiers can reuse this for hoisted (Tier B)
+ * and relative (Tier C) mocks without rewriting the emitter.
+ */
+export declare function generateMockSource(spec: string, exportKeys: readonly string[]): string;
+/** Node hook: called once when the loader is registered. */
+export declare function initialize(data: InitializeData): void;
+interface ResolveContext {
+    conditions: readonly string[];
+    importAttributes?: Record<string, string>;
+    parentURL?: string;
+}
+interface ResolveResult {
+    url: string;
+    format?: string;
+    shortCircuit?: boolean;
+    importAttributes?: Record<string, string>;
+}
+type DefaultResolve = (specifier: string, context: ResolveContext) => ResolveResult | Promise<ResolveResult>;
+/** Node hook: short-circuit mocked specs to a `unrift-mock:` URL. */
+export declare function resolve(specifier: string, context: ResolveContext, nextResolve: DefaultResolve): Promise<ResolveResult>;
+interface LoadContext {
+    format?: string;
+    importAttributes?: Record<string, string>;
+    conditions?: readonly string[];
+}
+interface LoadResult {
+    format: string;
+    source?: string | ArrayBuffer | Uint8Array;
+    shortCircuit?: boolean;
+}
+type DefaultLoad = (url: string, context: LoadContext) => LoadResult | Promise<LoadResult>;
+/** Node hook: emit synthetic ESM source for mocked specs. */
+export declare function load(url: string, context: LoadContext, nextLoad: DefaultLoad): Promise<LoadResult>;
+export {};
+//# sourceMappingURL=module-loader.d.ts.map

package/dist/esm/mock/module-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module-loader.d.ts","sourceRoot":"","sources":["../../../src/mock/module-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAwB,KAAK,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAQ7E,UAAU,cAAc;IACtB,IAAI,EAAE,WAAW,CAAC;CACnB;AAmCD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,SAAS,MAAM,EAAE,GAC5B,MAAM,CAuBR;AAED,4DAA4D;AAC5D,wBAAgB,UAAU,CAAC,IAAI,EAAE,cAAc,GAAG,IAAI,CAErD;AAED,UAAU,cAAc;IACtB,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,UAAU,aAAa;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC3C;AAED,KAAK,cAAc,GAAG,CACpB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,cAAc,KACpB,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;AAE5C,qEAAqE;AACrE,wBAAsB,OAAO,CAC3B,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,cAAc,EACvB,WAAW,EAAE,cAAc,GAC1B,OAAO,CAAC,aAAa,CAAC,CAexB;AAED,UAAU,WAAW;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAChC;AAED,UAAU,UAAU;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,GAAG,WAAW,GAAG,UAAU,CAAC;IAC3C,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,KAAK,WAAW,GAAG,CACjB,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,WAAW,KACjB,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;AAEtC,6DAA6D;AAC7D,wBAAsB,IAAI,CACxB,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,WAAW,EACpB,QAAQ,EAAE,WAAW,GACpB,OAAO,CAAC,UAAU,CAAC,CA0BrB"}

package/dist/esm/mock/module-loader.js

@@ -0,0 +1,123 @@
+/**
+ * Node module customization hook for unrift module mocking (Tier A).
+ *
+ * Registered by `bin/unrift.mjs` via `module.register()`. Runs in a
+ * worker thread (Node 20.6+ / 18.19+ behavior). Communicates with the
+ * main thread via a `MessagePort` to learn which specs have been mocked.
+ *
+ * Why we use `receiveMessageOnPort()` instead of `port.on("message")`:
+ * the resolve hook runs synchronously from the perspective of the
+ * import pipeline, but Worker `MessagePort` listeners are async.
+ * `receiveMessageOnPort()` (Node 18.7+) drains pending messages
+ * synchronously so registrations posted from the main thread are
+ * visible by the time the corresponding `await import(spec)` reaches
+ * us.
+ *
+ * The generated synthetic module source runs back in the MAIN thread
+ * (Node's loader output is evaluated in the importing thread, not the
+ * loader thread). That source reads exports from `globalThis.__unriftMocks`,
+ * which the main thread populates in `mock.doMock()`.
+ *
+ * Source compiled by tsc and shipped at `dist/esm/mock/module-loader.js`.
+ */
+import { receiveMessageOnPort } from "node:worker_threads";
+import { MOCKS_GLOBAL_KEY, MOCK_URL_PREFIX, } from "./module.js";
+// Loader-thread state. Populated by `initialize()` and updated by
+// drainMessages() on every resolve() call.
+let loaderPort;
+const registered = new Map();
+/**
+ * Pull every pending message off the port synchronously. Called at the
+ * top of every resolve() and load() hook so the loader's view of the
+ * registry is always current.
+ */
+function drainMessages() {
+    if (!loaderPort)
+        return;
+    let received = receiveMessageOnPort(loaderPort);
+    while (received !== undefined) {
+        const message = received.message;
+        if (message.type === "register") {
+            registered.set(message.spec, {
+                registrationId: message.registrationId,
+                exportKeys: message.exportKeys,
+            });
+        }
+        else if (message.type === "unregister") {
+            registered.delete(message.spec);
+        }
+        received = receiveMessageOnPort(loaderPort);
+    }
+}
+/**
+ * Generate ESM source for a mocked spec. The source executes in the
+ * MAIN thread (not the loader thread) - that's where the actual mock
+ * object lives, keyed in `globalThis.__unriftMocks`.
+ *
+ * Pure function so future tiers can reuse this for hoisted (Tier B)
+ * and relative (Tier C) mocks without rewriting the emitter.
+ */
+export function generateMockSource(spec, exportKeys) {
+    const specJson = JSON.stringify(spec);
+    const lines = [
+        `// Generated by unrift module mocking - do not edit.`,
+        `const __mocks = globalThis[${JSON.stringify(MOCKS_GLOBAL_KEY)}];`,
+        `if (!__mocks || !__mocks.has(${specJson})) {`,
+        `  throw new Error(`,
+        `    "Unrift module mock registry is missing the entry for " + ${specJson} + ". " +`,
+        `    "This usually means mock.unmock() ran between registration and import."`,
+        `  );`,
+        `}`,
+        `const __exports = __mocks.get(${specJson});`,
+    ];
+    for (const key of exportKeys) {
+        if (key === "default") {
+            lines.push(`export default __exports.default;`);
+        }
+        else {
+            lines.push(`export const ${key} = __exports[${JSON.stringify(key)}];`);
+        }
+    }
+    return lines.join("\n");
+}
+/** Node hook: called once when the loader is registered. */
+export function initialize(data) {
+    loaderPort = data.port;
+}
+/** Node hook: short-circuit mocked specs to a `unrift-mock:` URL. */
+export async function resolve(specifier, context, nextResolve) {
+    drainMessages();
+    const entry = registered.get(specifier);
+    if (entry) {
+        // Embed the registration ID in the URL so Node's URL-keyed module
+        // cache treats each re-mock of the same spec as a fresh module.
+        return {
+            url: `${MOCK_URL_PREFIX}${specifier}?v=${entry.registrationId}`,
+            format: "module",
+            shortCircuit: true,
+        };
+    }
+    return nextResolve(specifier, context);
+}
+/** Node hook: emit synthetic ESM source for mocked specs. */
+export async function load(url, context, nextLoad) {
+    if (url.startsWith(MOCK_URL_PREFIX)) {
+        drainMessages();
+        // URL shape: `unrift-mock:<spec>?v=<registrationId>`
+        const withoutPrefix = url.slice(MOCK_URL_PREFIX.length);
+        const queryIdx = withoutPrefix.indexOf("?");
+        const spec = queryIdx === -1 ? withoutPrefix : withoutPrefix.slice(0, queryIdx);
+        const entry = registered.get(spec);
+        if (!entry) {
+            // The user called mock.unmock() between resolve() and load().
+            // Fall through to the real module so the import still works.
+            return nextLoad(spec, context);
+        }
+        return {
+            format: "module",
+            source: generateMockSource(spec, entry.exportKeys),
+            shortCircuit: true,
+        };
+    }
+    return nextLoad(url, context);
+}