@c9up/helix 0.1.4 → 0.1.5

package/src/runtime/vi/spy.ts

@@ -1,224 +0,0 @@
-/**
- * Spy core — a callable function that records every call and exposes a
- * Vitest-shape `.mock` surface. Wears the `__helixIsSpy` brand so the
- * matchers in `matchers.ts` (`toHaveBeenCalled*`) recognise it.
- */
-
-export interface MockCallResult<Return = unknown> {
-	/** `"incomplete"` is pushed synchronously at call entry and patched when the call resolves — matches Vitest so `mock.results.length === mock.calls.length` even for in-flight async. */
-	type: "return" | "throw" | "incomplete";
-	value: Return;
-}
-
-export interface MockInternals<
-	Args extends readonly unknown[] = readonly unknown[],
-	Return = unknown,
-> {
-	calls: Args[];
-	results: MockCallResult<Return>[];
-	/** The most recent call's arguments. Mirrors Vitest. */
-	lastCall: Args | undefined;
-}
-
-export type AnyFn = (...args: unknown[]) => unknown;
-
-type CallSignature<Fn extends AnyFn> = (
-	...args: Parameters<Fn>
-) => ReturnType<Fn>;
-
-interface SpyMethods<Fn extends AnyFn> {
-	readonly __helixIsSpy: true;
-	readonly mock: MockInternals<Parameters<Fn>, ReturnType<Fn>>;
-	readonly calls: Parameters<Fn>[];
-	readonly callCount: number;
-
-	mockImplementation(fn: Impl<Fn>): Spy<Fn>;
-	mockImplementationOnce(fn: Impl<Fn>): Spy<Fn>;
-	mockReturnValue(value: ReturnType<Fn>): Spy<Fn>;
-	mockReturnValueOnce(value: ReturnType<Fn>): Spy<Fn>;
-	mockResolvedValue(value: Awaited<ReturnType<Fn>>): Spy<Fn>;
-	mockResolvedValueOnce(value: Awaited<ReturnType<Fn>>): Spy<Fn>;
-	mockRejectedValue(reason: unknown): Spy<Fn>;
-	mockRejectedValueOnce(reason: unknown): Spy<Fn>;
-	mockClear(): Spy<Fn>;
-	mockReset(): Spy<Fn>;
-	mockRestore(): Spy<Fn>;
-
-	/** Internal: spyOn installs a restore callback here. Undefined for `vi.fn`. */
-	__setRestore(fn: () => void): void;
-	/** Internal: true iff `__setRestore` was called (= created by spyOn). */
-	readonly __isSpyOn: boolean;
-}
-
-export type Spy<Fn extends AnyFn = AnyFn> = CallSignature<Fn> & SpyMethods<Fn>;
-
-type Impl<Fn extends AnyFn> = (...args: Parameters<Fn>) => ReturnType<Fn>;
-
-export interface CreateSpyOptions<Fn extends AnyFn> {
-	name?: string;
-	defaultImplementation?: Fn;
-}
-
-/**
- * Factory used by `vi.fn` and `vi.spyOn`. The returned function is both
- * callable (executing the current implementation) and an object carrying
- * `.mock`, the Helix brand, and the `mockFoo()` mutators.
- */
-export function createSpy<Fn extends AnyFn = AnyFn>(
-	options: CreateSpyOptions<Fn> = {},
-): Spy<Fn> {
-	const onceQueue: Array<Impl<Fn> | Fn> = [];
-	let currentImpl: Fn | Impl<Fn> | undefined = options.defaultImplementation;
-	let restoreFn: (() => void) | undefined;
-
-	const mock: MockInternals<Parameters<Fn>, ReturnType<Fn>> = {
-		calls: [],
-		results: [],
-		lastCall: undefined,
-	};
-
-	const call: CallSignature<Fn> = function (
-		this: unknown,
-		...args: Parameters<Fn>
-	): ReturnType<Fn> {
-		mock.calls.push(args);
-		mock.lastCall = args;
-		// Push an incomplete result synchronously so `mock.results.length`
-		// always matches `mock.calls.length` (Vitest parity).
-		const result: MockCallResult<ReturnType<Fn>> = {
-			type: "incomplete",
-			value: undefined as ReturnType<Fn>,
-		};
-		mock.results.push(result);
-		const impl = onceQueue.shift() ?? currentImpl;
-		if (!impl) {
-			result.type = "return";
-			return undefined as ReturnType<Fn>;
-		}
-		try {
-			const value: ReturnType<Fn> = (impl as Impl<Fn>).apply(this, args);
-			result.type = "return";
-			result.value = value;
-			return value;
-		} catch (err) {
-			result.type = "throw";
-			result.value = err as ReturnType<Fn>;
-			throw err;
-		}
-	};
-
-	// `calls` and `callCount` must be LIVE accessors. Defining them in an
-	// object literal and passing through `Object.assign` would snapshot the
-	// getter's current value (Object.assign invokes [[Get]] on the source).
-	const methods: Omit<SpyMethods<Fn>, "calls" | "callCount" | "__isSpyOn"> = {
-		__helixIsSpy: true,
-		mock,
-		mockImplementation(fn) {
-			currentImpl = fn;
-			return spy;
-		},
-		mockImplementationOnce(fn) {
-			onceQueue.push(fn);
-			return spy;
-		},
-		mockReturnValue(value) {
-			currentImpl = () => value;
-			return spy;
-		},
-		mockReturnValueOnce(value) {
-			onceQueue.push(() => value);
-			return spy;
-		},
-		mockResolvedValue(value) {
-			currentImpl = () => Promise.resolve(value) as ReturnType<Fn>;
-			return spy;
-		},
-		mockResolvedValueOnce(value) {
-			onceQueue.push(() => Promise.resolve(value) as ReturnType<Fn>);
-			return spy;
-		},
-		mockRejectedValue(reason) {
-			currentImpl = () => Promise.reject(reason) as ReturnType<Fn>;
-			return spy;
-		},
-		mockRejectedValueOnce(reason) {
-			onceQueue.push(() => Promise.reject(reason) as ReturnType<Fn>);
-			return spy;
-		},
-		mockClear() {
-			mock.calls.length = 0;
-			mock.results.length = 0;
-			mock.lastCall = undefined;
-			return spy;
-		},
-		mockReset() {
-			spy.mockClear();
-			onceQueue.length = 0;
-			// On a `vi.fn` (no `restoreFn`) Vitest clears the implementation
-			// entirely. On a `spyOn` spy, restoring to the call-through
-			// `defaultImplementation` is the right behaviour.
-			currentImpl = restoreFn ? options.defaultImplementation : undefined;
-			return spy;
-		},
-		mockRestore() {
-			// Atomic order: swap `restoreFn` out of the closure BEFORE calling
-			// it, so a re-entrant `mockRestore` during the user's restore hook
-			// doesn't double-fire. If the hook throws, the spy is considered
-			// restored (best we can do) and the error propagates.
-			const hook = restoreFn;
-			restoreFn = undefined;
-			spy.mockReset();
-			hook?.();
-			return spy;
-		},
-		__setRestore(fn) {
-			restoreFn = fn;
-			isSpyOn = true;
-		},
-	};
-
-	// Sticky flag: once a spy is created via spyOn (`__setRestore` called),
-	// it stays "spyOn-flavoured" even after `mockRestore()` clears
-	// `restoreFn`. This matters for `restoreAllMocks` which must distinguish
-	// pass-through spies from bare `vi.fn` spies independently of their
-	// restoration state.
-	let isSpyOn = false;
-
-	const withMethods = Object.assign(call, methods);
-	Object.defineProperties(withMethods, {
-		calls: {
-			configurable: true,
-			enumerable: false,
-			get() {
-				return mock.calls;
-			},
-		},
-		callCount: {
-			configurable: true,
-			enumerable: false,
-			get() {
-				return mock.calls.length;
-			},
-		},
-		__isSpyOn: {
-			configurable: true,
-			enumerable: false,
-			get() {
-				return isSpyOn;
-			},
-		},
-	});
-	const spy = withMethods as Spy<Fn>;
-	Object.defineProperty(spy, "name", {
-		value: options.name ?? "spy",
-		configurable: true,
-	});
-	return spy;
-}
-
-export function isSpy(value: unknown): value is Spy {
-	if (!value || (typeof value !== "function" && typeof value !== "object")) {
-		return false;
-	}
-	return (value as { __helixIsSpy?: unknown }).__helixIsSpy === true;
-}

