@moku-labs/game 0.14.11 → 0.14.13

package/dist/testing.d.mts

@@ -1,7 +1,7 @@
-import { Dt as AnyFlow, Ht as ClockSource, Nt as NodeTable, Wt as FakeClock, Xt as Json, ht as FeaturePlugin } from "./types-BT9S_Lo2.mjs";
-import { t as createApp } from "./index-0GIP3tgm.mjs";
-import { n as saveOf, t as memory } from "./memory-DR1ibF_s.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-CrhefcLu.mjs";
+import { $n as NodeFx, In as FeaturePlugin, Jn as Descriptor, Qn as Hint, Rn as AnyFlow, Wn as NodeTable, ir as FakeClock, nr as ClockSource, ur as Json } from "./types-BGcda5Le.mjs";
+import { t as createApp } from "./index-DedbED3T.mjs";
+import { b as saveOf, v as WithGameState, y as memory } from "./types-C73hbmxi.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-cFveciuY.mjs";
 import { AnyPluginInstance } from "@moku-labs/core";
 
 //#region src/plugins/clock/fake.d.ts
@@ -26,6 +26,101 @@ import { AnyPluginInstance } from "@moku-labs/core";
  */
 declare function fakeClock(start?: number): FakeClock;
 //#endregion
+//#region src/testing/fake-fx.d.ts
+/**
+ * What a test tells `fakeFx`.
+ *
+ * @example
+ * ```ts
+ * const options: FakeFxOptions = {
+ *   answer: descriptor => (descriptor.kind === "popup" ? { intent: "again" } : undefined),
+ *   path: "board/place"
+ * };
+ * ```
+ */
+type FakeFxOptions = {
+  /**
+   * What an awaited effect resolves with: a value, or a promise of one. Called once for every
+   * `await fx(descriptor)`, at the call, with the descriptor itself. Without it every awaited
+   * effect resolves `undefined`. A promise that never settles holds the body at its `await`, as a
+   * real effect can. A throw and a rejection stand for a handler that fails, and end as they do
+   * in the game: the awaited effect rejects, except for a descriptor with `cosmetic: true`
+   * (`sfx`, `play`, `haptic`, `music`), which resolves `undefined`. The game also writes the warn
+   * entry `flow:fx-cosmetic-failed` there. The fake has no log and writes nothing.
+   *
+   * @example
+   * ```ts
+   * // The popup is answered, a sound never ends: a body that waits for the sound stays there.
+   * fakeFx({
+   *   answer: descriptor =>
+   *     descriptor.kind === "sfx" ? new Promise<never>(() => undefined) : { intent: "again" }
+   * });
+   * ```
+   */
+  answer?: (descriptor: Descriptor) => unknown;
+  /**
+   * The path of the node under test. Only the error of a refused `fx.start` names it. `"test"`
+   * by default.
+   */
+  path?: string;
+};
+/**
+ * What `fakeFx` returns: the `fx` for the node context, and the three lists it records into.
+ * Each list is one array for the whole life of the fake: a list read before the body ran holds
+ * the later calls too, and a test starts a list over with `list.length = 0`. The lists hold the
+ * objects the body passed, not copies. The holder is frozen, so a list cannot be replaced by
+ * another array the fake would not write to.
+ *
+ * @example
+ * ```ts
+ * const { fx, started }: FakeFx = fakeFx();
+ *
+ * fx.start({ kind: "sfx", payload: { key: "ui.tap" } });
+ * started; // [{ kind: "sfx", payload: { key: "ui.tap" } }]
+ * ```
+ */
+type FakeFx = {
+  /** The `fx` to put into the node context: `{ ...context, fx: fake.fx }`. */readonly fx: NodeFx; /** Every `await fx(descriptor)` in call order, recorded at the call, answered or not. */
+  readonly awaited: Descriptor[]; /** Every `fx.start(descriptor)` in call order. A refused start is not in it. */
+  readonly started: Descriptor[]; /** Every `fx.emit(hint)` in call order. */
+  readonly emitted: Hint[];
+};
+/**
+ * Builds the `fx` of a node context for a unit test that calls `node.run(context)` itself, with no
+ * app and no runner. It records every call and plays no effect: `await fx(descriptor)` goes to
+ * `awaited` and resolves with `options.answer(descriptor)`, `fx.start(descriptor)` goes to
+ * `started`, `fx.emit(hint)` goes to `emitted`. `fx.start` refuses a descriptor with `answers`
+ * and a `guide` with the error the game throws. An `answer` that fails rejects the awaited
+ * effect, and resolves `undefined` for a `cosmetic` descriptor, as in the game. There is no
+ * handler, no log, no fast mode and no abort signal here: for those, walk the graph with
+ * `createHeadless`.
+ *
+ * @param options - The answer of an awaited effect, and the node path for the refusal message.
+ * @returns The `fx` and the lists `awaited`, `started` and `emitted`.
+ * @example
+ * ```ts
+ * // The body of the node "place" runs fx.start(sfx("ui.tap")), then pushes input.cell to
+ * // session.marks. `context` is the rest of its context: input, player, session, rng, out,
+ * // signal and now.
+ * const fx = fakeFx();
+ *
+ * await place.run?.({ ...context, fx: fx.fx });
+ *
+ * fx.started; // [{ kind: "sfx", payload: { key: "ui.tap", bus: "sfx" }, cosmetic: true }]
+ * fx.awaited; // []: the body waited for no effect
+ *
+ * // The node "retry" awaits a popup that takes answers. The test gives the player's pick.
+ * const picked = fakeFx({
+ *   answer: descriptor => (descriptor.kind === "popup" ? { intent: "again" } : undefined)
+ * });
+ *
+ * await retry.run?.({ ...context, fx: picked.fx });
+ *
+ * picked.awaited; // [{ kind: "popup", payload: { name: "Retry" }, answers: ["again", "home"] }]
+ * ```
+ */
+declare function fakeFx(options?: FakeFxOptions): FakeFx;
+//#endregion
 //#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.
