@moku-labs/game 0.8.0 → 0.10.0

package/dist/testing.d.mts

@@ -1,5 +1,8 @@
-import { G as SaveDoc, R as Json, U as PlayerStateProvider, W as ProviderCall, at as FakeClock } from "./types-ERb2Y9U5.mjs";
-import { a as createHeadless, i as ReproResult, n as HeadlessGame, o as runRepro, r as Repro, s as stepFrames, t as HeadlessApp } from "./headless-q98SwADR.mjs";
+import { Dt as AnyFlow, Ht as ClockSource, Nt as NodeTable, Wt as FakeClock, Xt as Json, ht as FeaturePlugin } from "./types-ZQLYXo5X.mjs";
+import { t as createApp } from "./index-xxSxKJJW.mjs";
+import { n as saveOf, t as memory } from "./memory-DwDhfFWK.mjs";
+import { a as createHeadless, i as ReproResult, n as HeadlessGame, o as runRepro, r as Repro, s as stepFrames, t as HeadlessApp } from "./headless-G4nuZ-xz.mjs";
+import { AnyPluginInstance } from "@moku-labs/core";
 
 //#region src/plugins/clock/fake.d.ts
 /**
@@ -23,51 +26,129 @@ import { a as createHeadless, i as ReproResult, n as HeadlessGame, o as runRepro
  */
 declare function fakeClock(start?: number): FakeClock;
 //#endregion
-//#region src/plugins/model/store/providers/memory.d.ts
+//#region src/testing/isolate.d.ts
 /**
- * Creates an in-memory provider that keeps what it was committed and records every call.
- * It is the default when a game configures no `playerProvider`, and the double every test uses:
- * `provider.calls` is the whole persistence protocol of one run, in order. The document lives as
- * long as the provider does, so a second app over the same instance reads what the first one
- * wrote, and nothing survives the process.
+ * A stub for one node or sub-flow of the isolated flow: the outcome it ends with, and its payload.
  *
- * `load()` reads the fixture, or everything committed since; without either, the player is new.
- * `commitDurable()` resolves at once: there is no disk behind it.
+ * @example
+ * ```ts
+ * const closed: Stub<"closed"> = stub("closed"); // { kind: "stub", outcome: "closed" }
+ * ```
+ */
+type Stub<Name extends string = string> = {
+  readonly kind: "stub";
+  readonly outcome: Name;
+  readonly payload?: Json;
+};
+/**
+ * The outcome names of one entry of a node table. Distributes over a union: for a flow widened
+ * to `Flow.AnyFlow` an entry is a node, a sub-flow or a slot, and every outcome name is allowed,
+ * not only the slot's `done`.
+ */
+type OutcomeNameOf<Entry> = Entry extends {
+  readonly outcomes: infer Tags;
+} ? keyof Tags & string : never;
+/**
+ * One optional stub per node of the flow. The outcome must be one the replaced entry declares:
+ * a wrong one and an unknown key are compile errors, and `isolate()` refuses them at run time too.
+ * A flow widened to `Flow.AnyFlow` takes every key and every outcome.
+ *
+ * @example
+ * ```ts
+ * // boardFlow holds settings: settingsFlow (outcome closed) and energy (outcomes watch, later).
+ * const stubs: StubsOf<typeof boardFlow.nodes> = { settings: stub("closed"), energy: stub("later") };
+ * ```
+ */
+type StubsOf<Nodes extends NodeTable> = { readonly [Name in keyof Nodes & string]?: Stub<OutcomeNameOf<Nodes[Name]>> };
+/**
+ * What `isolate` composes around one feature.
  *
- * @param fixture - The save `load()` starts from. Omitted: a new player.
- * @param fixture.state - The saved document.
- * @param fixture.version - Schema version of the saved document.
- * @returns A provider that keeps its document and records its calls.
  * @example
  * ```ts
- * // A new player is saved at once. One roll reaches the provider at the next rest node.
- * const provider = memory();
- * const game = await createHeadless(createGame(provider));
+ * const options: IsolateOptions<typeof boardFlow.nodes> = {
+ *   flow: boardFlow, shared: sharedLayer, stubs: { settings: stub("closed") }, player: fresh
+ * };
+ * ```
+ */
+type IsolateOptions<Nodes extends NodeTable> = {
+  /** The feature's flow. It becomes the one node of the harness main flow, named by `as`. */flow: AnyFlow & {
+    readonly nodes: Nodes;
+  };
+  /**
+   * The key the game's main flow holds the flow under. `flow.id` by default.
+   *
+   * @example
+   * ```ts
+   * // The mini game's main flow holds info: infoFlow, whose id is "infoPopup".
+   * isolate(infoFeature, { flow: infoFlow, as: "info", player: { count: 0 } });
+   * // paths read "info/show", as in the game
+   * ```
+   */
+  as?: string; /** The shared layer, composed as `logicOnly` before the feature. */
+  shared?: FeaturePlugin; /** Node name of `flow` to the stub that replaces it. A node not listed runs for real. */
+  stubs?: StubsOf<Nodes>; /** More plugins the feature needs headless, for example a feature-own plugin. */
+  plugins?: readonly AnyPluginInstance[]; /** The player a new save starts from. */
+  player: Json; /** The session at start. `{}` by default. */
+  session?: Json; /** The rng seed. `1` by default. */
+  seed?: number;
+};
+/**
+ * What one app of an isolated feature may pin over the options.
  *
- * await game.walk([{ at: "home", intent: "roll" }]);
- * provider.calls.map(call => call.method); // ["load", "commit", "commit"]
+ * @example
+ * ```ts
+ * const game = await createHeadless(boardOnly({ player: { ...fresh, coins: 7 }, clock: fakeClock(1_000_000) }));
  * ```
  */
