@unrift/core 0.3.0 → 0.4.0

package/dist/esm/mock/module.js

@@ -0,0 +1,198 @@
+/**
+ * Module mocking - main-thread registry and public API (Tier A).
+ *
+ * Tier A scope:
+ *   - `mock.doMock(spec, factory)` registers a mock for an external module
+ *     specifier (bare package name or `node:*` built-in).
+ *   - Subsequent `await import(spec)` calls return the factory's result.
+ *   - Static imports are NOT supported in Tier A; see the docs / ISSUES.md
+ *     for the planned Tier B (hoisted `mock.module`) work.
+ *
+ * Architecture:
+ *   - bin/unrift.mjs registers `module-loader.js` via `module.register()` and
+ *     pipes a MessagePort into the loader thread.
+ *   - The main-side port is stashed on `globalThis.__unriftLoaderPort` before
+ *     the test runner starts.
+ *   - `doMock()` invokes the factory once, caches the result on
+ *     `globalThis.__unriftMocks`, and posts a `register` message with the
+ *     spec + export-key list to the loader.
+ *   - The loader (see module-loader.ts) drains pending messages on every
+ *     resolve() and short-circuits matched specs to a synthetic module that
+ *     reads back from `globalThis.__unriftMocks`.
+ *
+ * Future tiers will reuse the same registry shape and IPC protocol -
+ * adding `register-hoisted` (Tier B) and `register-relative` (Tier C)
+ * message types without breaking the existing surface.
+ */
+import { activeRestorers, spy } from "./spy.js";
+// The mock registry and loader port below live on globalThis, which is
+// process-global. This is correct under unrift's sequential single-process
+// execution; parallel per-file execution (see ISSUES.md) would need the
+// registry keyed/isolated per worker.
+/**
+ * Sentinel field name on globalThis. Loader-generated synthetic source
+ * reads back through this same name, so it must stay stable.
+ */
+export const MOCKS_GLOBAL_KEY = "__unriftMocks";
+/** Sentinel field name for the IPC port set by bin/unrift.mjs. */
+export const LOADER_PORT_GLOBAL_KEY = "__unriftLoaderPort";
+/** URL prefix the loader uses for mocked modules. Public so tests can assert. */
+export const MOCK_URL_PREFIX = "unrift-mock:";
+function globals() {
+    return globalThis;
+}
+function ensureMocksMap() {
+    const slots = globals();
+    let map = slots[MOCKS_GLOBAL_KEY];
+    if (!map) {
+        map = new Map();
+        slots[MOCKS_GLOBAL_KEY] = map;
+    }
+    return map;
+}
+function getLoaderPort() {
+    return globals()[LOADER_PORT_GLOBAL_KEY];
+}
+/**
+ * JS identifier check. ESM `export const <key>` requires a valid identifier;
+ * keys that fail this check are skipped with a console.warn so the user
+ * isn't surprised by a silently-missing export.
+ */
+const IDENT_RE = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+function partitionExportKeys(spec, result) {
+    const validKeys = [];
+    const skippedKeys = [];
+    for (const key of Object.keys(result)) {
+        if (key === "default" || IDENT_RE.test(key)) {
+            validKeys.push(key);
+        }
+        else {
+            skippedKeys.push(key);
+        }
+    }
+    if (skippedKeys.length > 0) {
+        console.warn(`[unrift] mock.doMock("${spec}"): factory returned ${skippedKeys.length} key(s) that are not valid ` +
+            `JS identifiers and will not be exported: ${skippedKeys.join(", ")}`);
+    }
+    return { validKeys, skippedKeys };
+}
+/**
+ * Track every spec that's currently mocked so `unmock()` can find them
+ * and `restoreAll()` can clean them all up at once.
+ */
+const mockedSpecs = new Set();
+/**
+ * Monotonically increasing counter - every `doMock()` call gets a unique
+ * ID embedded in its synthetic module URL, defeating Node's module cache
+ * across re-registrations.
+ */
+let nextRegistrationId = 0;
+/**
+ * Restore hook registered with the spy/stub bulk-restore registry so
+ * `mock.restoreAll()` cleans up module mocks too.
+ */
+const restoreAllMockedSpecs = () => {
+    for (const spec of [...mockedSpecs]) {
+        unmock(spec);
+    }
+    activeRestorers.delete(restoreAllMockedSpecs);
+};
+/**
+ * Register a mock for `spec`. Subsequent `await import(spec)` calls will
+ * resolve to the factory's return value instead of the real module.
+ *
+ * Tier A constraints (planned to be lifted in Tier B and beyond):
+ *   - Only **dynamic** imports (`await import(spec)`) hit the mock; static
+ *     `import { x } from "spec"` is hoisted by ESM above this call and
+ *     will see the real module.
+ *   - Only **external** specifiers work - bare package names (`"react"`)
+ *     and Node built-ins (`"node:fs"`). Relative specs (`"./bar"`) are
+ *     bundled inline by esbuild and can't be intercepted at runtime.
+ *   - The factory is invoked **once** at registration time. Its return
+ *     value is reused for every subsequent import.
+ *
+ * Throws if the Unrift CLI loader isn't attached (i.e., tests were run
+ * with raw `node` instead of `unrift`).
+ */
+export function doMock(spec, factory) {
+    if (typeof spec !== "string" || spec.length === 0) {
+        throw new TypeError("mock.doMock() requires a non-empty string specifier");
+    }
+    if (typeof factory !== "function") {
+        throw new TypeError("mock.doMock() requires a factory function returning an exports object");
+    }
+    const port = getLoaderPort();
+    if (!port) {
+        throw new Error("mock.doMock() requires the Unrift CLI loader to be installed. " +
+            "Run tests via the `unrift` binary (or `node bin/unrift.mjs`), not raw `node`.");
+    }
+    const result = factory();
+    if (result === null || typeof result !== "object") {
+        throw new TypeError(`mock.doMock("${spec}"): factory must return an object; got ${typeof result}`);
+    }
+    const { validKeys } = partitionExportKeys(spec, result);
+    ensureMocksMap().set(spec, result);
+    mockedSpecs.add(spec);
+    activeRestorers.add(restoreAllMockedSpecs);
+    port.postMessage({
+        type: "register",
+        spec,
+        registrationId: ++nextRegistrationId,
+        exportKeys: validKeys,
+    });
+}
+/**
+ * Remove a previously registered mock. Subsequent `await import(spec)`
+ * calls fall through to the real module.
+ */
+export function unmock(spec) {
+    const port = getLoaderPort();
+    if (port) {
+        port.postMessage({ type: "unregister", spec });
+    }
+    ensureMocksMap().delete(spec);
+    mockedSpecs.delete(spec);
+}
+/** Returns the current set of mocked specs. Useful for tests / debugging. */
+export function listMockedSpecs() {
+    return [...mockedSpecs];
+}
+/**
+ * Convenience helper: imports the real module, builds a version with every
+ * function export wrapped in a spy, registers it via `mock.doMock`, and
+ * returns the mocked exports.
+ *
+ * Non-function exports are passed through unchanged. Tests can customize
+ * individual spies with `.mockReturnValue`, `.mockImplementation`, etc.
+ *
+ * Subject to the same Tier A limits as `doMock` - only affects
+ * `await import(spec)` after the call. Static imports of `spec` see the
+ * real module.
+ *
+ * @example
+ *   const fs = await mock.fromModule("node:fs");
+ *   fs.readFileSync.mockReturnValue("fake content");
+ *   // ... test code that does `await import("node:fs")` now gets the spies
+ */
+export async function fromModule(spec) {
+    if (typeof spec !== "string" || spec.length === 0) {
+        throw new TypeError("mock.fromModule() requires a non-empty string specifier");
+    }
+    const real = (await import(spec));
+    const mocked = {};
+    for (const key of Object.keys(real)) {
+        const value = real[key];
+        if (typeof value === "function") {
+            // Auto-mock: create a spy with NO implementation, so unconfigured
+            // exports record calls and return undefined rather than executing the
+            // real function (which could fire real side effects). Tests opt in to
+            // behavior per export via .mockReturnValue / .mockImplementation.
+            mocked[key] = spy();
+        }
+        else {
+            mocked[key] = value;
+        }
+    }
+    doMock(spec, () => mocked);
+    return mocked;
+}

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

