@moku-labs/game 0.8.0 → 0.9.0

package/dist/testing.d.mts

@@ -1,5 +1,7 @@
-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 { $t as PlayerStateProvider, Et as AnyFlow, Jt as Json, Mt as NodeTable, en as ProviderCall, gn as FakeClock, mn as ClockSource, mt as FeaturePlugin, tn as SaveDoc } from "./types-B0v5VVa3.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-SCQXJxQf.mjs";
+import { t as createApp } from "./index-BO9kZzY3.mjs";
+import { AnyPluginInstance } from "@moku-labs/core";
 
 //#region src/plugins/clock/fake.d.ts
 /**
@@ -70,4 +72,129 @@ declare function memory(fixture?: {
  */
 declare function saveOf(player: Json, seed?: number): SaveDoc;
 //#endregion
-export { type HeadlessApp, type HeadlessGame, type Repro, type ReproResult, createHeadless, fakeClock, memory, runRepro, saveOf, stepFrames };
+//#region src/testing/isolate.d.ts
+/**
+ * A stub for one node or sub-flow of the isolated flow: the outcome it ends with, and its payload.
+ *
+ * @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.
+ *
+ * @example
+ * ```ts
+ * 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.
+ *
+ * @example
+ * ```ts
+ * const game = await createHeadless(boardOnly({ player: { ...fresh, coins: 7 }, clock: fakeClock(1_000_000) }));
+ * ```
+ */
+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;
+};
+/**
+ * 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 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"
+ * ```
+ */
+declare function isolate<Nodes extends NodeTable>(feature: FeaturePlugin, options: IsolateOptions<Nodes>): (seams?: IsolateSeams) => IsolatedApp;
+//#endregion
+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,5 +1,5 @@
-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";
+import { Jt as saveOf, Vt as exit, Wt as type, qt as memory, t as createApp } from "./src-536arXjV.mjs";
+import { i as stepFrames, r as runRepro, t as createHeadless } from "./headless-BsNdJs9W.mjs";
 //#region src/plugins/clock/fake.ts
 /**
 * Removes and returns the timer that is due first, up to and including `until`.
@@ -86,4 +86,193 @@ function fakeClock(start = 0) {
 	};
 }
 //#endregion
-export { createHeadless, fakeClock, memory, runRepro, saveOf, stepFrames };
+//#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;
+/**
+* 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" } }
+* ```
+*/
+function stub(outcome, payload) {
+	return payload === void 0 ? {
+		kind: "stub",
+		outcome
+	} : {
+		kind: "stub",
+		outcome,
+		payload
+	};
+}
+/**
+* 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 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 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 }
+	};
+}
+/**
+* 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 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.
+*
+* @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 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 {
+		...harness,
+		nodes: {
+			[name]: flow,
+			[exitedName]: exited
+		},
+		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, isolate, memory, runRepro, saveOf, stepFrames, stub };