-declare function memory(fixture?: {
-  state: SaveDoc;
-  version: number;
-}): PlayerStateProvider & {
-  calls: ProviderCall[];
+type IsolateSeams = {
+  /** The player this app starts from, instead of `options.player`. */player?: Json; /** The session this app starts with, instead of `options.session`. */
+  session?: Json; /** The rng seed of this app, instead of `options.seed`. */
+  seed?: number; /** The clock source of this app, `fakeClock()` in a test. The system clock by default. */
+  clock?: ClockSource;
 };
 /**
- * Builds a save document from a player tree, with no rng streams drawn yet.
- * Short fixtures in tests read as `saveOf({ coins: 5 })` instead of spelling out the rng branch.
+ * An app of an isolated feature, as `createApp` returns it: not started, the engine's logic
+ * plugins on it.
+ */
+type IsolatedApp = ReturnType<typeof createApp>;
+/**
+ * A stub: the replaced node or sub-flow ends at once with this outcome. Written as a sub-flow of
+ * one transit node, so a route can still substitute it for one visit:
+ * `{ at: "board/energy", result: { outcome: "watch" } }`.
+ *
+ * @param outcome - An outcome the replaced entry declares.
+ * @param payload - The payload it carries, for an outcome with data.
+ * @returns The stub as plain data.
+ * @example
+ * ```ts
+ * stub("closed"); // { kind: "stub", outcome: "closed" }
+ * stub("orderComplete", { rewardId: "r1" }); // { kind: "stub", outcome: "orderComplete", payload: { rewardId: "r1" } }
+ * ```
+ */
+declare function stub<const Name extends string>(outcome: Name, payload?: Json): Stub<Name>;
+/**
+ * Composes one feature without the rest of the game: the shared layer and the feature as
+ * `logicOnly`, the feature's flow inside a harness main flow `isolated`, and every stubbed node
+ * replaced by a sub-flow that ends with the stub's outcome. Every exit of the flow lands on the
+ * rest node `exited`, whose intent `again` enters the flow once more. Paths read as in the game:
+ * the harness holds the flow under `options.as`, its id by default. A node that is not stubbed
+ * runs for real, even when it belongs to a feature that is not composed.
  *
- * @param player - Player tree of the save.
- * @param seed - Rng seed of the save.
- * @returns The save document.
+ * @param feature - The feature under test.
+ * @param options - Its flow, the shared layer, the stubs, the starting state.
+ * @returns A factory of apps, not started; pass one to `createHeadless`.
+ * @throws {Error} For a stub key that is not a node of the flow, or an outcome the node does not declare.
  * @example
  * ```ts
- * // A returning player with 5 coins. The test starts from this save, not from `initialPlayer`.
- * saveOf({ coins: 5 }, 42); // { player: { coins: 5 }, rng: { seed: 42, streams: {} } }
- * const provider = memory({ state: saveOf({ coins: 5 }, 42), version: 1 });
+ * // tests/fixtures/mini-game: Home alone; its info popup is stubbed to end with ok at once.
+ * const homeOnly = isolate(homeFeature, {
+ *   flow: mainFlow, stubs: { info: stub("ok") }, player: startingPlayer, session: startingSession
+ * });
+ * const game = await createHeadless(homeOnly());
+ * const state = await game.walk([{ at: "main/home", intent: "info" }]);
+ * state.path; // "main/home"
  * ```
  */
-declare function saveOf(player: Json, seed?: number): SaveDoc;
+declare function isolate<Nodes extends NodeTable>(feature: FeaturePlugin, options: IsolateOptions<Nodes>): (seams?: IsolateSeams) => IsolatedApp;
 //#endregion
-export { type HeadlessApp, type HeadlessGame, type Repro, type ReproResult, createHeadless, fakeClock, memory, runRepro, saveOf, stepFrames };
+export { type HeadlessApp, type HeadlessGame, type IsolateOptions, type IsolateSeams, type Repro, type ReproResult, type Stub, type StubsOf, createHeadless, fakeClock, isolate, memory, runRepro, saveOf, stepFrames, stub };

package/dist/testing.mjs

@@ -1,89 +1,194 @@
-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
+import { Vt as exit, Wt as type, t as createApp } from "./src-DSl1eNB1.mjs";
+import { n as saveOf, t as memory } from "./memory-CWlqhS7l.mjs";
+import { t as fakeClock } from "./fake-MpzwZhIZ.mjs";
+import { i as stepFrames, r as runRepro, t as createHeadless } from "./headless-BsNdJs9W.mjs";
+//#region src/testing/isolate.ts
+const noPayload = null;
+/** Id of the harness main flow. */
+const harnessId = "isolated";
+/** Name of the harness's rest node that every exit of the isolated flow leads to. */
+const exitedName = "exited";
+/** Name of the one transit node of a stub. */
+const endName = "end";
+/** The rng seed of an isolated app that pins none. */
+const defaultSeed = 1;
 /**
-* Removes and returns the timer that is due first, up to and including `until`.
-* Timers due at the same moment come out in the order they were scheduled.
+* A stub: the replaced node or sub-flow ends at once with this outcome. Written as a sub-flow of
+* one transit node, so a route can still substitute it for one visit:
+* `{ at: "board/energy", result: { outcome: "watch" } }`.
 *
-* @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.
+* @param outcome - An outcome the replaced entry declares.
+* @param payload - The payload it carries, for an outcome with data.
+* @returns The stub as plain data.
+* @example
+* ```ts
+* stub("closed"); // { kind: "stub", outcome: "closed" }
+* stub("orderComplete", { rewardId: "r1" }); // { kind: "stub", outcome: "orderComplete", payload: { rewardId: "r1" } }
+* ```
 */
-function takeDue(state, until) {
-	let earliest;
-	for (const timer of state.timers) {
-		if (timer.at > until) continue;
-		if (earliest === void 0 || timer.at < earliest.at) earliest = timer;
-	}
-	if (earliest === void 0) return void 0;
-	const due = earliest;
-	state.timers = state.timers.filter((timer) => timer !== due);
-	return due;
+function stub(outcome, payload) {
+	return payload === void 0 ? {
+		kind: "stub",
+		outcome
+	} : {
+		kind: "stub",
+		outcome,
+		payload
+	};
 }
 /**
-* Moves the clock to `until`, firing every timer that falls due on the way, in due order.
-* A timer scheduled inside a callback fires in the same run when it is due before `until`.
+* Builds the sub-flow `stub:<name>` that replaces one entry: one transit node `end` that ends
+* with the stub's outcome. Input and outcomes are the replaced entry's, and every outcome leaves
+* the sub-flow, so the parent's edge table stays valid and a route can substitute it by path.
 *
-* @param state - Innards of the fake clock.
-* @param until - Moment to stop at.
+* @param name - The node name of the replaced entry.
+* @param original - The replaced node, sub-flow or slot.
+* @param stubbed - The stub.
+* @returns The sub-flow.
+* @throws {Error} When the replaced entry does not declare the stub's outcome.
 */
-function runDue(state, until) {
-	let due = takeDue(state, until);
-	while (due !== void 0) {
-		state.now = Math.max(state.now, due.at);
-		due.callback();
-		due = takeDue(state, until);
-	}
-	state.now = Math.max(state.now, until);
+function stubEntry(name, original, stubbed) {
+	const outcomes = original.outcomes;
+	if (!Object.hasOwn(outcomes, stubbed.outcome)) throw new Error(`[game] stub at "${name}" ends with "${stubbed.outcome}", which "${name}" does not declare.\n  Use one of: ${Object.keys(outcomes).join(", ")}.`);
+	const end = {
+		kind: "node",
+		input: original.input,
+		outcomes,
+		rest: false,
+		over: false,
+		checkpoint: false,
+		barrier: false,
+		inbox: [],
+		run: () => ({
+			outcome: stubbed.outcome,
+			payload: stubbed.payload ?? noPayload
+		})
+	};
+	const exits = Object.fromEntries(Object.keys(outcomes).map((outcome) => [outcome, exit(outcome)]));
+	return {
+		kind: "flow",
+		id: `stub:${name}`,
+		input: original.input,
+		outcomes,
+		nodes: { [endName]: end },
+		start: endName,
+		edges: { [endName]: exits }
+	};
 }
 /**
-* 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.
+* Rebuilds a flow with the stubs applied by node name. The flow itself is never changed; without
+* stubs it is returned as it is. A key whose stub is `undefined` stubs nothing.
 *
-* @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);
-* const app = createApp({ pluginConfigs: { clock: { source: clock } } });
-* const seen: number[] = [];
+* @param flow - The feature's flow.
+* @param stubs - Node name to the stub that replaces it.
+* @returns The flow with the stubbed entries replaced.
+* @throws {Error} For a key that is not a node of the flow, or an outcome the node does not declare.
+*/
+function withStubs(flow, stubs) {
+	const entries = Object.entries(stubs).filter((entry) => entry[1] !== void 0);
+	if (entries.length === 0) return flow;
+	const nodes = { ...flow.nodes };
+	for (const [name, stubbed] of entries) {
+		const original = Object.hasOwn(flow.nodes, name) ? flow.nodes[name] : void 0;
+		if (original === void 0) throw new Error(`[game] isolate: no node "${name}" in flow "${flow.id}".\n  Stub keys are node names of the flow: ${Object.keys(flow.nodes).join(", ")}.`);
+		nodes[name] = stubEntry(name, original, stubbed);
+	}
+	return {
+		...flow,
+		nodes
+	};
+}
+/**
+* Builds the harness main flow `isolated`: the feature's flow as its node `name`, and, for a flow
+* with outcomes, the rest node `exited` that every exit leads to and whose intent `again` enters
+* the flow once more. An exit of the top-level flow would be fatal, so the flow is never the main
+* flow itself. A flow without outcomes gets no `exited`: it would be unreachable.
 *
-* 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]
-* ```
+* @param flow - The feature's flow, stubs applied.
+* @param name - The node name the flow is held under: the key the game's main flow uses.
+* @returns The harness main flow.
+* @throws {Error} When a flow with outcomes is to be held under the name `exited`.
 */
-function fakeClock(start = 0) {
-	const state = {
-		now: start,
-		nextId: 1,
-		timers: []
+function harnessOf(flow, name = flow.id) {
+	const outcomes = Object.keys(flow.outcomes);
+	const harness = {
+		kind: "flow",
+		id: harnessId,
+		input: type(),
+		outcomes: {},
+		start: name
+	};
+	if (outcomes.length === 0) return {
+		...harness,
+		nodes: { [name]: flow },
+		edges: { [name]: {} }
 	};
+	if (name === exitedName) throw new Error(`[game] isolate: "${exitedName}" is the rest node of the harness.\n  Pass another name in as.`);
+	const exited = {
+		kind: "node",
+		input: type(),
+		outcomes: { again: type() },
+		rest: true,
+		over: false,
+		checkpoint: false,
+		barrier: false,
+		inbox: []
+	};
+	const toExited = Object.fromEntries(outcomes.map((outcome) => [outcome, exitedName]));
 	return {
-		now: () => state.now,
-		setTimer: (callback, delayMs) => {
-			const id = state.nextId;
-			state.nextId += 1;
-			state.timers.push({
-				id,
-				at: state.now + Math.max(0, delayMs),
-				callback
-			});
-			return id;
-		},
-		clearTimer: (handle) => {
-			if (typeof handle !== "number") return;
-			state.timers = state.timers.filter((timer) => timer.id !== handle);
+		...harness,
+		nodes: {
+			[name]: flow,
+			[exitedName]: exited
 		},
-		advance: (ms) => {
-			runDue(state, state.now + Math.max(0, ms));
-		},
-		set: (moment) => {
-			state.now = moment;
+		edges: {
+			[name]: toExited,
+			[exitedName]: { again: name }
 		}
 	};
 }
+/**
+* Composes one feature without the rest of the game: the shared layer and the feature as
+* `logicOnly`, the feature's flow inside a harness main flow `isolated`, and every stubbed node
+* replaced by a sub-flow that ends with the stub's outcome. Every exit of the flow lands on the
+* rest node `exited`, whose intent `again` enters the flow once more. Paths read as in the game:
+* the harness holds the flow under `options.as`, its id by default. A node that is not stubbed
+* runs for real, even when it belongs to a feature that is not composed.
+*
+* @param feature - The feature under test.
+* @param options - Its flow, the shared layer, the stubs, the starting state.
+* @returns A factory of apps, not started; pass one to `createHeadless`.
+* @throws {Error} For a stub key that is not a node of the flow, or an outcome the node does not declare.
+* @example
+* ```ts
+* // tests/fixtures/mini-game: Home alone; its info popup is stubbed to end with ok at once.
+* const homeOnly = isolate(homeFeature, {
+*   flow: mainFlow, stubs: { info: stub("ok") }, player: startingPlayer, session: startingSession
+* });
+* const game = await createHeadless(homeOnly());
+* const state = await game.walk([{ at: "main/home", intent: "info" }]);
+* state.path; // "main/home"
+* ```
+*/
+function isolate(feature, options) {
+	const mainFlow = harnessOf(withStubs(options.flow, options.stubs ?? {}), options.as);
+	const plugins = [
+		...options.shared === void 0 ? [] : [options.shared.logicOnly],
+		feature.logicOnly,
+		...options.plugins ?? []
+	];
+	return (seams = {}) => createApp({
+		plugins: [...plugins],
+		pluginConfigs: {
+			model: {
+				initialPlayer: seams.player ?? options.player,
+				initialSession: seams.session ?? options.session ?? {},
+				seed: seams.seed ?? options.seed ?? defaultSeed
+			},
+			flow: { mainFlow },
+			clock: { source: seams.clock }
+		}
+	});
+}
 //#endregion
-export { createHeadless, fakeClock, memory, runRepro, saveOf, stepFrames };
+export { createHeadless, fakeClock, isolate, memory, runRepro, saveOf, stepFrames, stub };