refactor: update api

src/core/game.ts

@@ -11,37 +11,53 @@ import {
 } from "../utils/command";
 import {AsyncQueue} from "../utils/async-queue";
 
-export interface IGameContext {
+export interface IGameContext<TState extends {} = {}> {
     parts: ReturnType<typeof createEntityCollection<Part>>;
     regions: ReturnType<typeof createEntityCollection<Region>>;
-    commands: CommandRunnerContextExport<IGameContext>;
+    commands: CommandRunnerContextExport<IGameContext<TState>>;
     prompts: AsyncQueue<PromptEvent>;
 }
 
-/**
- * creates a game context.
- * expects a command registry already registered with commands.
- * @param commandRegistry
- */
-export function createGameContext(commandRegistry: CommandRegistry<IGameContext>) {
+export function createGameContext<TState extends {} = {}>(
+    commandRegistry: CommandRegistry<IGameContext<TState>>,
+    initialState?: TState | (() => TState)
+): IGameContext<TState> {
     const parts = createEntityCollection<Part>();
     const regions = createEntityCollection<Region>();
-    const ctx: IGameContext = {
+    const prompts = new AsyncQueue<PromptEvent>();
+    const state: TState = typeof initialState === 'function' ? (initialState as (() => TState))() : (initialState ?? {} as TState);
+
+    const ctx = {
         parts,
         regions,
+        prompts,
         commands: null!,
-        prompts: new AsyncQueue(),
-    };
+        state,
+    } as IGameContext<TState>
+
     ctx.commands = createCommandRunnerContext(commandRegistry, ctx);
     ctx.commands.on('prompt', (prompt: PromptEvent) => ctx.prompts.push(prompt));
 
     return ctx;
 }
 
-export function createGameCommand<TResult>(
+/**
+ * so that we can do `import * as tictactoe from './tic-tac-toe.ts';\n\n createGameContextFromModule(tictactoe);`
+ * @param module
+ */
+export function createGameContextFromModule<TState extends {} = {}>(
+    module: {
+        registry: CommandRegistry<IGameContext<TState>>,
+        createInitialState: () => TState
+    },
+): IGameContext<TState> {
+    return createGameContext(module.registry, module.createInitialState);
+}
+
+export function createGameCommand<TState extends {} = {}, TResult = unknown>(
     schema: CommandSchema | string,
-    run: (this: CommandRunnerContext<IGameContext>, command: Command) => Promise<TResult>
-): CommandRunner<IGameContext, TResult> {
+    run: (this: CommandRunnerContext<IGameContext<TState>>, command: Command) => Promise<TResult>
+): CommandRunner<IGameContext<TState>, TResult> {
     return {
         schema: typeof schema === 'string' ? parseCommandSchema(schema) : schema,
         run,

src/samples/tic-tac-toe.ts

@@ -1,7 +1,6 @@
-import { IGameContext } from '../core/game';
-import {CommandRegistry, CommandRunner, registerCommand} from '../utils/command';
+import { IGameContext, createGameCommand } from '../core/game';
+import { createCommandRegistry, type CommandRegistry, registerCommand } from '../utils/command';
 import type { Part } from '../core/part';
-import {createGameCommand} from "../core/game";
 
 export type TicTacToeState = {
     currentPlayer: 'X' | 'O';
@@ -9,15 +8,25 @@ export type TicTacToeState = {
     moveCount: number;
 };
 
+export type TicTacToeContext = IGameContext<TicTacToeState>;
+
 type TurnResult = {
     winner: 'X' | 'O' | 'draw' | null;
 };
 
-export function getBoardRegion(host: IGameContext) {
+export function createInitialState(): TicTacToeState {
+    return {
+        currentPlayer: 'X',
+        winner: null,
+        moveCount: 0,
+    };
+}
+
+export function getBoardRegion(host: TicTacToeContext) {
     return host.regions.get('board');
 }
 
-export function isCellOccupied(host: IGameContext, row: number, col: number): boolean {
+export function isCellOccupied(host: TicTacToeContext, row: number, col: number): boolean {
     const board = getBoardRegion(host);
     return board.value.children.some(
         (child: { value: { position: number[] } }) => child.value.position[0] === row && child.value.position[1] === col
@@ -43,7 +52,7 @@ export function hasWinningLine(positions: number[][]): boolean {
     );
 }
 
-export function checkWinner(host: IGameContext): 'X' | 'O' | 'draw' | null {
+export function checkWinner(host: TicTacToeContext): 'X' | 'O' | 'draw' | null {
     const parts = Object.values(host.parts.collection.value).map((s: { value: Part }) => s.value);
 
     const xPositions = parts.filter((_: Part, i: number) => i % 2 === 0).map((p: Part) => p.position);
@@ -55,7 +64,7 @@ export function checkWinner(host: IGameContext): 'X' | 'O' | 'draw' | null {
     return null;
 }
 
-export function placePiece(host: IGameContext, row: number, col: number, moveCount: number) {
+export function placePiece(host: TicTacToeContext, row: number, col: number, moveCount: number) {
     const board = getBoardRegion(host);
     const piece: Part = {
         id: `piece-${moveCount}`,
@@ -68,7 +77,7 @@ export function placePiece(host: IGameContext, row: number, col: number, moveCou
     board.value.children.push(host.parts.get(piece.id));
 }
 
-const setup = createGameCommand(
+const setup = createGameCommand<TicTacToeContext, { winner: 'X' | 'O' | 'draw' | null }>(
     'setup',
     async function() {
         this.context.regions.add({
@@ -81,23 +90,23 @@ const setup = createGameCommand(
         });
 
         let currentPlayer: 'X' | 'O' = 'X';
-        let turnResult: TurnResult | undefined;
+        let winner: 'X' | 'O' | 'draw' | null = null;
         let turn = 1;
 
         while (true) {
             const turnOutput = await this.run<TurnResult>(`turn ${currentPlayer} ${turn++}`);
             if (!turnOutput.success) throw new Error(turnOutput.error);
-            turnResult = turnOutput?.result.winner;
-            if (turnResult) break;
+            winner = turnOutput.result.winner;
+            if (winner) break;
 
             currentPlayer = currentPlayer === 'X' ? 'O' : 'X';
         }
 
-        return { winner: turnResult };
+        return { winner };
     }
 )
 
-const turn = createGameCommand(
+const turn = createGameCommand<TicTacToeContext, TurnResult>(
     'turn <player> <turn:number>',
     async function(cmd) {
         const [turnPlayer, turnNumber] = cmd.params as [string, number];
@@ -119,7 +128,6 @@ const turn = createGameCommand(
     }
 );
 
-export function registerTicTacToeCommands(registry: CommandRegistry<IGameContext>) {
-    registerCommand(registry, setup);
-    registerCommand(registry, turn);
-}
+export const registry = createCommandRegistry<TicTacToeContext>();
+registerCommand(registry, setup);
+registerCommand(registry, turn);