package/src/runtime/vi/spyOn.ts

@@ -1,155 +0,0 @@
-/**
- * `vi.spyOn(obj, key)` — replaces `obj[key]` with a spy that calls through
- * to the original. `spy.mockRestore()` puts the original back.
- *
- * Supports:
- *   - data properties whose value is a function (most methods);
- *   - accessor properties (`get` / `set`);
- *   - methods inherited via the prototype chain (the spy is installed as an
- *     own property on the target, and `mockRestore()` deletes the own
- *     property so inheritance resumes).
- *
- * `this` binding: the spy's default implementation uses a `function` form
- * (not arrow) so the caller's receiver is forwarded to the original. This
- * is essential when spying on a prototype method that depends on `this`.
- *
- * Double-spy detection: throws if the property is already a Helix spy, to
- * avoid the subtle double-counting bug where the inner spy's `calls` is
- * incremented by pass-through from the outer one.
- */
-
-import { type AnyFn, createSpy, isSpy, type Spy } from "./spy.js";
-
-type AccessorKind = "get" | "set";
-
-export interface SpyOnOptions {
-	/** For accessor properties, which side to spy on. Default: `"get"`. */
-	accessor?: AccessorKind;
-}
-
-function findDescriptor(
-	obj: object,
-	key: PropertyKey,
-): { descriptor: PropertyDescriptor; onPrototype: boolean } {
-	let cursor: object | null = obj;
-	while (cursor !== null) {
-		const desc = Object.getOwnPropertyDescriptor(cursor, key);
-		if (desc) {
-			return { descriptor: desc, onPrototype: cursor !== obj };
-		}
-		cursor = Object.getPrototypeOf(cursor);
-	}
-	throw new Error(
-		`vi.spyOn: property "${String(key)}" does not exist on the target`,
-	);
-}
-
-function buildRestore(
-	obj: object,
-	key: PropertyKey,
-	ownDescBefore: PropertyDescriptor | undefined,
-	onPrototype: boolean,
-): () => void {
-	return () => {
-		if (onPrototype && !ownDescBefore) {
-			Reflect.deleteProperty(obj, key);
-			return;
-		}
-		if (ownDescBefore) {
-			Object.defineProperty(obj, key, ownDescBefore);
-		}
-	};
-}
-
-export function spyOn<Obj extends object, Key extends keyof Obj>(
-	obj: Obj,
-	key: Key,
-	options: SpyOnOptions = {},
-): Spy {
-	const label = String(key);
-	const { descriptor, onPrototype } = findDescriptor(obj, key);
-	const ownDescBefore = Object.getOwnPropertyDescriptor(obj, key);
-
-	// Double-spy guard: refuse to spy on an already-spied value.
-	if (descriptor.value !== undefined && isSpy(descriptor.value)) {
-		throw new Error(
-			`vi.spyOn: "${label}" is already a spy. Call mockRestore() before spying again.`,
-		);
-	}
-
-	const restore = buildRestore(obj, key, ownDescBefore, onPrototype);
-
-	if (descriptor.get || descriptor.set) {
-		const kind: AccessorKind = options.accessor ?? "get";
-		const originalGet = descriptor.get;
-		const originalSet = descriptor.set;
-		if (kind === "get") {
-			if (!originalGet) {
-				throw new Error(
-					`vi.spyOn: "${label}" has no getter (pass { accessor: "set" } to spy on the setter)`,
-				);
-			}
-			// Use `function` so the shim + spy forward the caller's `this`.
-			const spy = createSpy({
-				name: label,
-				defaultImplementation: function (this: unknown) {
-					return originalGet.call(this);
-				},
-			});
-			Object.defineProperty(obj, key, {
-				configurable: true,
-				enumerable: descriptor.enumerable ?? true,
-				get(this: unknown): unknown {
-					return spy.call(this);
-				},
-				set: originalSet,
-			});
-			spy.__setRestore(restore);
-			return spy;
-		}
-		if (!originalSet) {
-			throw new Error(`vi.spyOn: "${label}" has no setter`);
-		}
-		const spy = createSpy<(v: unknown) => void>({
-			name: label,
-			defaultImplementation: function (this: unknown, v: unknown) {
-				originalSet.call(this, v);
-			},
-		});
-		Object.defineProperty(obj, key, {
-			configurable: true,
-			enumerable: descriptor.enumerable ?? true,
-			get: originalGet,
-			set(this: unknown, v: unknown) {
-				spy.call(this, v);
-			},
-		});
-		spy.__setRestore(restore);
-		return spy;
-	}
-
-	const originalValue = descriptor.value;
-	if (typeof originalValue !== "function") {
-		throw new Error(
-			`vi.spyOn: "${label}" is not a function (got ${typeof originalValue}). Pass { accessor } for accessors.`,
-		);
-	}
-	const originalFn = originalValue as AnyFn;
-	const spy = createSpy({
-		name: label,
-		defaultImplementation: function (this: unknown, ...args: unknown[]) {
-			// `this` is the call-site receiver (e.g. the class instance); the
-			// original method is forwarded its real receiver. Fixes the bug
-			// where `spyOn(Proto, 'method')` used to hard-bind `this = Proto`.
-			return originalFn.apply(this, args);
-		},
-	});
-	Object.defineProperty(obj, key, {
-		configurable: true,
-		enumerable: descriptor.enumerable ?? true,
-		writable: descriptor.writable ?? true,
-		value: spy,
-	});
-	spy.__setRestore(restore);
-	return spy;
-}