@@ -0,0 +1,17 @@
+/**
+ * Registers the Node module-customization hook that powers module mocking
+ * (mock.doMock / mock.fs / mock.fromModule).
+ *
+ * This is called once, early in the CLI startup (see cli.ts) - before any
+ * test file is dynamically imported. Because it lives in @unrift/core next to
+ * the loader, both the `@unrift/core` bin and the `unrift` wrapper bin get it
+ * "for free" by going through the shared CLI; neither bin needs its own
+ * bootstrap logic.
+ *
+ * The loader runs in a worker thread and receives a MessagePort over which
+ * the main thread posts register/unregister messages. The main-side port is
+ * stashed on globalThis so mock.doMock() can reach it without a circular
+ * import back into the CLI.
+ */
+export declare function registerModuleLoader(): void;
+//# sourceMappingURL=register-loader.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"register-loader.d.ts","sourceRoot":"","sources":["../../../src/mock/register-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AASH,wBAAgB,oBAAoB,IAAI,IAAI,CAyB3C"}

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

@@ -0,0 +1,45 @@
+/**
+ * Registers the Node module-customization hook that powers module mocking
+ * (mock.doMock / mock.fs / mock.fromModule).
+ *
+ * This is called once, early in the CLI startup (see cli.ts) - before any
+ * test file is dynamically imported. Because it lives in @unrift/core next to
+ * the loader, both the `@unrift/core` bin and the `unrift` wrapper bin get it
+ * "for free" by going through the shared CLI; neither bin needs its own
+ * bootstrap logic.
+ *
+ * The loader runs in a worker thread and receives a MessagePort over which
+ * the main thread posts register/unregister messages. The main-side port is
+ * stashed on globalThis so mock.doMock() can reach it without a circular
+ * import back into the CLI.
+ */
+import { register } from "node:module";
+import { MessageChannel } from "node:worker_threads";
+import { LOADER_PORT_GLOBAL_KEY } from "./module.js";
+let done = false;
+export function registerModuleLoader() {
+    if (done)
+        return;
+    done = true;
+    // `module.register()` was added in 18.19.0 / 20.6.0. On older Node, module
+    // mocking simply isn't available - doMock() throws a clear error if used.
+    if (typeof register !== "function")
+        return;
+    try {
+        const { port1, port2 } = new MessageChannel();
+        globalThis[LOADER_PORT_GLOBAL_KEY] = port1;
+        // Resolve the loader relative to this module - it's a sibling file, so no
+        // package export or cross-package specifier is involved.
+        register("./module-loader.js", import.meta.url, {
+            data: { port: port2 },
+            transferList: [port2],
+        });
+    }
+    catch (err) {
+        // Best-effort: a failure here must not crash test runs that don't use
+        // module mocking.
+        if (process.env.UNRIFT_DEBUG === "1") {
+            console.warn("[unrift] module loader registration failed:", err);
+        }
+    }
+}

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

