@menapo/machine 0.0.0-stage → 0.1.0

package/dist/test.js

@@ -0,0 +1,262 @@
+import { r as fail } from "./dev-BAz6e3W-.js";
+import { t as Interpreter } from "./instance-BM2UqeXW.js";
+import { r as records } from "./records-7FFepzo9.js";
+import { n as values, t as inspect } from "./inspect-BmyLUhcy.js";
+//#region src/test/clock.ts
+/** A timer on a fake clock: what `setTimeout` returns while the clock stands in. */
+var Timer = class {
+	clock;
+	at;
+	fn;
+	args;
+	constructor(clock, at, fn, args) {
+		this.clock = clock;
+		this.at = at;
+		this.fn = fn;
+		this.args = args;
+	}
+};
+/** Timers fired by one `runAll()`, or by `advance()` without time passing, before it is taken for a loop. */
+const RUN_LIMIT = 1e3;
+var Clock = class {
+	now = 0;
+	/** Pending timers, in the order they were set. */
+	timers = [];
+	set(fn, ms, args) {
+		const timer = new Timer(this, this.now + Math.max(0, ms ?? 0), fn, args);
+		this.timers.push(timer);
+		return timer;
+	}
+	clear(timer) {
+		const at = this.timers.indexOf(timer);
+		if (at >= 0) this.timers.splice(at, 1);
+	}
+	/** The next timer due by `end`: the earliest, and of equal times the first set. */
+	due(end) {
+		let next;
+		for (const timer of this.timers) if (timer.at <= end && (!next || timer.at < next.at)) next = timer;
+		return next;
+	}
+	/** Fires `timer`, moving time to it. */
+	fire(timer) {
+		this.clear(timer);
+		this.now = timer.at;
+		run(this, () => timer.fn(...timer.args));
+	}
+	/**
+	* Fires the timers due within `ms`, in time order; false, with time left
+	* where it stopped, after {@link RUN_LIMIT} in a row at one instant: a
+	* timer that sets another with no delay never lets time reach the end.
+	*/
+	advance(ms) {
+		const end = this.now + ms;
+		for (let timer, n = 0; timer = this.due(end); this.fire(timer)) {
+			n = timer.at === this.now ? n + 1 : 0;
+			if (n === RUN_LIMIT) return false;
+		}
+		this.now = end;
+		return true;
+	}
+	/** Fires timers in time order, those they set too, until none is left; false after {@link RUN_LIMIT}. */
+	runAll() {
+		for (let n = 0; this.timers.length; n++) {
+			if (n === RUN_LIMIT) return false;
+			this.fire(this.due(Infinity));
+		}
+		return true;
+	}
+};
+/** The clock standing in, and the real functions it stands in for. */
+let active;
+let real;
+const fakeSet = (fn, ms, ...args) => active.set(fn, ms, args);
+const fakeClear = (id) => id instanceof Timer ? id.clock.clear(id) : real[1](id);
+/** Runs `fn` with `clock` standing in for `setTimeout` and `clearTimeout`. */
+function run(clock, fn) {
+	const outer = active;
+	if (!outer) {
+		real = [globalThis.setTimeout, globalThis.clearTimeout];
+		globalThis.setTimeout = fakeSet;
+		globalThis.clearTimeout = fakeClear;
+	}
+	active = clock;
+	try {
+		return fn();
+	} finally {
+		active = outer;
+		if (!outer) [globalThis.setTimeout, globalThis.clearTimeout] = real;
+	}
+}
+//#endregion
+//#region src/test/machine.ts
+/**
+* `testMachine` (PLAN §4.10): a started instance on a fake clock of its
+* own, with every event it takes recorded. It is the instance itself, so
+* everything `start` gives works unchanged; the test controls are added
+* by one subclass, which wraps the handling of events in its clock.
+*/
+/** `instance.b` once stopped (the interpreter's STOPPED). */
+const STOPPED = 2;
+/** In a played path: fire the next timer. */
+const AFTER$1 = "machine.after";
+var Tested = class extends Interpreter {
+	get pending() {
+		return this.clock?.timers.length ?? 0;
+	}
+	get steps() {
+		return this.log ??= [];
+	}
+	get path() {
+		const path = [];
+		for (const { state } of this.steps) if (path.at(-1) !== state) path.push(state);
+		return path;
+	}
+	go(rules, event) {
+		run(this.clock ??= new Clock(), () => super.go(rules, event));
+	}
+	stop() {
+		try {
+			run(this.clock ??= new Clock(), () => super.stop());
+		} finally {
+			if (this.counted) {
+				this.counted = false;
+				live--;
+				queueMicrotask(uninstall);
+			}
+		}
+	}
+	advance(ms) {
+		if (!(ms >= 0)) fail("BAD_DELAY", this.M.name, `advance(${ms}): give a number of milliseconds, 0 or more.`);
+		if (this.clock && !this.clock.advance(ms)) fail("TIMER_LOOP", this.M.name, `advance(${ms}) fired 1000 timers at ${this.clock.now} ms in "${this.s.path}" and more keep coming; give the timer that sets another a delay above 0, or stop it.`);
+	}
+	runAll() {
+		if (this.clock && !this.clock.runAll()) fail("TIMER_LOOP", this.M.name, `runAll() fired 1000 timers in "${this.s.path}" and more keep coming; move the clock with advance(ms) instead.`);
+	}
+	play(events) {
+		for (const event of events) if (event.type !== AFTER$1) this.dispatch(event);
+		else {
+			const next = this.clock?.due(Infinity);
+			if (!next) fail("NO_TIMER", this.M.name, `play() reached "${AFTER$1}" in "${this.s.path}" with no timer pending; the path was made for other start options.`);
+			this.clock.fire(next);
+		}
+	}
+};
+/**
+* The recorder of steps, watching while test machines run: every instance
+* pays for the core's hook while it is installed, so it goes once all of
+* them have stopped (on the next microtask, after the step that stopped
+* the last one is told).
+*/
+let recorder;
+/** Test machines started and not stopped. */
+let live = 0;
+function uninstall() {
+	if (!live) {
+		recorder?.();
+		recorder = void 0;
+	}
+}
+/**
+* Starts `machine` for a test: events run synchronously, timers wait for
+* `advance` or `runAll`, and every event taken is recorded in `steps` and
+* `path`.
+*/
+function testMachine(machine, options) {
+	recorder ??= inspect((step) => {
+		const instance = step.instance;
+		if (instance instanceof Tested) (instance.log ??= []).push(step);
+	});
+	const tested = new Tested(machine, options?.context, options?.props);
+	if (tested.b !== STOPPED) {
+		tested.counted = true;
+		live++;
+	} else queueMicrotask(uninstall);
+	return tested;
+}
+//#endregion
+//#region src/test/paths.ts
+/**
+* `paths()` (PLAN §4.10): the event paths through a machine, for tests
+* that cover every state and transition, as `@xstate/test` generates them.
+* Each path is found by running a test machine, so guards, context and
+* timers decide what is reachable exactly as in the app.
+*/
+const AFTER = { type: "machine.after" };
+/**
+* Every path from the initial state that passes no state twice, up to
+* `depth` events. A path ends when it reaches a final state, a state where
+* nothing it can send does anything, `depth`, or a state with context it
+* passed through before; the step back is part of the path, so every
+* transition taken is covered. Events are those the current state handles,
+* plus `machine.after` while a timer is pending. A state is its path and
+* its context and props, compared as JSON, and what its history states
+* recorded. In a parallel configuration the state is every active leaf, and
+* the events tried are those any active state handles.
+*/
+function paths(machine, options = {}) {
+	const { depth = 6, limit = 1e3, events: data = {}, context, props } = options;
+	const samples = data;
+	const tables = machine;
+	const found = [];
+	let unique = 0;
+	/** Notifications per instance played: one that heard no more than its prefix changed nothing. */
+	const told = /* @__PURE__ */ new WeakMap();
+	const play = (events) => {
+		const t = new Tested(tables, context, props);
+		told.set(t, 0);
+		t.subscribe(() => told.set(t, told.get(t) + 1));
+		t.play(events);
+		return t;
+	};
+	const key = (t) => {
+		try {
+			const history = [...records.get(t) ?? []].map(([h, s]) => [h.i, s.map((x) => x.i)]);
+			return t.s.path + "\0" + JSON.stringify(values(t)) + "\0" + JSON.stringify(history);
+		} catch {
+			return `\0${unique++}`;
+		}
+	};
+	const add = (path) => {
+		if (found.push(path) > limit) fail("PATH_LIMIT", tables.name, `paths() found more than ${limit} paths within depth ${depth}; lower \`depth\`, list fewer \`events\` data, or raise \`limit\`.`);
+	};
+	const walk = (t, events, states, seen) => {
+		let extended = false;
+		if (events.length < depth && !t.s.fi) {
+			const next = [];
+			for (const type of t.s.on.keys()) for (const payload of samples[type] ?? [void 0]) next.push({
+				type,
+				...payload
+			});
+			if (t.pending) next.push(AFTER);
+			for (const event of next) {
+				const u = play([...events, event]);
+				try {
+					if (told.get(u) === told.get(t)) continue;
+					extended = true;
+					const path = {
+						events: [...events, event],
+						states: [...states, u.state]
+					};
+					const k = key(u);
+					if (seen.has(k)) add(path);
+					else walk(u, path.events, path.states, new Set(seen).add(k));
+				} finally {
+					u.stop();
+				}
+			}
+		}
+		if (!extended) add({
+			events,
+			states
+		});
+	};
+	const first = play([]);
+	try {
+		walk(first, [], [first.state], /* @__PURE__ */ new Set([key(first)]));
+	} finally {
+		first.stop();
+	}
+	return found;
+}
+//#endregion
+export { paths, testMachine };