@unrift/core 0.3.0 → 0.5.0

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"}

package/dist/esm/mock/stub.js

@@ -0,0 +1,82 @@
+/**
+ * `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.
+ */
+import { activeRestorers } from "./spy.js";
+/**
+ * Tracks live stubs per target so a repeat `stub()` on the same (target, key)
+ * updates the value in place and returns the ORIGINAL restore. Without this,
+ * the second stub would capture the first stub's value as its "original" and
+ * restoring would leave the first stub in place instead of the real value.
+ */
+const activeStubs = new WeakMap();
+/**
+ * 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 function stub(target, key, value) {
+    // Repeat stub on a live-stubbed key: swap the value, reuse the original
+    // descriptor captured by the first stub.
+    const existing = activeStubs.get(target)?.get(key);
+    if (existing) {
+        Object.defineProperty(target, key, {
+            value,
+            writable: true,
+            configurable: true,
+            enumerable: Object.getOwnPropertyDescriptor(target, key)?.enumerable,
+        });
+        return existing;
+    }
+    const original = Object.getOwnPropertyDescriptor(target, key);
+    const hadOwn = original !== undefined;
+    if (original && original.configurable === false) {
+        throw new Error(`mock.stub() cannot replace non-configurable property "${String(key)}"`);
+    }
+    Object.defineProperty(target, key, {
+        value,
+        writable: true,
+        configurable: true,
+        enumerable: original?.enumerable ?? true,
+    });
+    let restored = false;
+    const restore = () => {
+        if (restored)
+            return;
+        restored = true;
+        if (hadOwn && original) {
+            Object.defineProperty(target, key, original);
+        }
+        else {
+            // Property didn't exist on this object before, remove it to restore original behavior, including prototype inheritance.
+            delete target[key];
+        }
+        activeStubs.get(target)?.delete(key);
+        activeRestorers.delete(restore);
+    };
+    let byKey = activeStubs.get(target);
+    if (!byKey) {
+        byKey = new Map();
+        activeStubs.set(target, byKey);
+    }
+    byKey.set(key, restore);
+    activeRestorers.add(restore);
+    return restore;
+}
+/**
+ * Convenience wrapper: `mock.stub(globalThis, key, value)`. Useful for
+ * swapping `fetch`, `crypto`, `console`, etc. during a test.
+ */
+export function mockGlobal(key, value) {
+    return stub(globalThis, key, value);
+}

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

@@ -0,0 +1,51 @@
+/**
+ * Fake clock - controllable replacements for `setTimeout`, `setInterval`,
+ * `setImmediate`, `process.nextTick`, `queueMicrotask`, `Date`, `Date.now`,
+ * and `performance.now`.
+ *
+ * Tests opt in via `mock.useFakeTimers()` and drain queued tasks deterministically
+ * with `advanceTimersByTime(ms)` / `runAllTimers()` / `runOnlyPendingTimers()`.
+ *
+ * Restoration:
+ *   - `mock.useRealTimers()` reverts every patched global to its original
+ *   - `mock.restoreAll()` does the same as part of bulk cleanup
+ */
+/**
+ * Names of host APIs that `useFakeTimers` can patch. `setTimeout` implicitly
+ * pairs with `clearTimeout`, `setInterval` with `clearInterval`, and
+ * `setImmediate` with `clearImmediate` - you can't fake one half of a pair
+ * without breaking the other.
+ */
+export type FakeableApi = "setTimeout" | "setInterval" | "setImmediate" | "queueMicrotask" | "process.nextTick" | "Date" | "performance";
+export interface UseFakeTimersOptions {
+    now?: Date | string | number;
+    /**
+     * Opt-in: only the listed APIs are faked; everything else stays real.
+     * Mutually exclusive with `doNotFake`.
+     */
+    toFake?: readonly FakeableApi[];
+    /**
+     * Opt-out: everything is faked except the listed APIs.
+     * Mutually exclusive with `toFake`.
+     */
+    doNotFake?: readonly FakeableApi[];
+}
+export declare function useFakeTimers(options?: UseFakeTimersOptions): void;
+export declare function useRealTimers(): void;
+export declare function advanceTimersByTime(ms: number): void;
+export declare function runAllTimers(): void;
+export declare function runOnlyPendingTimers(): void;
+/**
+ * Like `advanceTimersByTime`, but awaits Promise return values from
+ * timer callbacks and yields to microtasks between pumps. Use this when
+ * the code under test does `await` work inside a `setTimeout` callback.
+ */
+export declare function advanceTimersByTimeAsync(ms: number): Promise<void>;
+/** Async sibling of `runAllTimers`. */
+export declare function runAllTimersAsync(): Promise<void>;
+/** Async sibling of `runOnlyPendingTimers`. */
+export declare function runOnlyPendingTimersAsync(): Promise<void>;
+export declare function getTimerCount(): number;
+export declare function setSystemTime(value: Date | string | number): void;
+export declare function getRealSystemTime(): number;
+//# sourceMappingURL=timers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"timers.d.ts","sourceRoot":"","sources":["../../../src/mock/timers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AA2PH;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GACnB,YAAY,GACZ,aAAa,GACb,cAAc,GACd,gBAAgB,GAChB,kBAAkB,GAClB,MAAM,GACN,aAAa,CAAC;AAYlB,MAAM,WAAW,oBAAoB;IAEnC,GAAG,CAAC,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,CAAC;IAC7B;;;OAGG;IACH,MAAM,CAAC,EAAE,SAAS,WAAW,EAAE,CAAC;IAChC;;;OAGG;IACH,SAAS,CAAC,EAAE,SAAS,WAAW,EAAE,CAAC;CACpC;AAmGD,wBAAgB,aAAa,CAAC,OAAO,GAAE,oBAAyB,GAAG,IAAI,CA4GtE;AAED,wBAAgB,aAAa,IAAI,IAAI,CA4CpC;AAED,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAGpD;AAED,wBAAgB,YAAY,IAAI,IAAI,CAcnC;AAED,wBAAgB,oBAAoB,IAAI,IAAI,CAqB3C;AA4CD;;;;GAIG;AACH,wBAAsB,wBAAwB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAiBxE;AAED,uCAAuC;AACvC,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CAcvD;AAED,+CAA+C;AAC/C,wBAAsB,yBAAyB,IAAI,OAAO,CAAC,IAAI,CAAC,CAkB/D;AAED,wBAAgB,aAAa,IAAI,MAAM,CAKtC;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,CAGjE;AAED,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C"}