@unrift/core 0.3.0 → 0.4.0

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