@moku-labs/game 0.0.1 → 0.0.2

package/dist/testing.mjs

@@ -1,4 +1,5 @@
-import { a as graphHash, l as memory, u as saveOf } from "./registry-DWV5C0Mf.mjs";
+import { n as saveOf, t as memory } from "./memory-CvgdnsQO.mjs";
+import { i as stepFrames, r as runRepro, t as createHeadless } from "./headless-CvamCUcR.mjs";
 //#region src/plugins/clock/fake.ts
 /**
 * Removes and returns the timer that is due first, up to and including `until`.
@@ -7,10 +8,6 @@ import { a as graphHash, l as memory, u as saveOf } from "./registry-DWV5C0Mf.mj
 * @param state - Innards of the fake clock.
 * @param until - Latest moment that counts as due.
 * @returns The timer to fire, or `undefined` when nothing is due.
-* @example
-* ```ts
-* const due = takeDue(state, 1500);
-* ```
 */
 function takeDue(state, until) {
 	let earliest;
@@ -29,10 +26,6 @@ function takeDue(state, until) {
 *
 * @param state - Innards of the fake clock.
 * @param until - Moment to stop at.
-* @example
-* ```ts
-* runDue(state, state.now + 5000);
-* ```
 */
 function runDue(state, until) {
 	let due = takeDue(state, until);
@@ -44,14 +37,22 @@ function runDue(state, until) {
 	state.now = Math.max(state.now, until);
 }
 /**
-* Creates a fake source for tests. Timers fire synchronously inside `advance`, in due order.
+* Creates a fake source for tests. Timers fire synchronously inside `advance`, in due order. A
+* negative delay counts as zero and an unknown handle is ignored.
 *
 * @param start - Starting moment in epoch milliseconds. Defaults to 0.
 * @returns A clock source with the test-only controls `advance` and `set`.
 * @example
 * ```ts
+* // An energy point refills 60 s after it was spent. The test moves the clock, not the minute.
 * const clock = fakeClock(1000);
-* clock.advance(5000);
+* const app = createApp({ pluginConfigs: { clock: { source: clock } } });
+* const seen: number[] = [];
+*
+* app.clock.onElapsed(({ now }) => seen.push(now));
+* app.clock.scheduleAt(61_000);
+* clock.advance(60_000); // the timer fires inside advance, nothing waits
+* seen; // [61000]
 * ```
 */
 function fakeClock(start = 0) {
@@ -61,27 +62,7 @@ function fakeClock(start = 0) {
 		timers: []
 	};
 	return {
-		/**
-		* Reads the fake moment.
-		*
-		* @returns The current moment in epoch milliseconds.
-		* @example
-		* ```ts
-		* const moment = clock.now();
-		* ```
-		*/
 		now: () => state.now,
-		/**
-		* Schedules one callback. A negative delay counts as zero.
-		*
-		* @param callback - Function to run when the delay has passed.
-		* @param delayMs - Delay in milliseconds.
-		* @returns The handle to give back to `clearTimer`.
-		* @example
-		* ```ts
-		* const handle = clock.setTimer(fire, 1000);
-		* ```
-		*/
 		setTimer: (callback, delayMs) => {
 			const id = state.nextId;
 			state.nextId += 1;
@@ -92,275 +73,17 @@ function fakeClock(start = 0) {
 			});
 			return id;
 		},
-		/**
-		* Cancels a pending timer. An unknown handle is ignored.
-		*
-		* @param handle - Handle returned by `setTimer`.
-		* @example
-		* ```ts
-		* clock.clearTimer(handle);
-		* ```
-		*/
 		clearTimer: (handle) => {
 			if (typeof handle !== "number") return;
 			state.timers = state.timers.filter((timer) => timer.id !== handle);
 		},
-		/**
-		* Moves the clock forward and fires every timer that falls due, in due order.
-		* A negative amount moves nothing.
-		*
-		* @param ms - Milliseconds to move forward.
-		* @example
-		* ```ts
-		* clock.advance(60_000);
-		* ```
-		*/
 		advance: (ms) => {
 			runDue(state, state.now + Math.max(0, ms));
 		},
-		/**
-		* Jumps the clock to a moment without firing any timer. Moving back is allowed: that is a
-		* device clock set by hand.
-		*
-		* @param moment - Moment in epoch milliseconds.
-		* @example
-		* ```ts
-		* clock.set(400);
-		* ```
-		*/
 		set: (moment) => {
 			state.now = moment;
 		}
 	};
 }
 //#endregion
-//#region src/plugins/flow/headless.ts
-const noPayload = null;
-/** Seed of a repro that pins no rng state, the seed `saveOf` writes. */
-const defaultSeed = 1;
-/**
-* Turns whatever `run()` rejected with into an error that can be thrown again.
-*
-* @param value - The rejection value.
-* @returns The value itself when it is an error, a wrapped one otherwise.
-* @example
-* ```ts
-* throw asError(fatal.error);
-* ```
-*/
-function asError(value) {
-	if (value instanceof Error) return value;
-	return /* @__PURE__ */ new Error(`[game] The headless run failed.\n  ${String(value)}.`);
-}
-/**
-* Starts the one loop unless the app's own `onStart` already did, and keeps a fatal error until
-* someone asks for it. `run()` rejects only on a fatal error, and nobody awaits it here.
-*
-* @param app - The started app.
-* @returns The holder of the fatal error.
-* @example
-* ```ts
-* const fatal = startLoop(app);
-* ```
-*/
-function startLoop(app) {
-	const fatal = { error: void 0 };
-	if (app.flow.state().running) return fatal;
-	app.flow.run().catch((error) => {
-		fatal.error = error;
-	});
-	return fatal;
-}
-/**
-* Waits until the loop rests for the first time, or ends. An empty route walks nowhere: it only
-* waits for the gate the loop opens at the node it enters, so a start that is a chain of transit
-* nodes is played out before anything reads the game.
-*
-* @param app - The started app whose loop is running.
-* @param fatal - Holder of the fatal error of `run()`.
-* @returns Resolves once the loop rests at its first rest node.
-* @throws {Error} When the loop failed fatally instead of reaching a rest node.
-* @example
-* ```ts
-* await settleAtFirstRest(app, fatal);
-* ```
-*/
-async function settleAtFirstRest(app, fatal) {
-	await app.flow.walk([]).catch((error) => {
-		throw asError(fatal.error ?? error);
-	});
-	if (fatal.error !== void 0) throw asError(fatal.error);
-}
-/**
-* Starts an app headless: sets flow mode `"fast"`, awaits `app.start()`, starts `flow.run()`
-* unless the app's own `onStart` already did, and waits until the loop rests for the first time.
-* `game.state().path` therefore names the first rest node of the graph as soon as the call
-* resolves. A fatal error of the loop rejects this call, and a later one is re-thrown by `walk`
-* and by `stop`, so a headless test never loses it.
-*
-* @param app - An app that is not started yet.
-* @returns The game: walk it, answer it, read it, stop it.
-* @throws {Error} When the loop failed fatally before it reached its first rest node.
-* @example
-* ```ts
-* const game = await createHeadless(app);
-* expect(game.state().path).toBe("home");
-* await game.walk([{ at: "board/awaitIntent", intent: "merge", payload: { from: "c2", to: "c3" } }]);
-* await game.stop();
-* ```
-*/
-async function createHeadless(app) {
-	app.flow.setMode("fast");
-	await app.start();
-	const fatal = startLoop(app);
-	await settleAtFirstRest(app, fatal);
-	return {
-		/**
-		* Walks a route through the running loop.
-		*
-		* @param route - The player's answers and substituted sub-flow results, in order.
-		* @returns The state the walk ended in.
-		* @throws {Error} When a step is never reached, or the loop failed fatally.
-		* @example
-		* ```ts
-		* await game.walk([{ at: "home", intent: "play" }]);
-		* ```
-		*/
-		walk: async (route) => {
-			const state = await app.flow.walk(route).catch((error) => {
-				throw asError(fatal.error ?? error);
-			});
-			if (fatal.error !== void 0) throw asError(fatal.error);
-			return state;
-		},
-		/**
-		* Gives one answer to the gate, the way a tap does.
-		*
-		* @param answer - Intent and optional payload.
-		* @returns Whether the gate took it.
-		* @example
-		* ```ts
-		* game.answer({ intent: "play" });
-		* ```
-		*/
-		answer: (answer) => app.flow.gate.answer(answer),
-		/**
-		* Reads where the graph stands.
-		*
-		* @returns Whether it runs, the path, the stack, what it waits for and the mode.
-		* @example
-		* ```ts
-		* expect(game.state().path).toBe("home");
-		* ```
-		*/
-		state: () => app.flow.state(),
-		/**
-		* Reads the edges taken since the last checkpoint.
-		*
-		* @returns A copy of the journal.
-		* @example
-		* ```ts
-		* const [last] = game.history().slice(-1);
-		* ```
-		*/
-		history: () => app.flow.history(),
-		/**
-		* Stops the app, then re-throws a fatal error of the loop.
-		*
-		* @throws {Error} When the loop failed fatally.
-		* @example
-		* ```ts
-		* await game.stop();
-		* ```
-		*/
-		stop: async () => {
-			await app.stop();
-			if (fatal.error !== void 0) throw asError(fatal.error);
-		}
-	};
-}
-/**
-* Reads the rest node a repro starts at: its checkpoint, or the start of the main flow.
-*
-* @param app - The started app.
-* @param repro - Starting state, optional checkpoint and the route.
-* @returns The path of the node the repro enters.
-* @throws {Error} When the graph has no main flow to start from.
-* @example
-* ```ts
-* const path = reproPath(app, repro);
-* ```
-*/
-function reproPath(app, repro) {
-	if (repro.checkpoint !== void 0) return repro.checkpoint;
-	const graph = app.flow.describe();
-	const start = graph.flows[graph.main]?.start;
-	if (start === void 0) throw new Error(`[game] runRepro() found no flow "${graph.main}" to start from.\n  Name the checkpoint the repro was taken at.`);
-	return start;
-}
-/**
-* Builds the bookmark a repro is entered with: its state, its checkpoint and the hash of the
-* graph that runs now, so a checkpoint is accepted and any other rest node is checked.
-*
-* @param app - The started app.
-* @param repro - Starting state, optional checkpoint and the route.
-* @returns The bookmark to restore.
-* @example
-* ```ts
-* const bookmark = reproBookmark(app, repro);
-* ```
-*/
-function reproBookmark(app, repro) {
-	return {
-		path: reproPath(app, repro),
-		input: noPayload,
-		player: repro.player,
-		session: repro.session ?? {},
-		rng: repro.rng ?? {
-			seed: defaultSeed,
-			streams: {}
-		},
-		graph: graphHash(app.flow.describe())
-	};
-}
-/**
-* Plays a repro: starts the app headless, restores the bookmark built from its state and
-* checkpoint, then walks its route. The app keeps running, so the caller can read more than the
-* result and stops it itself.
-*
-* @param app - An app that is not started yet.
-* @param repro - Starting state, optional checkpoint and the route.
-* @returns The path the run ended at, and the committed state.
-* @example
-* ```ts
-* const result = await runRepro(app, { player: saved, checkpoint: "home", route });
-* ```
-*/
-async function runRepro(app, repro) {
-	const game = await createHeadless(app);
-	await app.flow.restore(reproBookmark(app, repro));
-	const state = await game.walk(repro.route);
-	const ended = app.flow.bookmark();
-	return {
-		path: state.stack.map((frame) => frame.node),
-		player: ended.player,
-		session: ended.session
-	};
-}
-/**
-* Steps the frame loop by hand: `count` calls of `app.time.step(deltaMs)`. A headless game has no
-* frame source, so this is the only thing that moves the frame phases.
-*
-* @param app - A started app.
-* @param count - Number of frames.
-* @param deltaMs - Milliseconds per frame.
-* @example
-* ```ts
-* stepFrames(app, 60, 16);
-* ```
-*/
-function stepFrames(app, count, deltaMs) {
-	for (let frame = 0; frame < count; frame += 1) app.time.step(deltaMs);
-}
-//#endregion
 export { createHeadless, fakeClock, memory, runRepro, saveOf, stepFrames };