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>;
 }
 
-/**
+export function createGameContext<TState extends {} = {}>(
- * creates a game context.
+    commandRegistry: CommandRegistry<IGameContext<TState>>,
- * expects a command registry already registered with commands.
+    initialState?: TState | (() => TState)
- * @param commandRegistry
+): IGameContext<TState> {
- */
-export function createGameContext(commandRegistry: CommandRegistry<IGameContext>) {
     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>
+    run: (this: CommandRunnerContext<IGameContext<TState>>, command: Command) => Promise<TResult>
-): CommandRunner<IGameContext, 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 { IGameContext, createGameCommand } from '../core/game';
-import {CommandRegistry, CommandRunner, registerCommand} from '../utils/command';
+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;
+            winner = turnOutput.result.winner;
-            if (turnResult) break;
+            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>) {
+export const registry = createCommandRegistry<TicTacToeContext>();
-    registerCommand(registry, setup);
+registerCommand(registry, setup);
-    registerCommand(registry, turn);
+registerCommand(registry, turn);
-}

tests/core/game.test.ts

@@ -1,7 +1,15 @@
 import { describe, it, expect } from 'vitest';
-import { createGameContext, createGameCommand } from '../../src/core/game';
+import { createGameContext, createGameCommand, IGameContext } from '../../src/core/game';
 import { createCommandRegistry, parseCommandSchema, type CommandRegistry } from '../../src/utils/command';
