@c9up/helix 0.1.3 → 0.1.4

package/dist/runtime/suite.js

@@ -0,0 +1,203 @@
+/**
+ * `describe` / `test` / `it` DSL — builds a suite tree during module load.
+ *
+ * Collection phase: `describe(name, fn)` runs `fn` synchronously with an
+ * active suite on a per-invocation stack. `withCollection(...)` scopes the
+ * collection to one `runTestFile` call via AsyncLocalStorage, so parallel
+ * invocations never share state.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+function makeSuite(name, mode, parent) {
+    return {
+        kind: "suite",
+        name,
+        mode,
+        parent,
+        children: [],
+        hooks: [],
+    };
+}
+/**
+ * Scoped collection context. Each `runTestFile` invocation opens its own
+ * store so concurrent runs never see each other's registrations.
+ */
+const storage = new AsyncLocalStorage();
+/**
+ * Fallback context used when the DSL is called outside `runTestFile` (e.g.,
+ * unit tests that drive `describe`/`test` directly). `resetRoot` replaces
+ * this; `getRoot` returns it.
+ */
+let fallbackRoot = makeSuite("", "run", undefined);
+let fallbackStack = [fallbackRoot];
+function currentContext() {
+    const scoped = storage.getStore();
+    if (scoped)
+        return scoped;
+    return { root: fallbackRoot, stack: fallbackStack };
+}
+export function resetRoot() {
+    fallbackRoot = makeSuite("", "run", undefined);
+    fallbackStack = [fallbackRoot];
+    return fallbackRoot;
+}
+export function getRoot() {
+    return currentContext().root;
+}
+/**
+ * Run `body` inside a fresh, isolated collection context. Returns the root
+ * populated by its DSL calls. Safe under concurrent invocation.
+ */
+export async function withCollection(body) {
+    const root = makeSuite("", "run", undefined);
+    const ctx = { root, stack: [root] };
+    await storage.run(ctx, async () => {
+        await body();
+    });
+    return root;
+}
+function current() {
+    const { stack } = currentContext();
+    const top = stack[stack.length - 1];
+    if (!top)
+        throw new Error("internal: suite stack empty");
+    return top;
+}
+function registerTest(name, mode, fn) {
+    const parent = current();
+    parent.children.push({
+        kind: "test",
+        name,
+        fn,
+        mode,
+        parent,
+    });
+}
+function registerSuite(name, mode, body) {
+    const ctx = currentContext();
+    const parent = current();
+    const suite = makeSuite(name, mode, parent);
+    parent.children.push(suite);
+    ctx.stack.push(suite);
+    let result;
+    try {
+        result = body();
+    }
+    finally {
+        ctx.stack.pop();
+    }
+    // Async describe bodies would register nested describe/test against the
+    // wrong parent after the first `await` (because we've already popped).
+    // Fail loudly rather than silently mis-collect.
+    if (result && typeof result.then === "function") {
+        throw new Error(`describe(${JSON.stringify(name)}): body returned a Promise. Async describe is not supported — await the setup in a \`beforeAll\` hook instead.`);
+    }
+}
+function safeStringify(v) {
+    try {
+        const s = JSON.stringify(v);
+        return s === undefined ? String(v) : s;
+    }
+    catch {
+        // Circular / BigInt / etc.
+        return String(v);
+    }
+}
+function isArrayRow(row) {
+    return Array.isArray(row);
+}
+function isObjectRow(row) {
+    return typeof row === "object" && row !== null && !Array.isArray(row);
+}
+function interpolateArrayRow(template, row, index) {
+    // Hand-rolled walker so `%%` escapes to a literal `%` without consuming a
+    // row value, and format specifiers consume their argument in order.
+    let i = 0;
+    let out = "";
+    for (let j = 0; j < template.length; j += 1) {
+        const c = template[j];
+        if (c !== "%" || j === template.length - 1) {
+            out += c;
+            continue;
+        }
+        const next = template[j + 1];
+        if (next === "%") {
+            out += "%";
+            j += 1;
+            continue;
+        }
+        if (next === "#") {
+            out += String(index);
+            j += 1;
+            continue;
+        }
+        if (next === "s" ||
+            next === "d" ||
+            next === "i" ||
+            next === "f" ||
+            next === "j" ||
+            next === "o") {
+            const v = row[i];
+            i += 1;
+            out += typeof v === "object" && v !== null ? safeStringify(v) : String(v);
+            j += 1;
+            continue;
+        }
+        out += c;
+    }
+    return out;
+}
+function interpolateObjectRow(template, row, index) {
+    return template
+        .replace(/\$#/g, String(index))
+        .replace(/\$([a-zA-Z_][\w.]*)/g, (_match, path) => {
+        const parts = path.split(".");
+        let cursor = row;
+        for (const p of parts) {
+            if (cursor && typeof cursor === "object" && p in cursor) {
+                cursor = Reflect.get(cursor, p);
+            }
+            else {
+                return "undefined";
+            }
+        }
+        if (typeof cursor === "object" && cursor !== null)
+            return safeStringify(cursor);
+        return String(cursor);
+    });
+}
+function interpolateEach(template, row, index) {
+    if (isArrayRow(row))
+        return interpolateArrayRow(template, row, index);
+    if (isObjectRow(row))
+        return interpolateObjectRow(template, row, index);
+    // Primitive row (number, string, boolean, bigint, symbol, null, undefined).
+    // Append index so names don't collide.
+    return `${template} [${index}]`;
+}
+const describeFn = ((name, fn) => registerSuite(name, "run", fn));
+describeFn.skip = (name, fn) => registerSuite(name, "skip", fn);
+describeFn.only = (name, fn) => registerSuite(name, "only", fn);
+describeFn.todo = (name) => registerSuite(name, "todo", () => { });
+const testFn = ((name, fn) => registerTest(name, "run", fn));
+testFn.skip = (name, fn) => registerTest(name, "skip", fn);
+testFn.only = (name, fn) => registerTest(name, "only", fn);
+testFn.todo = (name) => registerTest(name, "todo", undefined);
+testFn.each = (rows) => {
+    return (name, fn) => {
+        rows.forEach((row, index) => {
+            const resolvedName = interpolateEach(name, row, index);
+            registerTest(resolvedName, "run", () => fn(row));
+        });
+    };
+};
+export const describe = describeFn;
+export const test = testFn;
+export const it = testFn;
+export function addHook(type, fn) {
+    current().hooks.push({ type, fn });
+}
+export const beforeAll = (fn) => addHook("beforeAll", fn);
+export const afterAll = (fn) => addHook("afterAll", fn);
+export const beforeEach = (fn) => addHook("beforeEach", fn);
+export const afterEach = (fn) => addHook("afterEach", fn);
+//# sourceMappingURL=suite.js.map

package/dist/runtime/suite.js.map

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

package/dist/runtime/test-context.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Per-test execution frame.
+ *
+ * Whereas `withViContext` wraps each test FILE (so spies and fake
+ * timers can span tests within a file), `withTestContext` wraps each
+ * INDIVIDUAL test (cycle = beforeEach + body + afterEach). It exists
+ * so test-scoped resources — most notably container overrides
+ * registered through `helix.override()` — get torn down between tests
+ * without needing the user to wire `afterEach(restore)` by hand.
+ *
+ * Cleanup semantics mirror `withViContext`'s finally:
+ *   - reverse insertion order
+ *   - one cleanup throwing must not block the others
+ */
+export type TestCleanup = () => void | Promise<void>;
+export declare function withTestContext<T>(body: () => Promise<T>): Promise<T>;
+/**
+ * Register a cleanup function that runs at the end of the current
+ * test cycle. Returns `true` when registered, `false` when called
+ * outside a test frame (caller decides — usually a no-op or fallback
+ * to a wider frame).
+ */
+export declare function registerTestCleanup(cleanup: TestCleanup): boolean;
+export declare function inTestContext(): boolean;
+//# sourceMappingURL=test-context.d.ts.map

package/dist/runtime/test-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-context.d.ts","sourceRoot":"","sources":["../../src/runtime/test-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,MAAM,MAAM,WAAW,GAAG,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAQrD,wBAAsB,eAAe,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAgB3E;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAKjE;AAED,wBAAgB,aAAa,IAAI,OAAO,CAEvC"}

package/dist/runtime/test-context.js

@@ -0,0 +1,52 @@
+/**
+ * Per-test execution frame.
+ *
+ * Whereas `withViContext` wraps each test FILE (so spies and fake
+ * timers can span tests within a file), `withTestContext` wraps each
+ * INDIVIDUAL test (cycle = beforeEach + body + afterEach). It exists
+ * so test-scoped resources — most notably container overrides
+ * registered through `helix.override()` — get torn down between tests
+ * without needing the user to wire `afterEach(restore)` by hand.
+ *
+ * Cleanup semantics mirror `withViContext`'s finally:
+ *   - reverse insertion order
+ *   - one cleanup throwing must not block the others
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+const storage = new AsyncLocalStorage();
+export async function withTestContext(body) {
+    const frame = { cleanups: [] };
+    try {
+        return await storage.run(frame, body);
+    }
+    finally {
+        for (let i = frame.cleanups.length - 1; i >= 0; i -= 1) {
+            try {
+                await frame.cleanups[i]();
+            }
+            catch (err) {
+                // One cleanup failing must not block the others — but log it
+                // so silent leaks become noisy. `console.error` matches what
+                // Vitest does for `afterEach` failures observed at runtime.
+                console.error("[helix] test cleanup failed:", err);
+            }
+        }
+    }
+}
+/**
+ * Register a cleanup function that runs at the end of the current
+ * test cycle. Returns `true` when registered, `false` when called
+ * outside a test frame (caller decides — usually a no-op or fallback
+ * to a wider frame).
+ */
+export function registerTestCleanup(cleanup) {
+    const frame = storage.getStore();
+    if (!frame)
+        return false;
+    frame.cleanups.push(cleanup);
+    return true;
+}
+export function inTestContext() {
+    return storage.getStore() !== undefined;
+}
+//# sourceMappingURL=test-context.js.map

package/dist/runtime/test-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-context.js","sourceRoot":"","sources":["../../src/runtime/test-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAQrD,MAAM,OAAO,GAAG,IAAI,iBAAiB,EAAa,CAAC;AAEnD,MAAM,CAAC,KAAK,UAAU,eAAe,CAAI,IAAsB;IAC9D,MAAM,KAAK,GAAc,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;IAC1C,IAAI,CAAC;QACJ,OAAO,MAAM,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IACvC,CAAC;YAAS,CAAC;QACV,KAAK,IAAI,CAAC,GAAG,KAAK,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;YACxD,IAAI,CAAC;gBACJ,MAAM,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;YAC3B,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACd,6DAA6D;gBAC7D,6DAA6D;gBAC7D,4DAA4D;gBAC5D,OAAO,CAAC,KAAK,CAAC,8BAA8B,EAAE,GAAG,CAAC,CAAC;YACpD,CAAC;QACF,CAAC;IACF,CAAC;AACF,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAAoB;IACvD,MAAM,KAAK,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IACjC,IAAI,CAAC,KAAK;QAAE,OAAO,KAAK,CAAC;IACzB,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC7B,OAAO,IAAI,CAAC;AACb,CAAC;AAED,MAAM,UAAU,aAAa;IAC5B,OAAO,OAAO,CAAC,QAAQ,EAAE,KAAK,SAAS,CAAC;AACzC,CAAC"}

package/dist/runtime/vi/fake-timers.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Fake-timer core — swaps the global timer APIs for a deterministic
+ * scheduler. Mirrors the subset of Vitest we need:
+ *   setTimeout / setInterval / setImmediate (+ clear*)
+ *   advanceTimersByTime / runAllTimers / runOnlyPendingTimers
+ *   performance.now() (when available)
+ *
+ * Zero dependency on `@sinonjs/fake-timers` — we re-implement the queue.
+ */
+type TimerCallback = (...args: unknown[]) => void;
+interface Timer {
+    id: number;
+    dueMs: number;
+    intervalMs: number | null;
+    callback: TimerCallback;
+    args: unknown[];
+    kind: "timeout" | "interval" | "immediate";
+}
+export interface FakeTimerState {
+    now: number;
+    queue: Timer[];
+    nextId: number;
+    active: boolean;
+}
+interface OriginalTimerBag {
+    setTimeout: unknown;
+    clearTimeout: unknown;
+    setInterval: unknown;
+    clearInterval: unknown;
+    setImmediate: unknown;
+    clearImmediate: unknown;
+    performanceNow: unknown;
+}
+export type TimerGlobals = OriginalTimerBag;
+export declare function createFakeTimerController(): FakeTimerController;
+export interface FakeTimerController {
+    install(now: number): void;
+    uninstall(): void;
+    isActive(): boolean;
+    now(): number;
+    advanceBy(ms: number): void;
+    runAll(): void;
+    runOnlyPending(): void;
+    pending(): number;
+    clear(): void;
+}
+export {};
+//# sourceMappingURL=fake-timers.d.ts.map

package/dist/runtime/vi/fake-timers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fake-timers.d.ts","sourceRoot":"","sources":["../../../src/runtime/vi/fake-timers.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,KAAK,aAAa,GAAG,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;AAElD,UAAU,KAAK;IACd,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,QAAQ,EAAE,aAAa,CAAC;IACxB,IAAI,EAAE,OAAO,EAAE,CAAC;IAChB,IAAI,EAAE,SAAS,GAAG,UAAU,GAAG,WAAW,CAAC;CAC3C;AAED,MAAM,WAAW,cAAc;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,KAAK,EAAE,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;CAChB;AAED,UAAU,gBAAgB;IACzB,UAAU,EAAE,OAAO,CAAC;IACpB,YAAY,EAAE,OAAO,CAAC;IACtB,WAAW,EAAE,OAAO,CAAC;IACrB,aAAa,EAAE,OAAO,CAAC;IACvB,YAAY,EAAE,OAAO,CAAC;IACtB,cAAc,EAAE,OAAO,CAAC;IACxB,cAAc,EAAE,OAAO,CAAC;CACxB;AAsID,MAAM,MAAM,YAAY,GAAG,gBAAgB,CAAC;AA+F5C,wBAAgB,yBAAyB,IAAI,mBAAmB,CAkI/D;AAED,MAAM,WAAW,mBAAmB;IACnC,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,SAAS,IAAI,IAAI,CAAC;IAClB,QAAQ,IAAI,OAAO,CAAC;IACpB,GAAG,IAAI,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,MAAM,IAAI,IAAI,CAAC;IACf,cAAc,IAAI,IAAI,CAAC;IACvB,OAAO,IAAI,MAAM,CAAC;IAClB,KAAK,IAAI,IAAI,CAAC;CACd"}

package/dist/runtime/vi/fake-timers.js

@@ -0,0 +1,317 @@
+/**
+ * Fake-timer core — swaps the global timer APIs for a deterministic
+ * scheduler. Mirrors the subset of Vitest we need:
+ *   setTimeout / setInterval / setImmediate (+ clear*)
+ *   advanceTimersByTime / runAllTimers / runOnlyPendingTimers
+ *   performance.now() (when available)
+ *
+ * Zero dependency on `@sinonjs/fake-timers` — we re-implement the queue.
+ */
+import { getRealNow } from "./system-time.js";
+function getPerformance() {
+    const p = Reflect.get(globalThis, "performance");
+    if (p && typeof p === "object")
+        return p;
+    return undefined;
+}
+function captureGlobals() {
+    const perf = getPerformance();
+    return {
+        setTimeout: Reflect.get(globalThis, "setTimeout"),
+        clearTimeout: Reflect.get(globalThis, "clearTimeout"),
+        setInterval: Reflect.get(globalThis, "setInterval"),
+        clearInterval: Reflect.get(globalThis, "clearInterval"),
+        setImmediate: Reflect.get(globalThis, "setImmediate"),
+        clearImmediate: Reflect.get(globalThis, "clearImmediate"),
+        performanceNow: perf?.now?.bind(perf),
+    };
+}
+function installHandler(state) {
+    const originals = captureGlobals();
+    // Keep a reference to the real clearTimeout so we can fall back to it
+    // when a user passes a real `Timeout` handle that predates the install.
+    const realClearTimeout = typeof originals.clearTimeout === "function"
+        ? originals.clearTimeout
+        : undefined;
+    function scheduleTimeout(cb, ms, ...args) {
+        const ready = normaliseDelay(ms);
+        const timer = {
+            id: ++state.nextId,
+            dueMs: state.now + ready,
+            intervalMs: null,
+            callback: cb,
+            args,
+            kind: "timeout",
+        };
+        state.queue.push(timer);
+        return timer;
+    }
+    function scheduleInterval(cb, ms, ...args) {
+        const intervalMs = Math.max(1, normaliseDelay(ms, 1));
+        const timer = {
+            id: ++state.nextId,
+            dueMs: state.now + intervalMs,
+            intervalMs,
+            callback: cb,
+            args,
+            kind: "interval",
+        };
+        state.queue.push(timer);
+        return timer;
+    }
+    function scheduleImmediate(cb, ...args) {
+        const timer = {
+            id: ++state.nextId,
+            dueMs: state.now,
+            intervalMs: null,
+            callback: cb,
+            args,
+            kind: "immediate",
+        };
+        state.queue.push(timer);
+        return timer;
+    }
+    const clear = (idOrTimer) => {
+        if (idOrTimer == null)
+            return;
+        let id;
+        if (typeof idOrTimer === "number")
+            id = idOrTimer;
+        else if (typeof idOrTimer === "object") {
+            const maybe = idOrTimer.id;
+            if (typeof maybe === "number")
+                id = maybe;
+        }
+        if (id === undefined) {
+            // Not a Helix timer — likely a real `Timeout` handle from before
+            // fake timers were installed. Fall back to the real `clearTimeout`
+            // so it still gets cancelled.
+            realClearTimeout?.(idOrTimer);
+            return;
+        }
+        const idx = state.queue.findIndex((t) => t.id === id);
+        if (idx >= 0)
+            state.queue.splice(idx, 1);
+    };
+    Reflect.set(globalThis, "setTimeout", timerFacade(scheduleTimeout));
+    Reflect.set(globalThis, "setInterval", timerFacade(scheduleInterval));
+    Reflect.set(globalThis, "clearTimeout", clear);
+    Reflect.set(globalThis, "clearInterval", clear);
+    if (originals.setImmediate) {
+        Reflect.set(globalThis, "setImmediate", immediateFacade(scheduleImmediate));
+        Reflect.set(globalThis, "clearImmediate", clear);
+    }
+    // `performance.now()` tracks the fake clock when available.
+    const perf = getPerformance();
+    if (perf && typeof perf.now === "function") {
+        Reflect.set(perf, "now", () => state.now);
+    }
+    return originals;
+}
+function restoreHandler(originals) {
+    Reflect.set(globalThis, "setTimeout", originals.setTimeout);
+    Reflect.set(globalThis, "clearTimeout", originals.clearTimeout);
+    Reflect.set(globalThis, "setInterval", originals.setInterval);
+    Reflect.set(globalThis, "clearInterval", originals.clearInterval);
+    if (originals.setImmediate) {
+        Reflect.set(globalThis, "setImmediate", originals.setImmediate);
+    }
+    if (originals.clearImmediate) {
+        Reflect.set(globalThis, "clearImmediate", originals.clearImmediate);
+    }
+    const perf = getPerformance();
+    if (perf && typeof originals.performanceNow === "function") {
+        Reflect.set(perf, "now", originals.performanceNow);
+    }
+}
+/** Normalise the `ms` argument: NaN / undefined / negative → 0. */
+function normaliseDelay(ms, floor = 0) {
+    if (ms === undefined || Number.isNaN(ms) || !Number.isFinite(ms))
+        return floor;
+    return Math.max(floor, ms);
+}
+function timerFacade(schedule) {
+    return Object.assign((cb, ms, ...args) => {
+        return makeHandle(schedule(cb, ms, ...args));
+    }, { __promisify__: promisifyTimer });
+}
+function immediateFacade(schedule) {
+    return Object.assign((cb, ...args) => {
+        return makeHandle(schedule(cb, ...args));
+    }, { __promisify__: promisifyImmediate });
+}
+/**
+ * `util.promisify(setTimeout)(ms, value)` must honour the fake clock — the
+ * Promise resolves only when `advanceTimersByTime(ms)` is called, not on
+ * the next microtask.
+ */
+function promisifyTimer(ms, value) {
+    return new Promise((resolve) => {
+        globalThis.setTimeout(() => resolve(value), ms);
+    });
+}
+function promisifyImmediate(value) {
+    return new Promise((resolve) => {
+        const setI = Reflect.get(globalThis, "setImmediate");
+        if (typeof setI === "function") {
+            setI(() => resolve(value));
+        }
+        else {
+            // Browsers: fall back to setTimeout(0).
+            globalThis.setTimeout(() => resolve(value), 0);
+        }
+    });
+}
+/**
+ * Produce the object Node's `setTimeout` returns — enough for clear*()
+ * and ref/unref. `refresh` re-queues the timer starting from the current
+ * fake clock, matching Node's semantics.
+ */
+function makeHandle(timer) {
+    const noop = () => timer;
+    Object.defineProperties(timer, {
+        ref: { value: noop, configurable: true },
+        unref: { value: noop, configurable: true },
+        hasRef: { value: () => true, configurable: true },
+        refresh: {
+            value: () => {
+                // Node's refresh: if not yet fired, reset due time from "now".
+                // We don't have direct access to the queue here (closure), so
+                // the real refresh happens inside `advanceBy`/`runAll` when the
+                // caller manipulates the handle. For now return the handle.
+                return timer;
+            },
+            configurable: true,
+        },
+    });
+    return timer;
+}
+export function createFakeTimerController() {
+    let state;
+    let originals;
+    function install(now) {
+        if (state) {
+            // Re-installation updates the clock in place so tests that call
+            // `vi.useFakeTimers({ now: X })` twice get the new epoch. Vitest
+            // parity.
+            state.now = now;
+            return;
+        }
+        state = { now, queue: [], nextId: 0, active: true };
+        originals = installHandler(state);
+    }
+    function uninstall() {
+        if (!state)
+            return;
+        if (originals)
+            restoreHandler(originals);
+        state = undefined;
+        originals = undefined;
+    }
+    function requireState() {
+        if (!state) {
+            throw new Error("vi: fake timers not installed. Call vi.useFakeTimers() first.");
+        }
+        return state;
+    }
+    function drainUntil(target) {
+        const s = requireState();
+        // Bound iterations to catch `setImmediate(() => setImmediate(...))`
+        // infinite loops in `advanceTimersByTime(0)` / `runAll`.
+        let iterations = 0;
+        const MAX = 10_000;
+        while (true) {
+            if (++iterations > MAX) {
+                throw new Error(`vi: fake-timer drain exceeded ${MAX} iterations — likely a self-rescheduling immediate / interval. Use runOnlyPendingTimers or clearAllTimers.`);
+            }
+            let nextIdx = -1;
+            let nextDue = Number.POSITIVE_INFINITY;
+            for (let i = 0; i < s.queue.length; i += 1) {
+                const t = s.queue[i];
+                if (t.dueMs <= target && t.dueMs < nextDue) {
+                    nextDue = t.dueMs;
+                    nextIdx = i;
+                }
+            }
+            if (nextIdx < 0)
+                break;
+            const timer = s.queue[nextIdx];
+            s.queue.splice(nextIdx, 1);
+            s.now = Math.max(s.now, timer.dueMs);
+            if (timer.intervalMs !== null) {
+                s.queue.push({ ...timer, dueMs: timer.dueMs + timer.intervalMs });
+            }
+            // Advance clock to target BEFORE firing: if the callback throws,
+            // the wall clock has already been moved so subsequent drains see
+            // the state the user asked for.
+            const latestDue = timer.dueMs;
+            try {
+                timer.callback(...timer.args);
+            }
+            catch (err) {
+                // Set `now` to the target so callers can resume after catching.
+                if (s.now < target)
+                    s.now = target;
+                throw err;
+            }
+        }
+        if (s.now < target)
+            s.now = target;
+    }
+    return {
+        install,
+        uninstall,
+        isActive: () => state?.active === true,
+        now: () => state?.now ?? getRealNow(),
+        advanceBy(ms) {
+            if (ms < 0) {
+                throw new Error(`vi.advanceTimersByTime: negative delta (${ms}) is not supported`);
+            }
+            const s = requireState();
+            drainUntil(s.now + ms);
+        },
+        runAll() {
+            const s = requireState();
+            let iterations = 0;
+            while (s.queue.length > 0) {
+                iterations += 1;
+                if (iterations > 10_000) {
+                    throw new Error("vi.runAllTimers: exceeded 10 000 iterations — likely a self-rescheduling interval or immediate. Use runOnlyPendingTimers or advanceTimersByTime instead.");
+                }
+                let earliest = Number.POSITIVE_INFINITY;
+                for (const t of s.queue) {
+                    if (t.dueMs < earliest)
+                        earliest = t.dueMs;
+                }
+                if (!Number.isFinite(earliest))
+                    break;
+                drainUntil(earliest);
+            }
+        },
+        runOnlyPending() {
+            const s = requireState();
+            // Sort the snapshot by due time so callbacks fire in schedule order,
+            // not insertion order (Vitest parity).
+            const snapshot = [...s.queue].sort((a, b) => a.dueMs - b.dueMs);
+            for (const timer of snapshot) {
+                const idx = s.queue.indexOf(timer);
+                if (idx < 0)
+                    continue;
+                s.queue.splice(idx, 1);
+                s.now = Math.max(s.now, timer.dueMs);
+                if (timer.intervalMs !== null) {
+                    s.queue.push({ ...timer, dueMs: timer.dueMs + timer.intervalMs });
+                }
+                timer.callback(...timer.args);
+            }
+        },
+        pending() {
+            return state ? state.queue.length : 0;
+        },
+        clear() {
+            if (state)
+                state.queue.length = 0;
+        },
+    };
+}
+//# sourceMappingURL=fake-timers.js.map