package/src/runtime/vi/system-time.ts

@@ -1,121 +0,0 @@
-/**
- * System-time control — pins `Date.now()` and `new Date()` to a fake
- * epoch. Each `ViContext` owns its own `SystemClock` instance; the Date
- * shim read-through to `context.fakeEpoch`, so concurrent test files
- * never share wall-clock state (AC 6 isolation).
- *
- * The shim is installed globally on first activation across ANY context
- * (Date is a singleton per realm), but the shim ALWAYS reads from the
- * currently-active context via the `readContext` resolver passed in. When
- * all contexts deactivate, the shim uninstalls.
- */
-
-const OriginalDate = globalThis.Date;
-const originalNow = OriginalDate.now.bind(OriginalDate);
-
-export interface SystemClock {
-	/** Fake epoch in ms, or `null` if this context is on real time. */
-	fakeEpoch: number | null;
-}
-
-export function createSystemClock(): SystemClock {
-	return { fakeEpoch: null };
-}
-
-/**
- * Register one context's interest in the Date shim. Returns an
- * unregister function.
- */
-type ContextResolver = () => SystemClock | undefined;
-
-const resolvers = new Set<ContextResolver>();
-let installed = false;
-
-function resolveEpoch(): number | null {
-	for (const resolve of resolvers) {
-		const ctx = resolve();
-		if (ctx?.fakeEpoch !== null && ctx?.fakeEpoch !== undefined) {
-			return ctx.fakeEpoch;
-		}
-	}
-	return null;
-}
-
-export function registerSystemClockContext(
-	resolver: ContextResolver,
-): () => void {
-	resolvers.add(resolver);
-	install();
-	return () => {
-		resolvers.delete(resolver);
-		if (resolvers.size === 0) restore();
-	};
-}
-
-export function setFakeEpoch(clock: SystemClock, time: Date | number): void {
-	let epoch: number;
-	if (time instanceof OriginalDate) {
-		epoch = time.getTime();
-	} else if (typeof time === "number") {
-		epoch = time;
-	} else {
-		throw new Error(
-			`vi.setSystemTime: expected Date or number, got ${typeof time}`,
-		);
-	}
-	if (!Number.isFinite(epoch)) {
-		throw new Error(`vi.setSystemTime: expected a finite epoch, got ${epoch}`);
-	}
-	clock.fakeEpoch = epoch;
-}
-
-export function clearFakeEpoch(clock: SystemClock): void {
-	clock.fakeEpoch = null;
-}
-
-function buildShim(): object {
-	const shim = function DateShim(this: unknown, ...args: unknown[]): unknown {
-		const epoch = resolveEpoch();
-		// Called without `new`: return a toString of the pinned (or real) time.
-		if (!new.target) {
-			return epoch !== null
-				? new OriginalDate(epoch).toString()
-				: new OriginalDate().toString();
-		}
-		if (args.length === 0 && epoch !== null) {
-			return new OriginalDate(epoch);
-		}
-		return Reflect.construct(OriginalDate, args);
-	};
-	shim.prototype = OriginalDate.prototype;
-	Object.defineProperty(shim, "name", { value: "Date", configurable: true });
-	Reflect.set(shim, "now", () => {
-		const epoch = resolveEpoch();
-		return epoch !== null ? epoch : originalNow();
-	});
-	Reflect.set(shim, "parse", OriginalDate.parse.bind(OriginalDate));
-	Reflect.set(shim, "UTC", OriginalDate.UTC.bind(OriginalDate));
-	return shim;
-}
-
-function install(): void {
-	if (installed) return;
-	installed = true;
-	Reflect.set(globalThis, "Date", buildShim());
-}
-
-function restore(): void {
-	if (!installed) return;
-	installed = false;
-	Reflect.set(globalThis, "Date", OriginalDate);
-}
-
-/** Get the original `Date.now` even after the shim is installed. */
-export function getRealNow(): number {
-	return originalNow();
-}
-
-/** Get the original `Date` constructor. */
-export function getRealDate(): DateConstructor {
-	return OriginalDate;
-}