@@ -65,12 +160,12 @@ type StubsOf<Nodes extends NodeTable> = { readonly [Name in keyof Nodes & string
  *
  * @example
  * ```ts
- * const options: IsolateOptions<typeof boardFlow.nodes> = {
+ * const options: IsolateOptions<typeof boardFlow.nodes, Player> = {
  *   flow: boardFlow, shared: sharedLayer, stubs: { settings: stub("closed") }, player: fresh
  * };
  * ```
  */
-type IsolateOptions<Nodes extends NodeTable> = {
+type IsolateOptions<Nodes extends NodeTable, Player extends Json = Json, Session extends Json = Json> = {
   /** The feature's flow. It becomes the one node of the harness main flow, named by `as`. */flow: AnyFlow & {
     readonly nodes: Nodes;
   };
@@ -87,9 +182,9 @@ type IsolateOptions<Nodes extends NodeTable> = {
   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. */
+  plugins?: readonly AnyPluginInstance[]; /** The player a new save starts from. Its type types `model.store.snapshot().player`. */
+  player: Player; /** The session at start. `{}` by default. Its type types `model.store.snapshot().session`. */
+  session?: Session; /** The rng seed. `1` by default. */
   seed?: number;
 };
 /**
@@ -111,6 +206,12 @@ type IsolateSeams = {
  * plugins on it.
  */
 type IsolatedApp = ReturnType<typeof createApp>;
+/**
+ * The app of an isolated feature with `model.store.snapshot()` typed by the player and session
+ * of the `isolate` call, as `WithGameState` types `game.headless()`. A call whose player and
+ * session are `Model.Json` reads a `Model.Json` snapshot, as before. Only the type.
+ */
+type IsolatedAppOf<Player, Session> = WithGameState<IsolatedApp, Player, Session>;
 /**
  * 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:
@@ -128,14 +229,16 @@ type IsolatedApp = ReturnType<typeof createApp>;
 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
+ * `logicOnly` (a parent feature is composed with its sub-features), 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.
+ * @param options - Its flow, the shared layer, the stubs, the starting state. The types of
+ *   `player` and `session` type the app's `model.store.snapshot()`.
  * @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
@@ -144,11 +247,13 @@ declare function stub<const Name extends string>(outcome: Name, payload?: Json):
  * const homeOnly = isolate(homeFeature, {
  *   flow: mainFlow, stubs: { info: stub("ok") }, player: startingPlayer, session: startingSession
  * });
- * const game = await createHeadless(homeOnly());
+ * const app = homeOnly();
+ * const game = await createHeadless(app);
  * const state = await game.walk([{ at: "main/home", intent: "info" }]);
  * state.path; // "main/home"
+ * app.model.store.snapshot().player.count; // 0, typed number: startingPlayer types the snapshot
  * ```
  */
-declare function isolate<Nodes extends NodeTable>(feature: FeaturePlugin, options: IsolateOptions<Nodes>): (seams?: IsolateSeams) => IsolatedApp;
+declare function isolate<Nodes extends NodeTable, Player extends Json = Json, Session extends Json = Json>(feature: FeaturePlugin, options: IsolateOptions<Nodes, Player, Session>): (seams?: IsolateSeams) => IsolatedAppOf<Player, Session>;
 //#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 };
+export { type FakeFx, type FakeFxOptions, type HeadlessApp, type HeadlessGame, type IsolateOptions, type IsolateSeams, type Repro, type ReproResult, type Stub, type StubsOf, createHeadless, fakeClock, fakeFx, isolate, memory, runRepro, saveOf, stepFrames, stub };

package/dist/testing.mjs

@@ -1,7 +1,93 @@
-import { Kt as type, Ut as exit, t as createApp } from "./src-Do697seR.mjs";
+import { $t as refuseStart, en as exit, p as flattenFeatures, rn as type, t as createApp } from "./src-BEbJ_sSx.mjs";
 import { n as saveOf, t as memory } from "./memory-CWlqhS7l.mjs";
-import { t as fakeClock } from "./fake-MpzwZhIZ.mjs";
+import { t as fakeClock } from "./fake-6mazmHK3.mjs";
 import { i as stepFrames, r as runRepro, t as createHeadless } from "./headless-BA6ffzqD.mjs";
+//#region src/testing/fake-fx.ts
+/** The node path a refused `fx.start` names when the test gives none. */
+const defaultPath = "test";
+/**
+* Builds the `fx` of a node context for a unit test that calls `node.run(context)` itself, with no
+* app and no runner. It records every call and plays no effect: `await fx(descriptor)` goes to
+* `awaited` and resolves with `options.answer(descriptor)`, `fx.start(descriptor)` goes to
+* `started`, `fx.emit(hint)` goes to `emitted`. `fx.start` refuses a descriptor with `answers`
+* and a `guide` with the error the game throws. An `answer` that fails rejects the awaited
+* effect, and resolves `undefined` for a `cosmetic` descriptor, as in the game. There is no
+* handler, no log, no fast mode and no abort signal here: for those, walk the graph with
+* `createHeadless`.
+*
+* @param options - The answer of an awaited effect, and the node path for the refusal message.
+* @returns The `fx` and the lists `awaited`, `started` and `emitted`.
+* @example
+* ```ts
+* // The body of the node "place" runs fx.start(sfx("ui.tap")), then pushes input.cell to
+* // session.marks. `context` is the rest of its context: input, player, session, rng, out,
+* // signal and now.
+* const fx = fakeFx();
+*
+* await place.run?.({ ...context, fx: fx.fx });
+*
+* fx.started; // [{ kind: "sfx", payload: { key: "ui.tap", bus: "sfx" }, cosmetic: true }]
+* fx.awaited; // []: the body waited for no effect
+*
+* // The node "retry" awaits a popup that takes answers. The test gives the player's pick.
+* const picked = fakeFx({
+*   answer: descriptor => (descriptor.kind === "popup" ? { intent: "again" } : undefined)
+* });
+*
+* await retry.run?.({ ...context, fx: picked.fx });
+*
+* picked.awaited; // [{ kind: "popup", payload: { name: "Retry" }, answers: ["again", "home"] }]
+* ```
+*/
+function fakeFx(options = {}) {
+	const path = options.path ?? defaultPath;
+	const awaited = [];
+	const started = [];
+	const emitted = [];
+	/**
+	* Records one awaited effect and answers it. Both happen at the call. An `answer` that throws
+	* or rejects is a handler that fails: the effect rejects, never the call. A `cosmetic`
+	* descriptor swallows that failure and resolves `undefined`, as the gateway of the game does.
+	*
+	* @param descriptor - The descriptor the body awaits.
+	* @returns A promise of what `options.answer` gives for it.
+	*/
+	const run = async (descriptor) => {
+		awaited.push(descriptor);
+		try {
+			return await options.answer?.(descriptor);
+		} catch (error) {
+			if (descriptor.cosmetic !== true) throw error;
+		}
+	};
+	const fx = Object.assign(run, {
+		/**
+		* Records one hint. Nothing releases it: the test has no edge to commit.
+		*
+		* @param item - The hint.
+		*/
+		emit: (item) => {
+			emitted.push(item);
+		},
+		/**
+		* Records one started effect, unless the real `fx.start` would refuse it.
+		*
+		* @param descriptor - The descriptor the body starts.
+		* @throws {Error} When the descriptor has `answers` or is a `guide`.
+		*/
+		start: (descriptor) => {
+			refuseStart(descriptor, path);
+			started.push(descriptor);
+		}
+	});
+	return Object.freeze({
+		fx,
+		awaited,
+		started,
+		emitted
+	});
+}
+//#endregion
 //#region src/testing/isolate.ts
 const noPayload = null;
 /** Id of the harness main flow. */
@@ -149,14 +235,16 @@ function harnessOf(flow, name = flow.id) {
 }
 /**
 * 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
+* `logicOnly` (a parent feature is composed with its sub-features), 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.
+* @param options - Its flow, the shared layer, the stubs, the starting state. The types of
+*   `player` and `session` type the app's `model.store.snapshot()`.
 * @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
@@ -165,16 +253,18 @@ function harnessOf(flow, name = flow.id) {
 * const homeOnly = isolate(homeFeature, {
 *   flow: mainFlow, stubs: { info: stub("ok") }, player: startingPlayer, session: startingSession
 * });
-* const game = await createHeadless(homeOnly());
+* const app = homeOnly();
+* const game = await createHeadless(app);
 * const state = await game.walk([{ at: "main/home", intent: "info" }]);
 * state.path; // "main/home"
+* app.model.store.snapshot().player.count; // 0, typed number: startingPlayer types the snapshot
 * ```
 */
 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,
+		...flattenFeatures([feature.logicOnly]),
 		...options.plugins ?? []
 	];
 	return (seams = {}) => createApp({
@@ -191,4 +281,4 @@ function isolate(feature, options) {
 	});
 }
 //#endregion
-export { createHeadless, fakeClock, isolate, memory, runRepro, saveOf, stepFrames, stub };
+export { createHeadless, fakeClock, fakeFx, isolate, memory, runRepro, saveOf, stepFrames, stub };