@@ -0,0 +1,73 @@
+/**
+ * Spy / Mock function primitive.
+ *
+ * Both `spy()` and `mock.fn()` produce the same object - a callable that
+ * records every invocation, supports configurable implementations, and can
+ * be restored to the original (when created via `spyOn`).
+ */
+export declare const SPY_BRAND: unique symbol;
+export type AnyFn = (...args: any[]) => any;
+export interface MockResult {
+    type: "return" | "throw";
+    value: unknown;
+}
+export interface MockState {
+    calls: unknown[][];
+    results: MockResult[];
+    contexts: unknown[];
+    instances: unknown[];
+    lastCall: unknown[] | undefined;
+}
+export interface Spy<T extends AnyFn = AnyFn> {
+    (...args: Parameters<T>): ReturnType<T>;
+    mock: MockState;
+    mockName(name: string): Spy<T>;
+    getMockName(): string;
+    mockImplementation(impl: T): Spy<T>;
+    mockImplementationOnce(impl: T): Spy<T>;
+    mockReturnValue(value: ReturnType<T>): Spy<T>;
+    mockReturnValueOnce(value: ReturnType<T>): Spy<T>;
+    mockResolvedValue(value: Awaited<ReturnType<T>>): Spy<T>;
+    mockResolvedValueOnce(value: Awaited<ReturnType<T>>): Spy<T>;
+    mockRejectedValue(error: unknown): Spy<T>;
+    mockRejectedValueOnce(error: unknown): Spy<T>;
+    mockClear(): Spy<T>;
+    mockReset(): Spy<T>;
+    mockRestore(): void;
+    readonly [SPY_BRAND]: true;
+}
+/**
+ * Internal registries. Used by `mock.clearAll()`, `mock.resetAll()`,
+ * and `mock.restoreAll()` to operate on every spy created so far.
+ */
+export declare const activeSpies: Set<Spy<AnyFn>>;
+export declare const activeRestorers: Set<() => void>;
+/**
+ * Returns true if the value is a spy created by `spy()` or `spyOn()`.
+ * Used by mock matchers to validate their `received` argument.
+ */
+export declare function isSpy(value: unknown): value is Spy;
+/**
+ * Creates a standalone spy / mock function. Records every invocation and
+ * supports configurable behavior via `.mockReturnValue`, `.mockImplementation`, etc.
+ */
+export declare function spy<T extends AnyFn = AnyFn>(impl?: T): Spy<T>;
+/**
+ * Replaces `obj[key]` with a spy that wraps the original method. Calling
+ * `.mockRestore()` (or `mock.restoreAll()`) puts the original back.
+ *
+ * The original is the default implementation - calls pass through unless
+ * the user provides an override via `.mockReturnValue` / `.mockImplementation`.
+ *
+ * The 3-arg form `spyOn(obj, "prop", "get")` / `spyOn(obj, "prop", "set")`
+ * wraps the accessor instead of a method. Setter spies record the assigned
+ * value as the first call argument; getter spies record the returned value
+ * in `mock.results`.
+ */
+export declare function spyOn<T extends object, K extends keyof T & (string | symbol)>(obj: T, key: K): T[K] extends AnyFn ? Spy<T[K]> : never;
+export declare function spyOn<T extends object, K extends keyof T & (string | symbol)>(obj: T, key: K, accessor: "get"): Spy<() => T[K]>;
+export declare function spyOn<T extends object, K extends keyof T & (string | symbol)>(obj: T, key: K, accessor: "set"): Spy<(value: T[K]) => void>;
+export declare function clearAllMocks(): void;
+export declare function resetAllMocks(): void;
+export declare function restoreAllMocks(): void;
+//# sourceMappingURL=spy.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"spy.d.ts","sourceRoot":"","sources":["../../../src/mock/spy.ts"],"names":[],"mappings":"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"}