-import type { IGameContext } from '../../src/core/game';
+
+type MyState = {
+    score: number;
+    round: number;
+};
+
+type MyContext = IGameContext & {
+    state: MyState;
+};
 
 describe('createGameContext', () => {
     it('should create a game context with empty parts and regions', () => {
@@ -21,6 +29,26 @@ describe('createGameContext', () => {
         expect(ctx.commands.context).toBe(ctx);
     });
 
+    it('should accept initial state as an object', () => {
+        const registry = createCommandRegistry<MyContext>();
+        const ctx = createGameContext<MyContext>(registry, {
+            state: { score: 0, round: 1 },
+        });
+
+        expect(ctx.state.score).toBe(0);
+        expect(ctx.state.round).toBe(1);
+    });
+
+    it('should accept initial state as a factory function', () => {
+        const registry = createCommandRegistry<MyContext>();
+        const ctx = createGameContext<MyContext>(registry, () => ({
+            state: { score: 10, round: 3 },
+        }));
+
+        expect(ctx.state.score).toBe(10);
+        expect(ctx.state.round).toBe(3);
+    });
+
     it('should forward prompt events to the prompts queue', async () => {
         const registry = createCommandRegistry<IGameContext>();
         const ctx = createGameContext(registry);
@@ -123,4 +151,30 @@ describe('createGameCommand', () => {
         }
         expect(ctx.parts.get('piece-1')).not.toBeNull();
     });
+
+    it('should run a typed command with extended context', async () => {
+        const registry = createCommandRegistry<MyContext>();
+
+        const addScore = createGameCommand<MyContext, number>(
+            'add-score <amount:number>',
+            async function (cmd) {
+                const amount = cmd.params[0] as number;
+                this.context.state.score += amount;
+                return this.context.state.score;
+            }
+        );
+
+        registry.set('add-score', addScore);
+
+        const ctx = createGameContext<MyContext>(registry, () => ({
+            state: { score: 0, round: 1 },
+        }));
+
+        const result = await ctx.commands.run('add-score 5');
+        expect(result.success).toBe(true);
+        if (result.success) {
+            expect(result.result).toBe(5);
+        }
+        expect(ctx.state.score).toBe(5);
+    });
 });

tests/samples/tic-tac-toe.test.ts

@@ -1,18 +1,15 @@
 import { describe, it, expect } from 'vitest';
-import { createGameContext } from '../../src/core/game';
+import {registry, checkWinner, isCellOccupied, placePiece, createInitialState} from '../../src/samples/tic-tac-toe';
-import { createCommandRegistry } from '../../src/utils/command';
+import type { TicTacToeContext } from '../../src/samples/tic-tac-toe';
-import { registerTicTacToeCommands, checkWinner, isCellOccupied, placePiece } from '../../src/samples/tic-tac-toe';
-import type { IGameContext } from '../../src/core/game';
 import type { Part } from '../../src/core/part';
+import {createGameContext} from "../../src";
 
 function createTestContext() {
-    const registry = createCommandRegistry<IGameContext>();
+    const ctx = createGameContext(registry, createInitialState);
-    registerTicTacToeCommands(registry);
-    const ctx = createGameContext(registry);
     return { registry, ctx };
 }
 
-function setupBoard(ctx: IGameContext) {
+function setupBoard(ctx: TicTacToeContext) {
     ctx.regions.add({
         id: 'board',
         axes: [
@@ -23,7 +20,7 @@ function setupBoard(ctx: IGameContext) {
     });
 }
 
-function addPiece(ctx: IGameContext, id: string, row: number, col: number) {
+function addPiece(ctx: TicTacToeContext, id: string, row: number, col: number) {
     const board = ctx.regions.get('board');
     const part: Part = {
         id,
@@ -172,10 +169,10 @@ describe('TicTacToe - helper functions', () => {
 
 describe('TicTacToe - game flow', () => {
     it('should have setup and turn commands registered', () => {
-        const { registry } = createTestContext();
+        const { registry: reg } = createTestContext();
 
-        expect(registry.has('setup')).toBe(true);
+        expect(reg.has('setup')).toBe(true);
-        expect(registry.has('turn')).toBe(true);
+        expect(reg.has('turn')).toBe(true);
     });
 
     it('should setup board when setup command runs', async () => {
@@ -205,7 +202,6 @@ describe('TicTacToe - game flow', () => {
 
         promptEvent.resolve({ name: 'play', params: ['X', 1, 1], options: {}, flags: {} });
 
-        // After valid non-winning move, turn command prompts again, reject to stop
         const promptEvent2 = await ctx.prompts.pop();
         promptEvent2.reject(new Error('done'));
 
@@ -229,7 +225,6 @@ describe('TicTacToe - game flow', () => {
 
         promptEvent2.resolve({ name: 'play', params: ['X', 1, 1], options: {}, flags: {} });
 
-        // After valid non-winning move, reject next prompt
         const promptEvent3 = await ctx.prompts.pop();
         promptEvent3.reject(new Error('done'));
 
@@ -253,7 +248,6 @@ describe('TicTacToe - game flow', () => {
 
         promptEvent2.resolve({ name: 'play', params: ['X', 0, 0], options: {}, flags: {} });
 
-        // After valid non-winning move, reject next prompt
         const promptEvent3 = await ctx.prompts.pop();
         promptEvent3.reject(new Error('done'));
 
@@ -265,7 +259,6 @@ describe('TicTacToe - game flow', () => {
         const { ctx } = createTestContext();
         setupBoard(ctx);
 
-        // X plays (0,0)
         let runPromise = ctx.commands.run('turn X 1');
         let prompt = await ctx.prompts.pop();
         prompt.resolve({ name: 'play', params: ['X', 0, 0], options: {}, flags: {} });
@@ -274,7 +267,6 @@ describe('TicTacToe - game flow', () => {
         let result = await runPromise;
         expect(result.success).toBe(false);
 
-        // O plays (0,1)
         runPromise = ctx.commands.run('turn O 2');
         prompt = await ctx.prompts.pop();
         prompt.resolve({ name: 'play', params: ['O', 0, 1], options: {}, flags: {} });
@@ -283,7 +275,6 @@ describe('TicTacToe - game flow', () => {
         result = await runPromise;
         expect(result.success).toBe(false);
 
-        // X plays (1,0)
         runPromise = ctx.commands.run('turn X 3');
         prompt = await ctx.prompts.pop();
         prompt.resolve({ name: 'play', params: ['X', 1, 0], options: {}, flags: {} });
@@ -292,7 +283,6 @@ describe('TicTacToe - game flow', () => {
         result = await runPromise;
         expect(result.success).toBe(false);
 
-        // O plays (0,2)
         runPromise = ctx.commands.run('turn O 4');
         prompt = await ctx.prompts.pop();
         prompt.resolve({ name: 'play', params: ['O', 0, 2], options: {}, flags: {} });
@@ -301,7 +291,6 @@ describe('TicTacToe - game flow', () => {
         result = await runPromise;
         expect(result.success).toBe(false);
 
-        // X plays (2,0) - wins with vertical line
         runPromise = ctx.commands.run('turn X 5');
         prompt = await ctx.prompts.pop();
         prompt.resolve({ name: 'play', params: ['X', 2, 0], options: {}, flags: {} });
@@ -314,28 +303,23 @@ describe('TicTacToe - game flow', () => {
         const { ctx } = createTestContext();
         setupBoard(ctx);
 
-        // Pre-place 8 pieces that don't form any winning line for either player
-        // Using positions that clearly don't form lines
-        // X pieces at even indices, O pieces at odd indices
         const pieces = [
-            { id: 'p1', pos: [0, 0] }, // X
+            { id: 'p1', pos: [0, 0] },
-            { id: 'p2', pos: [2, 2] }, // O
+            { id: 'p2', pos: [2, 2] },
-            { id: 'p3', pos: [0, 2] }, // X
+            { id: 'p3', pos: [0, 2] },
-            { id: 'p4', pos: [2, 0] }, // O
+            { id: 'p4', pos: [2, 0] },
-            { id: 'p5', pos: [1, 0] }, // X
+            { id: 'p5', pos: [1, 0] },
-            { id: 'p6', pos: [0, 1] }, // O
+            { id: 'p6', pos: [0, 1] },
-            { id: 'p7', pos: [2, 1] }, // X
+            { id: 'p7', pos: [2, 1] },
-            { id: 'p8', pos: [1, 2] }, // O
+            { id: 'p8', pos: [1, 2] },
         ];
 
         for (const { id, pos } of pieces) {
             addPiece(ctx, id, pos[0], pos[1]);
         }
 
-        // Verify no winner before 9th move
         expect(checkWinner(ctx)).toBeNull();
 
-        // Now X plays (1,1) for the 9th move -> draw
         const runPromise = ctx.commands.run('turn X 9');
         const prompt = await ctx.prompts.pop();
         prompt.resolve({ name: 'play', params: ['X', 1, 1], options: {}, flags: {} });