package/dist/esm/mock/spy.js

@@ -0,0 +1,307 @@
+/**
+ * Spy / Mock function primitive.
+ *
+ * Both `spy()` and `mock.fn()` produce the same object - a callable that
+ * records every invocation, supports configurable implementations, and can
+ * be restored to the original (when created via `spyOn`).
+ */
+export const SPY_BRAND = Symbol.for("unrift.spy");
+/**
+ * Internal registries. Used by `mock.clearAll()`, `mock.resetAll()`,
+ * and `mock.restoreAll()` to operate on every spy created so far.
+ */
+export const activeSpies = new Set();
+export const activeRestorers = new Set();
+/**
+ * Returns true if the value is a spy created by `spy()` or `spyOn()`.
+ * Used by mock matchers to validate their `received` argument.
+ */
+export function isSpy(value) {
+    return (typeof value === "function" &&
+        value[SPY_BRAND] === true);
+}
+/**
+ * True if `fn` can be used with `new` / `Reflect.construct`. Arrow functions,
+ * object/class methods, async and generator functions, and most bound
+ * functions are NOT constructable.
+ *
+ * Probes by using `fn` as the `newTarget` of a no-op construct - this
+ * validates constructability without ever invoking `fn`'s body.
+ */
+function isConstructor(fn) {
+    try {
+        Reflect.construct(function () { }, [], fn);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function createSpy(config) {
+    let mockName = "spy";
+    let currentImpl = config.initialImpl;
+    const onceImpls = [];
+    const state = {
+        calls: [],
+        results: [],
+        contexts: [],
+        instances: [],
+        lastCall: undefined,
+    };
+    // The callable. Defined as a regular `function` (not arrow) so it has its own
+    // `this` binding when invoked as a method, and so `new spy(...)` works.
+    function spyImpl(...args) {
+        state.calls.push(args);
+        state.contexts.push(this);
+        state.lastCall = args;
+        /**
+         * Resolution order:
+         *   1. queued one-shot implementations (FIFO)
+         *   2. current permanent implementation
+         *   3. original (spyOn) implementation
+         *   4. no-op returning undefined
+         */
+        const impl = onceImpls.shift() ?? currentImpl ?? config.originalImpl;
+        let isNewTarget = false;
+        try {
+            /**
+             * `new.target` would be cleaner, but inside this regular function we
+             * detect construction by checking whether `this` is an instance whose
+             * prototype matches the spy's prototype.
+             */
+            isNewTarget =
+                new.target !== undefined ||
+                    (this !== undefined &&
+                        this !== null &&
+                        Object.getPrototypeOf(this) === spyImpl.prototype);
+        }
+        catch {
+            isNewTarget = false;
+        }
+        try {
+            let value;
+            if (isNewTarget) {
+                // `new spy()` is always valid, regardless of the implementation.
+                if (impl && isConstructor(impl)) {
+                    // Constructable impl: run it as the constructor with the spy's
+                    // prototype (via newTarget), yielding its own instance.
+                    value = Reflect.construct(impl, args, spyImpl);
+                }
+                else if (impl) {
+                    // Non-constructable impl (arrow, method, async, …): can't
+                    // Reflect.construct it. Run it against the object JS already created
+                    // for us; the instance is that object, unless the impl explicitly
+                    // returns one (constructor return semantics).
+                    const ret = impl.apply(this, args);
+                    value = typeof ret === "object" && ret !== null ? ret : this;
+                }
+                else {
+                    // No impl: the instance is the object JS created for `new spy()`.
+                    value = this;
+                }
+                state.instances.push(value);
+            }
+            else {
+                value = impl ? impl.apply(this, args) : undefined;
+            }
+            state.results.push({ type: "return", value });
+            return value;
+        }
+        catch (err) {
+            state.results.push({ type: "throw", value: err });
+            throw err;
+        }
+    }
+    // Attach state + methods.
+    const spy = spyImpl;
+    Object.defineProperty(spy, SPY_BRAND, {
+        value: true,
+        enumerable: false,
+        configurable: false,
+        writable: false,
+    });
+    Object.defineProperty(spy, "mock", {
+        value: state,
+        enumerable: false,
+        configurable: true,
+        writable: true,
+    });
+    spy.mockName = (name) => {
+        mockName = name;
+        return spy;
+    };
+    spy.getMockName = () => mockName;
+    spy.mockImplementation = (impl) => {
+        currentImpl = impl;
+        return spy;
+    };
+    spy.mockImplementationOnce = (impl) => {
+        onceImpls.push(impl);
+        return spy;
+    };
+    spy.mockReturnValue = (value) => spy.mockImplementation((() => value));
+    spy.mockReturnValueOnce = (value) => spy.mockImplementationOnce((() => value));
+    spy.mockResolvedValue = (value) => spy.mockImplementation((() => Promise.resolve(value)));
+    spy.mockResolvedValueOnce = (value) => spy.mockImplementationOnce((() => Promise.resolve(value)));
+    spy.mockRejectedValue = (error) => spy.mockImplementation((() => Promise.reject(error)));
+    spy.mockRejectedValueOnce = (error) => spy.mockImplementationOnce((() => Promise.reject(error)));
+    spy.mockClear = () => {
+        state.calls.length = 0;
+        state.results.length = 0;
+        state.contexts.length = 0;
+        state.instances.length = 0;
+        state.lastCall = undefined;
+        return spy;
+    };
+    spy.mockReset = () => {
+        spy.mockClear();
+        currentImpl = undefined;
+        onceImpls.length = 0;
+        return spy;
+    };
+    spy.mockRestore = () => {
+        spy.mockReset();
+        if (config.restoreFn) {
+            config.restoreFn();
+            activeRestorers.delete(config.restoreFn);
+        }
+        activeSpies.delete(spy);
+    };
+    activeSpies.add(spy);
+    return spy;
+}
+/**
+ * Creates a standalone spy / mock function. Records every invocation and
+ * supports configurable behavior via `.mockReturnValue`, `.mockImplementation`, etc.
+ */
+export function spy(impl) {
+    return createSpy({ initialImpl: impl });
+}
+/**
+ * Walks the prototype chain to find the descriptor for `key` - needed
+ * because accessor properties (getter/setter) usually live on a prototype,
+ * not on the instance itself.
+ */
+function findDescriptor(obj, key) {
+    let current = obj;
+    while (current !== null) {
+        const descriptor = Object.getOwnPropertyDescriptor(current, key);
+        if (descriptor)
+            return { host: current, descriptor };
+        current = Object.getPrototypeOf(current);
+    }
+    return undefined;
+}
+export function spyOn(obj, key, accessor) {
+    // Accessor (getter/setter) path - 3-arg form.
+    if (accessor === "get" || accessor === "set") {
+        const found = findDescriptor(obj, key);
+        if (!found) {
+            throw new Error(`spyOn() could not find property "${String(key)}" on the target or its prototype chain`);
+        }
+        const { host, descriptor } = found;
+        const original = descriptor[accessor];
+        // Repeat spyOn on an already-spied accessor returns the existing spy.
+        // Wrapping a spy in a spy would capture the first spy as the "original",
+        // and restoring would then put the first spy back instead of the real
+        // accessor - leaking a mock past restoreAll().
+        if (isSpy(original)) {
+            return original;
+        }
+        if (descriptor.configurable === false) {
+            throw new Error(`spyOn() cannot wrap non-configurable property "${String(key)}"`);
+        }
+        if (typeof original !== "function") {
+            throw new Error(`spyOn(..., "${accessor}") requires "${String(key)}" to have a ${accessor}ter`);
+        }
+        // If the spy is on a prototype, restoring needs to put back the
+        // *prototype's* descriptor at the *prototype* level - not on `obj`.
+        // Idempotent: a second run (mockRestore + restoreAll) is a no-op.
+        let restored = false;
+        const restore = () => {
+            if (restored)
+                return;
+            restored = true;
+            Object.defineProperty(host, key, descriptor);
+        };
+        const accessorSpy = createSpy({
+            originalImpl: original,
+            restoreFn: restore,
+        });
+        const newDescriptor = {
+            configurable: true,
+            enumerable: descriptor.enumerable,
+            [accessor]: accessorSpy,
+        };
+        // Preserve the other half of the pair (the unspied accessor stays put).
+        if (accessor === "get" && descriptor.set)
+            newDescriptor.set = descriptor.set;
+        if (accessor === "set" && descriptor.get)
+            newDescriptor.get = descriptor.get;
+        Object.defineProperty(host, key, newDescriptor);
+        activeRestorers.add(restore);
+        return accessorSpy;
+    }
+    // Method path - original 2-arg behavior.
+    const original = obj[key];
+    // Repeat spyOn on an already-spied method returns the existing spy rather
+    // than wrapping it. A spy-wrapping-a-spy would capture the first spy as its
+    // "original", so restore order could put the first spy back after the real
+    // method - leaking a mock past restoreAll().
+    if (isSpy(original)) {
+        return original;
+    }
+    if (typeof original !== "function") {
+        throw new Error(`spyOn() requires a function property; got ${typeof original} for key "${String(key)}"`);
+    }
+    const descriptor = Object.getOwnPropertyDescriptor(obj, key);
+    if (descriptor && descriptor.configurable === false) {
+        throw new Error(`spyOn() cannot wrap non-configurable property "${String(key)}"`);
+    }
+    // Idempotent: mockRestore() followed by restoreAll() must not re-apply.
+    let restored = false;
+    const restore = () => {
+        if (restored)
+            return;
+        restored = true;
+        if (descriptor) {
+            Object.defineProperty(obj, key, descriptor);
+        }
+        else {
+            delete obj[key];
+        }
+    };
+    const spy = createSpy({
+        originalImpl: original,
+        restoreFn: restore,
+    });
+    Object.defineProperty(obj, key, {
+        value: spy,
+        writable: true,
+        configurable: true,
+        enumerable: descriptor?.enumerable ?? true,
+    });
+    activeRestorers.add(restore);
+    return spy;
+}
+// Clear call history on every active spy. Implementations are preserved.
+export function clearAllMocks() {
+    for (const spy of activeSpies)
+        spy.mockClear();
+}
+// Clear call history AND remove all configured implementations on every active spy.
+export function resetAllMocks() {
+    for (const spy of activeSpies)
+        spy.mockReset();
+}
+// Restore originals for every spyOn / stub created so far, then clear all spy state.
+export function restoreAllMocks() {
+    // Iterate over a snapshot - restorers mutate the set as they run.
+    for (const restore of [...activeRestorers]) {
+        restore();
+        activeRestorers.delete(restore);
+    }
+    for (const spy of [...activeSpies])
+        spy.mockReset();
+    activeSpies.clear();
+}

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

@@ -0,0 +1,26 @@
+/**
+ * `mock.stub` - replace any property on any object (function or value),
+ * with restoration tracked centrally so `mock.restoreAll()` can undo it.
+ *
+ * Use `spyOn` when you want a wrapped function spy. Use `stub` when you
+ * want to swap in a fixed value or non-function replacement.
+ */
+/**
+ * Replace `target[key]` with `value`. Returns a function that restores
+ * the original property descriptor (or removes the key entirely if it
+ * didn't exist before).
+ *
+ * Stubbing the same property again before restoring updates the value but
+ * keeps the first stub's original - so restore always yields the real value,
+ * no matter how many times the property was re-stubbed.
+ *
+ * The restorer is also registered with the global `mock.restoreAll()`
+ * pool, so test cleanup can reset every stub at once.
+ */
+export declare function stub<T extends object, K extends keyof T>(target: T, key: K, value: T[K]): () => void;
+/**
+ * Convenience wrapper: `mock.stub(globalThis, key, value)`. Useful for
+ * swapping `fetch`, `crypto`, `console`, etc. during a test.
+ */
+export declare function mockGlobal<K extends string>(key: K, value: unknown): () => void;
+//# sourceMappingURL=stub.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"stub.d.ts","sourceRoot":"","sources":["../../../src/mock/stub.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAYH;;;;;;;;;;;GAWG;AACH,wBAAgB,IAAI,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,CAAC,EACtD,MAAM,EAAE,CAAC,EACT,GAAG,EAAE,CAAC,EACN,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,GACV,MAAM,IAAI,CAuDZ;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,MAAM,EACzC,GAAG,EAAE,CAAC,EACN,KAAK,EAAE,OAAO,GACb,MAAM,IAAI,CAEZ"}