hypercross
/
boardgame-core
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Compare commits

base: hypercross:bcb31da77301546b976092178c605d915d61c9ca
Branches Tags
hypercross:master
...
compare: hypercross:846badc08192d4b91fe3e08ff129105279a8a30d
Branches Tags
hypercross:master

6 Commits
bcb31da773 ... 846badc081

Author SHA1 Message Date
hypercross 846badc081 tests: game and tic tac toe 2026-04-02 11:31:57 +08:00
hypercross 1cb7fa05ec refactor: rewrite game & tic tac toe 2026-04-02 11:06:29 +08:00
hypercross 5042d6ebc7 refactor: allow run command to return a typed result 2026-04-02 10:38:31 +08:00
hypercross d4a8668b54 refactor: remove context. add game. 2026-04-02 10:26:42 +08:00
hypercross 9c7baa29ef refactor: add a new async queue 2026-04-02 10:04:22 +08:00
hypercross 40788d445d refactor: replace rule.ts with a command runner based solution 2026-04-02 09:33:03 +08:00
12 changed files with 744 additions and 942 deletions
Show Stats Expand all files Collapse all files

94
src/core/context.ts
View File

@ -1,94 +0,0 @@
import {createModel, Signal, signal} from '@preact/signals-core';
import {createEntityCollection} from "../utils/entity";
import {Part} from "./part";
import {Region} from "./region";
import {RuleDef, RuleRegistry, RuleContext, RuleEngineHost, dispatchCommand as dispatchRuleCommand} from "./rule";
export type Context = {
type: string;
}
export const GameContext = createModel((root: Context) => {
const parts = createEntityCollection<Part>();
const regions = createEntityCollection<Region>();
const rules = signal<RuleRegistry>(new Map());
const ruleContexts = signal<RuleContext<unknown>[]>([]);
const contexts = signal<Signal<Context>[]>([]);
contexts.value = [signal(root)];
function pushContext(context: Context) {
const ctxSignal = signal(context);
contexts.value = [...contexts.value, ctxSignal];
return context;
}
function popContext() {
if (contexts.value.length > 1) {
contexts.value = contexts.value.slice(0, -1);
}
}
function latestContext<T extends Context>(type: T['type']): Signal<T> | undefined {
for(let i = contexts.value.length - 1; i >= 0; i--){
if(contexts.value[i].value.type === type){
return contexts.value[i] as Signal<T>;
}
}
return undefined;
}
function registerRule(name: string, rule: RuleDef<unknown, RuleEngineHost>) {
const newRules = new Map(rules.value);
newRules.set(name, rule);
rules.value = newRules;
}
function unregisterRule(name: string) {
const newRules = new Map(rules.value);
newRules.delete(name);
rules.value = newRules;
}
function addRuleContext(ctx: RuleContext<unknown>) {
ruleContexts.value = [...ruleContexts.value, ctx];
}
function removeRuleContext(ctx: RuleContext<unknown>) {
ruleContexts.value = ruleContexts.value.filter(c => c !== ctx);
}
function dispatchCommand(this: GameContextInstance, input: string) {
return dispatchRuleCommand({
rules: rules.value,
ruleContexts: ruleContexts.value,
addRuleContext,
removeRuleContext,
pushContext,
popContext,
latestContext,
parts,
regions,
} as any, input);
}
return {
parts,
regions,
rules,
ruleContexts,
contexts,
pushContext,
popContext,
latestContext,
registerRule,
unregisterRule,
dispatchCommand,
}
})
/** 创建游戏上下文实<E69687>?*/
export function createGameContext(root: Context = { type: 'game' }) {
return new GameContext(root);
}
export type GameContextInstance = ReturnType<typeof createGameContext>;

49
src/core/game.ts Normal file
View File

@ -0,0 +1,49 @@
import {createEntityCollection} from "../utils/entity";
import {Part} from "./part";
import {Region} from "./region";
import {
Command,
CommandRegistry,
type CommandRunner, CommandRunnerContext,
CommandRunnerContextExport, CommandSchema,
createCommandRunnerContext, parseCommandSchema,
PromptEvent
} from "../utils/command";
import {AsyncQueue} from "../utils/async-queue";
export interface IGameContext {
parts: ReturnType<typeof createEntityCollection<Part>>;
regions: ReturnType<typeof createEntityCollection<Region>>;
commands: CommandRunnerContextExport<IGameContext>;
prompts: AsyncQueue<PromptEvent>;
}
/**
* creates a game context.
* expects a command registry already registered with commands.
* @param commandRegistry
*/
export function createGameContext(commandRegistry: CommandRegistry<IGameContext>) {
const parts = createEntityCollection<Part>();
const regions = createEntityCollection<Region>();
const ctx: IGameContext = {
parts,
regions,
commands: null!,
prompts: new AsyncQueue(),
};
ctx.commands = createCommandRunnerContext(commandRegistry, ctx);
ctx.commands.on('prompt', (prompt: PromptEvent) => ctx.prompts.push(prompt));
return ctx;
}
export function createGameCommand<TResult>(
schema: CommandSchema | string,
run: (this: CommandRunnerContext<IGameContext>, command: Command) => Promise<TResult>
): CommandRunner<IGameContext, TResult> {
return {
schema: typeof schema === 'string' ? parseCommandSchema(schema) : schema,
run,
};
}

233
src/core/rule.ts
View File

@ -1,233 +0,0 @@
import {Command, CommandSchema, parseCommand, parseCommandSchema, applyCommandSchema} from "../utils/command";
export type RuleState = 'running' | 'yielded' | 'waiting' | 'invoking' | 'done';
export type SchemaYield = { type: 'schema'; value: string | CommandSchema };
export type InvokeYield = { type: 'invoke'; rule: string; command: Command };
export type RuleYield = SchemaYield | InvokeYield;
export type RuleContext<T = unknown> = {
type: string;
schema?: CommandSchema;
generator: Generator<RuleYield, T, Command | RuleContext<unknown>>;
parent?: RuleContext<unknown>;
children: RuleContext<unknown>[];
state: RuleState;
resolution?: T;
}
export type RuleDef<T = unknown, H extends RuleEngineHost = RuleEngineHost> = {
schema: CommandSchema;
create: (this: H, cmd: Command) => Generator<RuleYield, T, Command | RuleContext<unknown>>;
};
export type RuleRegistry = Map<string, RuleDef<unknown, RuleEngineHost>>;
export type RuleEngineHost = {
rules: RuleRegistry;
ruleContexts: RuleContext<unknown>[];
addRuleContext: (ctx: RuleContext<unknown>) => void;
removeRuleContext: (ctx: RuleContext<unknown>) => void;
};
export function createRule<T, H extends RuleEngineHost = RuleEngineHost>(
schemaStr: string,
fn: (this: H, cmd: Command) => Generator<RuleYield, T, Command | RuleContext<unknown>>
): RuleDef<T, H> {
return {
schema: parseCommandSchema(schemaStr, ''),
create: fn as RuleDef<T, H>['create'],
};
}
function parseYieldedSchema(value: string | CommandSchema): CommandSchema {
if (typeof value === 'string') {
return parseCommandSchema(value, '');
}
return value;
}
function addContextToHost(host: RuleEngineHost, ctx: RuleContext<unknown>) {
host.addRuleContext(ctx);
}
function discardChildren(host: RuleEngineHost, parent: RuleContext<unknown>) {
for (const child of parent.children) {
host.removeRuleContext(child);
}
parent.children = [];
parent.state = 'yielded';
}
function commandMatchesSchema(command: Command, schema: CommandSchema): boolean {
const requiredParams = schema.params.filter(p => p.required);
const variadicParam = schema.params.find(p => p.variadic);
if (command.params.length < requiredParams.length) {
return false;
}
if (!variadicParam && command.params.length > schema.params.length) {
return false;
}
const requiredOptions = Object.values(schema.options).filter(o => o.required);
for (const opt of requiredOptions) {
const hasOption = opt.name in command.options || (opt.short && opt.short in command.options);
if (!hasOption) {
return false;
}
}
return true;
}
function applySchemaToCommand(command: Command, schema: CommandSchema): Command {
return applyCommandSchema(command, schema).command;
}
function findYieldedContext(contexts: RuleContext<unknown>[]): RuleContext<unknown> | undefined {
for (let i = contexts.length - 1; i >= 0; i--) {
const ctx = contexts[i];
if (ctx.state === 'yielded') {
return ctx;
}
}
return undefined;
}
function createContext<T>(
command: Command,
ruleDef: RuleDef<T>,
host: RuleEngineHost,
parent?: RuleContext<unknown>
): RuleContext<T> {
return {
type: ruleDef.schema.name,
schema: undefined,
generator: ruleDef.create.call(host, command),
parent,
children: [],
state: 'running',
resolution: undefined,
};
}
function handleGeneratorResult<T>(
host: RuleEngineHost,
ctx: RuleContext<T>,
result: IteratorResult<RuleYield, T>
): RuleContext<unknown> | undefined {
if (result.done) {
ctx.resolution = result.value;
ctx.state = 'done';
return resumeParentAfterChildComplete(host, ctx as RuleContext<unknown>);
}
const yielded = result.value;
if (yielded.type === 'invoke') {
const childRuleDef = host.rules.get(yielded.rule);
if (childRuleDef) {
ctx.state = 'invoking';
return invokeChildRule(host, yielded.rule, yielded.command, ctx as RuleContext<unknown>);
} else {
ctx.schema = parseYieldedSchema({ name: '', params: [], options: {}, flags: {} });
ctx.state = 'yielded';
}
} else {
ctx.schema = parseYieldedSchema(yielded.value);
ctx.state = 'yielded';
}
return undefined;
}
function stepGenerator<T>(
host: RuleEngineHost,
ctx: RuleContext<T>
): RuleContext<T> {
const result = ctx.generator.next();
const resumed = handleGeneratorResult(host, ctx, result);
if (resumed) return resumed as RuleContext<T>;
return ctx;
}
function invokeChildRule<T>(
host: RuleEngineHost,
ruleName: string,
command: Command,
parent: RuleContext<unknown>
): RuleContext<T> {
const ruleDef = host.rules.get(ruleName)!;
const ctx = createContext(command, ruleDef, host, parent);
parent.children.push(ctx as RuleContext<unknown>);
addContextToHost(host, ctx as RuleContext<unknown>);
return stepGenerator(host, ctx) as RuleContext<T>;
}
function resumeParentAfterChildComplete(
host: RuleEngineHost,
childCtx: RuleContext<unknown>
): RuleContext<unknown> | undefined {
const parent = childCtx.parent;
if (!parent || parent.state !== 'invoking') return undefined;
parent.children = parent.children.filter(c => c !== childCtx);
const result = parent.generator.next(childCtx);
const resumed = handleGeneratorResult(host, parent, result);
if (resumed) return resumed;
return parent;
}
function invokeRule<T>(
host: RuleEngineHost,
command: Command,
ruleDef: RuleDef<T>,
parent?: RuleContext<unknown>
): RuleContext<T> {
const ctx = createContext(command, ruleDef, host, parent);
if (parent) {
discardChildren(host, parent);
parent.children.push(ctx as RuleContext<unknown>);
parent.state = 'waiting';
}
addContextToHost(host, ctx as RuleContext<unknown>);
return stepGenerator(host, ctx);
}
function feedYieldedContext(
host: RuleEngineHost,
ctx: RuleContext<unknown>,
command: Command
): RuleContext<unknown> {
const typedCommand = applySchemaToCommand(command, ctx.schema!);
const result = ctx.generator.next(typedCommand);
const resumed = handleGeneratorResult(host, ctx, result);
return resumed ?? ctx;
}
export function dispatchCommand(host: RuleEngineHost, input: string): RuleContext<unknown> | undefined {
const command = parseCommand(input);
const matchedRule = host.rules.get(command.name);
if (matchedRule) {
const typedCommand = applySchemaToCommand(command, matchedRule.schema);
const parent = findYieldedContext(host.ruleContexts);
return invokeRule(host, typedCommand, matchedRule, parent);
}
for (let i = host.ruleContexts.length - 1; i >= 0; i--) {
const ctx = host.ruleContexts[i];
if (ctx.state === 'yielded' && ctx.schema && commandMatchesSchema(command, ctx.schema)) {
return feedYieldedContext(host, ctx, command);
}
}
return undefined;
}

11
src/index.ts
View File

@ -4,8 +4,8 @@
*/ */
// Core types // Core types
export type { Context } from './core/context'; export type { IGameContext } from './core/game';
export { GameContext, createGameContext } from './core/context'; export { createGameContext } from './core/game';
export type { Part } from './core/part'; export type { Part } from './core/part';
export { flip, flipTo, roll } from './core/part'; export { flip, flipTo, roll } from './core/part';
@ -13,15 +13,12 @@ export { flip, flipTo, roll } from './core/part';
export type { Region, RegionAxis } from './core/region'; export type { Region, RegionAxis } from './core/region';
export { applyAlign, shuffle } from './core/region'; export { applyAlign, shuffle } from './core/region';
export type { RuleContext, RuleState, RuleDef, RuleRegistry } from './core/rule';
export { createRule, dispatchCommand } from './core/rule';
// Utils // Utils
export type { Command, CommandSchema, CommandParamSchema, CommandOptionSchema, CommandFlagSchema } from './utils/command'; export type { Command, CommandSchema, CommandParamSchema, CommandOptionSchema, CommandFlagSchema } from './utils/command';
export { parseCommand, parseCommandSchema, validateCommand, parseCommandWithSchema, applyCommandSchema } from './utils/command'; export { parseCommand, parseCommandSchema, validateCommand, parseCommandWithSchema, applyCommandSchema } from './utils/command';
export type { CommandRunner, CommandRunnerHandler, CommandRegistry, CommandRunnerContext } from './utils/command'; export type { CommandRunner, CommandRunnerHandler, CommandRunnerContext, PromptEvent, CommandRunnerEvents } from './utils/command';
export { createCommandRegistry, registerCommand, unregisterCommand, hasCommand, getCommand, runCommand, createCommandRunnerContext } from './utils/command'; export { createCommandRegistry, registerCommand, unregisterCommand, hasCommand, getCommand, runCommand, runCommandParsed, createCommandRunnerContext, type CommandRegistry, type CommandRunnerContextExport } from './utils/command';
export type { Entity, EntityAccessor } from './utils/entity'; export type { Entity, EntityAccessor } from './utils/entity';
export { createEntityCollection } from './utils/entity'; export { createEntityCollection } from './utils/entity';

135
src/samples/tic-tac-toe.ts
View File

@ -1,13 +1,9 @@
import { GameContextInstance } from '../core/context'; import { IGameContext } from '../core/game';
import type { RuleEngineHost, RuleContext } from '../core/rule'; import {CommandRegistry, CommandRunner, registerCommand} from '../utils/command';
import { createRule, type InvokeYield, type SchemaYield } from '../core/rule';
import type { Command } from '../utils/command';
import type { Part } from '../core/part'; import type { Part } from '../core/part';
import type { Region } from '../core/region'; import {createGameCommand} from "../core/game";
import type { Context } from '../core/context';
export type TicTacToeState = Context & { export type TicTacToeState = {
type: 'tic-tac-toe';
currentPlayer: 'X' | 'O'; currentPlayer: 'X' | 'O';
winner: 'X' | 'O' | 'draw' | null; winner: 'X' | 'O' | 'draw' | null;
moveCount: number; moveCount: number;
@ -17,37 +13,18 @@ type TurnResult = {
winner: 'X' | 'O' | 'draw' | null; winner: 'X' | 'O' | 'draw' | null;
}; };
type TicTacToeHost = RuleEngineHost & { export function getBoardRegion(host: IGameContext) {
pushContext: (context: Context) => any;
latestContext: <T>(type: string) => { value: T } | undefined;
regions: { add: (...entities: any[]) => void; get: (id: string) => { value: { children: any[] } } };
parts: { add: (...entities: any[]) => void; get: (id: string) => any; collection: { value: Record<string, { value: Part }> } };
};
function getBoardRegion(host: TicTacToeHost) {
return host.regions.get('board'); return host.regions.get('board');
} }
function isCellOccupied(host: TicTacToeHost, row: number, col: number): boolean { export function isCellOccupied(host: IGameContext, row: number, col: number): boolean {
const board = getBoardRegion(host); const board = getBoardRegion(host);
return board.value.children.some( return board.value.children.some(
(child: { value: { position: number[] } }) => child.value.position[0] === row && child.value.position[1] === col (child: { value: { position: number[] } }) => child.value.position[0] === row && child.value.position[1] === col
); );
} }
function checkWinner(host: TicTacToeHost): 'X' | 'O' | 'draw' | null { export function hasWinningLine(positions: number[][]): boolean {
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);
const oPositions = parts.filter((_: Part, i: number) => i % 2 === 1).map((p: Part) => p.position);
if (hasWinningLine(xPositions)) return 'X';
if (hasWinningLine(oPositions)) return 'O';
return null;
}
function hasWinningLine(positions: number[][]): boolean {
const lines = [ const lines = [
[[0, 0], [0, 1], [0, 2]], [[0, 0], [0, 1], [0, 2]],
[[1, 0], [1, 1], [1, 2]], [[1, 0], [1, 1], [1, 2]],
@ -66,7 +43,19 @@ function hasWinningLine(positions: number[][]): boolean {
); );
} }
function placePiece(host: TicTacToeHost, row: number, col: number, moveCount: number) { export function checkWinner(host: IGameContext): '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);
const oPositions = parts.filter((_: Part, i: number) => i % 2 === 1).map((p: Part) => p.position);
if (hasWinningLine(xPositions)) return 'X';
if (hasWinningLine(oPositions)) return 'O';
return null;
}
export function placePiece(host: IGameContext, row: number, col: number, moveCount: number) {
const board = getBoardRegion(host); const board = getBoardRegion(host);
const piece: Part = { const piece: Part = {
id: `piece-${moveCount}`, id: `piece-${moveCount}`,
@ -79,84 +68,58 @@ function placePiece(host: TicTacToeHost, row: number, col: number, moveCount: nu
board.value.children.push(host.parts.get(piece.id)); board.value.children.push(host.parts.get(piece.id));
} }
const playSchema: SchemaYield = { type: 'schema', value: 'play <player> <row:number> <col:number>' }; const setup = createGameCommand(
'setup',
export function createSetupRule() { async function() {
return createRule('start', function*(this: TicTacToeHost) { this.context.regions.add({
this.pushContext({
type: 'tic-tac-toe',
currentPlayer: 'X',
winner: null,
moveCount: 0,
} as TicTacToeState);
this.regions.add({
id: 'board', id: 'board',
axes: [ axes: [
{ name: 'x', min: 0, max: 2 }, { name: 'x', min: 0, max: 2 },
{ name: 'y', min: 0, max: 2 }, { name: 'y', min: 0, max: 2 },
], ],
children: [], children: [],
} as Region); });
let currentPlayer: 'X' | 'O' = 'X'; let currentPlayer: 'X' | 'O' = 'X';
let turnResult: TurnResult | undefined; let turnResult: TurnResult | undefined;
let turn = 1;
while (true) { while (true) {
const yieldValue: InvokeYield = { const turnOutput = await this.run<TurnResult>(`turn ${currentPlayer} ${turn++}`);
type: 'invoke', if (!turnOutput.success) throw new Error(turnOutput.error);
rule: 'turn', turnResult = turnOutput?.result.winner;
command: { name: 'turn', params: [currentPlayer], flags: {}, options: {} } as Command, if (turnResult) break;
};
const ctx = yield yieldValue;
turnResult = (ctx as RuleContext<TurnResult>).resolution;
if (turnResult?.winner) break;
currentPlayer = currentPlayer === 'X' ? 'O' : 'X'; currentPlayer = currentPlayer === 'X' ? 'O' : 'X';
const state = this.latestContext<TicTacToeState>('tic-tac-toe')!;
state.value.currentPlayer = currentPlayer;
} }
const state = this.latestContext<TicTacToeState>('tic-tac-toe')!; return { winner: turnResult };
state.value.winner = turnResult?.winner ?? null; }
return { winner: state.value.winner }; )
});
}
export function createTurnRule() { const turn = createGameCommand(
return createRule('turn <player>', function*(this: TicTacToeHost, cmd) { 'turn <player> <turn:number>',
async function(cmd) {
const [turnPlayer, turnNumber] = cmd.params as [string, number];
while (true) { while (true) {
const received = yield playSchema; const playCmd = await this.prompt('play <player> <row:number> <col:number>');
if ('resolution' in received) continue; const [player, row, col] = playCmd.params as [string, number, number];
if(turnPlayer !== player) continue;
const playCmd = received as Command;
if (playCmd.name !== 'play') continue;
const row = playCmd.params[1] as number;
const col = playCmd.params[2] as number;
if (isNaN(row) || isNaN(col) || row < 0 || row > 2 || col < 0 || col > 2) continue; if (isNaN(row) || isNaN(col) || row < 0 || row > 2 || col < 0 || col > 2) continue;
if (isCellOccupied(this, row, col)) continue; if (isCellOccupied(this.context, row, col)) continue;
const state = this.latestContext<TicTacToeState>('tic-tac-toe')!; placePiece(this.context, row, col, turnNumber);
if (state.value.winner) continue;
placePiece(this, row, col, state.value.moveCount); const winner = checkWinner(this.context);
state.value.moveCount++;
const winner = checkWinner(this);
if (winner) return { winner }; if (winner) return { winner };
if (state.value.moveCount >= 9) return { winner: 'draw' as const }; if (turnNumber >= 9) return { winner: 'draw' as const };
} }
}); }
} );
export function registerTicTacToeRules(game: GameContextInstance) { export function registerTicTacToeCommands(registry: CommandRegistry<IGameContext>) {
game.registerRule('start', createSetupRule()); registerCommand(registry, setup);
game.registerRule('turn', createTurnRule()); registerCommand(registry, turn);
}
export function startTicTacToe(game: GameContextInstance) {
game.dispatchCommand('start');
} }

32
src/utils/async-queue.ts Normal file
View File

@ -0,0 +1,32 @@
export class AsyncQueue<T> {
private items: T[] = [];
private resolvers: ((value: T) => void)[] = [];
push(item: T): void {
if (this.resolvers.length > 0) {
const resolve = this.resolvers.shift()!;
resolve(item);
} else {
this.items.push(item);
}
}
pushAll(items: Iterable<T>): void {
for (const item of items) {
this.push(item);
}
}
async pop(): Promise<T> {
if (this.items.length > 0) {
return this.items.shift()!;
}
return new Promise<T>((resolve) => {
this.resolvers.push(resolve);
});
}
get length(): number {
return this.items.length - this.resolvers.length;
}
}

57
src/utils/command/command-registry.ts
View File

@ -1,7 +1,7 @@
import type { Command } from './types.js'; import type { Command, CommandSchema } from './types.js';
import type { CommandRunner, CommandRunnerContext, PromptEvent } from './command-runner.js'; import type {CommandResult, CommandRunner, CommandRunnerContext, PromptEvent} from './command-runner.js';
import { parseCommand } from './command-parse.js'; import { parseCommand } from './command-parse.js';
import { applyCommandSchema } from './command-apply.js'; import { applyCommandSchema } from './command-validate.js';
import { parseCommandSchema } from './schema-parse.js'; import { parseCommandSchema } from './schema-parse.js';
export type CommandRegistry<TContext> = Map<string, CommandRunner<TContext, unknown>>; export type CommandRegistry<TContext> = Map<string, CommandRunner<TContext, unknown>>;
@ -42,6 +42,10 @@ type Listener = (e: PromptEvent) => void;
export type CommandRunnerContextExport<TContext> = CommandRunnerContext<TContext> & { export type CommandRunnerContextExport<TContext> = CommandRunnerContext<TContext> & {
registry: CommandRegistry<TContext>; registry: CommandRegistry<TContext>;
_activePrompt: PromptEvent | null;
_resolvePrompt: (command: Command) => void;
_rejectPrompt: (error: Error) => void;
_pendingInput: string | null;
}; };
export function createCommandRunnerContext<TContext>( export function createCommandRunnerContext<TContext>(
@ -58,9 +62,26 @@ export function createCommandRunnerContext<TContext>(
listeners.delete(listener); listeners.delete(listener);
}; };
let activePrompt: PromptEvent | null = null;
const resolvePrompt = (command: Command) => {
if (activePrompt) {
activePrompt.resolve(command);
activePrompt = null;
}
};
const rejectPrompt = (error: Error) => {
if (activePrompt) {
activePrompt.reject(error);
activePrompt = null;
}
};
const prompt = (schema: Parameters<CommandRunnerContext<TContext>['prompt']>[0]): Promise<Command> => { const prompt = (schema: Parameters<CommandRunnerContext<TContext>['prompt']>[0]): Promise<Command> => {
const resolvedSchema = typeof schema === 'string' ? parseCommandSchema(schema) : schema; const resolvedSchema = typeof schema === 'string' ? parseCommandSchema(schema) : schema;
return new Promise((resolve, reject) => { return new Promise((resolve, reject) => {
activePrompt = { schema: resolvedSchema, resolve, reject };
const event: PromptEvent = { schema: resolvedSchema, resolve, reject }; const event: PromptEvent = { schema: resolvedSchema, resolve, reject };
for (const listener of listeners) { for (const listener of listeners) {
listener(event); listener(event);
@ -71,13 +92,21 @@ export function createCommandRunnerContext<TContext>(
const runnerCtx: CommandRunnerContextExport<TContext> = { const runnerCtx: CommandRunnerContextExport<TContext> = {
registry, registry,
context, context,
run: (input: string) => runCommandWithContext(registry, runnerCtx, input), run: <T=unknown>(input: string) => runCommandWithContext(runnerCtx, input) as Promise<CommandResult<T>>,
runParsed: (command: Command) => runCommandParsedWithContext(registry, runnerCtx, command), runParsed: (command: Command) => runCommandParsedWithContext(runnerCtx, command),
prompt, prompt,
on, on,
off, off,
_activePrompt: null,
_resolvePrompt: resolvePrompt,
_rejectPrompt: rejectPrompt,
_pendingInput: null,
}; };
Object.defineProperty(runnerCtx, '_activePrompt', {
get: () => activePrompt,
});
return runnerCtx; return runnerCtx;
} }
@ -85,7 +114,7 @@ async function executeWithRunnerContext<TContext>(
runnerCtx: CommandRunnerContextExport<TContext>, runnerCtx: CommandRunnerContextExport<TContext>,
runner: CommandRunner<TContext, unknown>, runner: CommandRunner<TContext, unknown>,
command: Command command: Command
): Promise<{ success: true; result: unknown } | { success: false; error: string }> { ): Promise<CommandResult> {
try { try {
const result = await runner.run.call(runnerCtx, command); const result = await runner.run.call(runnerCtx, command);
return { success: true, result }; return { success: true, result };
@ -99,35 +128,33 @@ export async function runCommand<TContext>(
registry: CommandRegistry<TContext>, registry: CommandRegistry<TContext>,
context: TContext, context: TContext,
input: string input: string
): Promise<{ success: true; result: unknown } | { success: false; error: string }> { ): Promise<CommandResult> {
const runnerCtx = createCommandRunnerContext(registry, context); const runnerCtx = createCommandRunnerContext(registry, context);
return await runCommandWithContext(registry, runnerCtx, input); return await runCommandWithContext(runnerCtx, input);
} }
async function runCommandWithContext<TContext>( async function runCommandWithContext<TContext>(
registry: CommandRegistry<TContext>,
runnerCtx: CommandRunnerContextExport<TContext>, runnerCtx: CommandRunnerContextExport<TContext>,
input: string input: string
): Promise<{ success: true; result: unknown } | { success: false; error: string }> { ): Promise<{ success: true; result: unknown } | { success: false; error: string }> {
const command = parseCommand(input); const command = parseCommand(input);
return await runCommandParsedWithContext(registry, runnerCtx, command); return await runCommandParsedWithContext(runnerCtx, command);
} }
export async function runCommandParsed<TContext>( export async function runCommandParsed<TContext>(
registry: CommandRegistry<TContext>, registry: CommandRegistry<TContext>,
context: TContext, context: TContext,
command: Command command: Command
): Promise<{ success: true; result: unknown } | { success: false; error: string }> { ): Promise<CommandResult> {
const runnerCtx = createCommandRunnerContext(registry, context); const runnerCtx = createCommandRunnerContext(registry, context);
return await runCommandParsedWithContext(registry, runnerCtx, command); return await runCommandParsedWithContext(runnerCtx, command);
} }
async function runCommandParsedWithContext<TContext>( async function runCommandParsedWithContext<TContext>(
registry: CommandRegistry<TContext>,
runnerCtx: CommandRunnerContextExport<TContext>, runnerCtx: CommandRunnerContextExport<TContext>,
command: Command command: Command
): Promise<{ success: true; result: unknown } | { success: false; error: string }> { ): Promise<CommandResult> {
const runner = registry.get(command.name); const runner = runnerCtx.registry.get(command.name);
if (!runner) { if (!runner) {
return { success: false, error: `Unknown command: ${command.name}` }; return { success: false, error: `Unknown command: ${command.name}` };
} }

10
src/utils/command/command-runner.ts
View File

@ -10,9 +10,17 @@ export type CommandRunnerEvents = {
prompt: PromptEvent; prompt: PromptEvent;
}; };
export type CommandResult<T=unknown> = {
success: true;
result: T;
} | {
success: false;
error: string;
}
export type CommandRunnerContext<TContext> = { export type CommandRunnerContext<TContext> = {
context: TContext; context: TContext;
run: (input: string) => Promise<{ success: true; result: unknown } | { success: false; error: string }>; run: <T=unknown>(input: string) => Promise<CommandResult<T>>;
runParsed: (command: Command) => Promise<{ success: true; result: unknown } | { success: false; error: string }>; runParsed: (command: Command) => Promise<{ success: true; result: unknown } | { success: false; error: string }>;
prompt: (schema: CommandSchema | string) => Promise<Command>; prompt: (schema: CommandSchema | string) => Promise<Command>;
on: <T extends keyof CommandRunnerEvents>(event: T, listener: (e: CommandRunnerEvents[T]) => void) => void; on: <T extends keyof CommandRunnerEvents>(event: T, listener: (e: CommandRunnerEvents[T]) => void) => void;

126
tests/core/game.test.ts Normal file
View File

@ -0,0 +1,126 @@
import { describe, it, expect } from 'vitest';
import { createGameContext, createGameCommand } from '../../src/core/game';
import { createCommandRegistry, parseCommandSchema, type CommandRegistry } from '../../src/utils/command';
import type { IGameContext } from '../../src/core/game';
describe('createGameContext', () => {
it('should create a game context with empty parts and regions', () => {
const registry = createCommandRegistry<IGameContext>();
const ctx = createGameContext(registry);
expect(ctx.parts.collection.value).toEqual({});
expect(ctx.regions.collection.value).toEqual({});
});
it('should wire commands to the context', () => {
const registry = createCommandRegistry<IGameContext>();
const ctx = createGameContext(registry);
expect(ctx.commands).not.toBeNull();
expect(ctx.commands.registry).toBe(registry);
expect(ctx.commands.context).toBe(ctx);
});
it('should forward prompt events to the prompts queue', async () => {
const registry = createCommandRegistry<IGameContext>();
const ctx = createGameContext(registry);
const schema = parseCommandSchema('test <value>');
registry.set('test', {
schema,
run: async function () {
return this.prompt('prompt <answer>');
},
});
const runPromise = ctx.commands.run('test hello');
await new Promise((r) => setTimeout(r, 0));
const promptEvent = await ctx.prompts.pop();
expect(promptEvent).not.toBeNull();
expect(promptEvent.schema.name).toBe('prompt');
promptEvent.resolve({ name: 'prompt', params: ['yes'], options: {}, flags: {} });
const result = await runPromise;
expect(result.success).toBe(true);
if (result.success) {
expect((result.result as any).params[0]).toBe('yes');
}
});
});
describe('createGameCommand', () => {
it('should create a command from a string schema', () => {
const cmd = createGameCommand('test <a>', async function () {
return 1;
});
expect(cmd.schema.name).toBe('test');
expect(cmd.schema.params[0].name).toBe('a');
expect(cmd.schema.params[0].required).toBe(true);
});
it('should create a command from a CommandSchema object', () => {
const schema = parseCommandSchema('foo <x> [y]');
const cmd = createGameCommand(schema, async function () {
return 2;
});
expect(cmd.schema.name).toBe('foo');
expect(cmd.schema.params[0].name).toBe('x');
expect(cmd.schema.params[0].required).toBe(true);
expect(cmd.schema.params[1].name).toBe('y');
expect(cmd.schema.params[1].required).toBe(false);
});
it('should run a command with access to game context', async () => {
const registry = createCommandRegistry<IGameContext>();
const ctx = createGameContext(registry);
const addRegion = createGameCommand('add-region <id>', async function (cmd) {
const id = cmd.params[0] as string;
this.context.regions.add({ id, axes: [], children: [] });
return id;
});
registry.set('add-region', addRegion);
const result = await ctx.commands.run('add-region board');
expect(result.success).toBe(true);
if (result.success) {
expect(result.result).toBe('board');
}
expect(ctx.regions.get('board')).not.toBeNull();
});
it('should run a command that adds parts', async () => {
const registry = createCommandRegistry<IGameContext>();
const ctx = createGameContext(registry);
ctx.regions.add({ id: 'zone', axes: [], children: [] });
const addPart = createGameCommand('add-part <id>', async function (cmd) {
const id = cmd.params[0] as string;
const part = {
id,
sides: 1,
side: 0,
region: this.context.regions.get('zone'),
position: [0],
};
this.context.parts.add(part);
return id;
});
registry.set('add-part', addPart);
const result = await ctx.commands.run('add-part piece-1');
expect(result.success).toBe(true);
if (result.success) {
expect(result.result).toBe('piece-1');
}
expect(ctx.parts.get('piece-1')).not.toBeNull();
});
});

396
tests/core/rule.test.ts
View File

@ -1,396 +0,0 @@
import { describe, it, expect } from 'vitest';
import { createRule, type RuleContext, type RuleEngineHost } from '../../src/core/rule';
import { createGameContext } from '../../src/core/context';
import type { Command } from '../../src/utils/command';
function isCommand(value: Command | RuleContext<unknown>): value is Command {
return 'name' in value;
}
function schema(value: string | { name: string; params: any[]; options: any[]; flags: any[] }) {
return { type: 'schema' as const, value };
}
describe('Rule System', () => {
function createTestGame() {
const game = createGameContext();
return game;
}
describe('createRule', () => {
it('should create a rule definition with parsed schema', () => {
const rule = createRule('<from> <to> [--force]', function*(cmd) {
return { from: cmd.params[0], to: cmd.params[1] };
});
expect(rule.schema.params).toHaveLength(2);
expect(rule.schema.params[0].name).toBe('from');
expect(rule.schema.params[0].required).toBe(true);
expect(rule.schema.params[1].name).toBe('to');
expect(rule.schema.params[1].required).toBe(true);
expect(Object.keys(rule.schema.flags)).toHaveLength(1);
expect(rule.schema.flags.force.name).toBe('force');
});
it('should create a generator when called', () => {
const game = createTestGame();
const rule = createRule('<target>', function*(cmd) {
return cmd.params[0];
});
const gen = rule.create.call(game as unknown as RuleEngineHost, { name: 'test', params: ['card1'], flags: {}, options: {} });
const result = gen.next();
expect(result.done).toBe(true);
expect(result.value).toBe('card1');
});
});
describe('dispatchCommand - rule invocation', () => {
it('should invoke a registered rule and yield schema', () => {
const game = createTestGame();
game.registerRule('move', createRule('<from> <to>', function*(cmd) {
yield schema({ name: '', params: [], options: [], flags: [] });
return { moved: cmd.params[0] };
}));
const ctx = game.dispatchCommand('move card1 hand');
expect(ctx).toBeDefined();
expect(ctx!.state).toBe('yielded');
expect(ctx!.schema).toBeDefined();
expect(ctx!.resolution).toBeUndefined();
});
it('should complete a rule when final command matches yielded schema', () => {
const game = createTestGame();
game.registerRule('move', createRule('<from> <to>', function*(cmd) {
const confirm = yield schema({ name: '', params: [], options: [], flags: [] });
const confirmCmd = isCommand(confirm) ? confirm : undefined;
return { moved: cmd.params[0], confirmed: confirmCmd?.name === 'confirm' };
}));
game.dispatchCommand('move card1 hand');
const ctx = game.dispatchCommand('confirm');
expect(ctx).toBeDefined();
expect(ctx!.state).toBe('done');
expect(ctx!.resolution).toEqual({ moved: 'card1', confirmed: true });
});
it('should return undefined when command matches no rule and no yielded context', () => {
const game = createTestGame();
const result = game.dispatchCommand('unknown command');
expect(result).toBeUndefined();
});
it('should pass the initial command to the generator', () => {
const game = createTestGame();
game.registerRule('attack', createRule('<target> [--power: number]', function*(cmd) {
return { target: cmd.params[0], power: cmd.options.power || '1' };
}));
const ctx = game.dispatchCommand('attack goblin --power 5');
expect(ctx!.state).toBe('done');
expect(ctx!.resolution).toEqual({ target: 'goblin', power: 5 });
});
it('should complete immediately if generator does not yield', () => {
const game = createTestGame();
game.registerRule('look', createRule('[--at]', function*() {
return 'looked';
}));
const ctx = game.dispatchCommand('look');
expect(ctx!.state).toBe('done');
expect(ctx!.resolution).toBe('looked');
});
});
describe('dispatchCommand - rule priority', () => {
it('should prioritize new rule invocation over feeding yielded context', () => {
const game = createTestGame();
game.registerRule('move', createRule('<from> <to>', function*(cmd) {
yield schema({ name: '', params: [], options: [], flags: [] });
return { moved: cmd.params[0] };
}));
game.registerRule('confirm', createRule('', function*() {
return 'new confirm rule';
}));
game.dispatchCommand('move card1 hand');
const ctx = game.dispatchCommand('confirm');
expect(ctx!.state).toBe('done');
expect(ctx!.resolution).toBe('new confirm rule');
expect(ctx!.type).toBe('');
});
});
describe('dispatchCommand - fallback to yielded context', () => {
it('should feed a yielded context when command does not match any rule', () => {
const game = createTestGame();
game.registerRule('move', createRule('<from> <to>', function*(cmd) {
const response = yield schema({ name: '', params: [], options: [], flags: [] });
const rcmd = isCommand(response) ? response : undefined;
return { moved: cmd.params[0], response: rcmd?.name };
}));
game.dispatchCommand('move card1 hand');
const ctx = game.dispatchCommand('yes');
expect(ctx!.state).toBe('done');
expect(ctx!.resolution).toEqual({ moved: 'card1', response: 'yes' });
});
it('should skip non-matching commands for yielded context', () => {
const game = createTestGame();
game.registerRule('move', createRule('<from> <to>', function*(cmd) {
const response = yield schema('<item>');
const rcmd = isCommand(response) ? response : undefined;
return { response: rcmd?.params[0] };
}));
game.dispatchCommand('move card1 hand');
const ctx = game.dispatchCommand('goblin');
expect(ctx).toBeUndefined();
});
it('should validate command against yielded schema', () => {
const game = createTestGame();
game.registerRule('trade', createRule('<from> <to>', function*(cmd) {
const response = yield schema('<item> [amount: number]');
const rcmd = isCommand(response) ? response : undefined;
return { traded: rcmd?.params[0] };
}));
game.dispatchCommand('trade player1 player2');
const ctx = game.dispatchCommand('offer gold 5');
expect(ctx!.state).toBe('done');
expect(ctx!.resolution).toEqual({ traded: 'gold' });
});
});
describe('dispatchCommand - deepest context first', () => {
it('should feed the deepest yielded context', () => {
const game = createTestGame();
game.registerRule('parent', createRule('<action>', function*() {
yield schema({ name: '', params: [], options: [], flags: [] });
return 'parent done';
}));
game.registerRule('child', createRule('<target>', function*() {
yield schema({ name: '', params: [], options: [], flags: [] });
return 'child done';
}));
game.dispatchCommand('parent start');
game.dispatchCommand('child target1');
const ctx = game.dispatchCommand('grandchild_cmd');
expect(ctx!.state).toBe('done');
expect(ctx!.resolution).toBe('child done');
});
});
describe('nested rule invocations', () => {
it('should link child to parent', () => {
const game = createTestGame();
game.registerRule('parent', createRule('<action>', function*() {
yield schema('child_cmd');
return 'parent done';
}));
game.registerRule('child_cmd', createRule('<target>', function*() {
return 'child done';
}));
game.dispatchCommand('parent start');
const parentCtx = game.ruleContexts.value[0];
game.dispatchCommand('child_cmd target1');
expect(parentCtx.state).toBe('waiting');
const childCtx = game.ruleContexts.value[1];
expect(childCtx.parent).toBe(parentCtx);
expect(parentCtx.children).toContain(childCtx);
});
it('should discard previous children when a new child is invoked', () => {
const game = createTestGame();
game.registerRule('parent', createRule('<action>', function*() {
yield schema('child_a | child_b');
return 'parent done';
}));
game.registerRule('child_a', createRule('<target>', function*() {
return 'child_a done';
}));
game.registerRule('child_b', createRule('<target>', function*() {
return 'child_b done';
}));
game.dispatchCommand('parent start');
game.dispatchCommand('child_a target1');
expect(game.ruleContexts.value.length).toBe(2);
const oldParent = game.ruleContexts.value[0];
expect(oldParent.children).toHaveLength(1);
game.dispatchCommand('parent start');
game.dispatchCommand('child_b target2');
const newParent = game.ruleContexts.value[2];
expect(newParent.children).toHaveLength(1);
expect(newParent.children[0].resolution).toBe('child_b done');
});
});
describe('context tracking', () => {
it('should track rule contexts in ruleContexts signal', () => {
const game = createTestGame();
game.registerRule('test', createRule('<arg>', function*() {
yield schema({ name: '', params: [], options: [], flags: [] });
return 'done';
}));
expect(game.ruleContexts.value.length).toBe(0);
game.dispatchCommand('test arg1');
expect(game.ruleContexts.value.length).toBe(1);
expect(game.ruleContexts.value[0].state).toBe('yielded');
});
});
describe('error handling', () => {
it('should leave context in place when generator throws', () => {
const game = createTestGame();
game.registerRule('failing', createRule('<arg>', function*() {
throw new Error('rule error');
}));
expect(() => game.dispatchCommand('failing arg1')).toThrow('rule error');
expect(game.ruleContexts.value.length).toBe(1);
});
it('should leave children in place when child generator throws', () => {
const game = createTestGame();
game.registerRule('parent', createRule('<action>', function*() {
yield schema('child');
return 'parent done';
}));
game.registerRule('child', createRule('<target>', function*() {
throw new Error('child error');
}));
game.dispatchCommand('parent start');
expect(() => game.dispatchCommand('child target1')).toThrow('child error');
expect(game.ruleContexts.value.length).toBe(2);
});
});
describe('schema yielding', () => {
it('should accept a CommandSchema object as yield value', () => {
const game = createTestGame();
const customSchema = {
name: 'custom',
params: [{ name: 'x', required: true, variadic: false }],
options: [],
flags: [],
};
game.registerRule('test', createRule('<arg>', function*() {
const cmd = yield schema(customSchema);
const rcmd = isCommand(cmd) ? cmd : undefined;
return { received: rcmd?.params[0] };
}));
game.dispatchCommand('test val1');
const ctx = game.dispatchCommand('custom hello');
expect(ctx!.state).toBe('done');
expect(ctx!.resolution).toEqual({ received: 'hello' });
});
it('should parse string schema on each yield', () => {
const game = createTestGame();
game.registerRule('multi', createRule('<start>', function*() {
const a = yield schema('<value>');
const b = yield schema('<value>');
const acmd = isCommand(a) ? a : undefined;
const bcmd = isCommand(b) ? b : undefined;
return { a: acmd?.params[0], b: bcmd?.params[0] };
}));
game.dispatchCommand('multi init');
game.dispatchCommand('cmd first');
const ctx = game.dispatchCommand('cmd second');
expect(ctx!.state).toBe('done');
expect(ctx!.resolution).toEqual({ a: 'first', b: 'second' });
});
});
describe('complex flow', () => {
it('should handle a multi-step game flow', () => {
const game = createTestGame();
game.registerRule('start', createRule('<player>', function*(cmd) {
const player = cmd.params[0];
const action = yield schema({ name: '', params: [], options: [], flags: [] });
if (isCommand(action)) {
if (action.name === 'move') {
yield schema('<target>');
} else if (action.name === 'attack') {
yield schema('<target> [--power: number]');
}
}
return { player, action: isCommand(action) ? action.name : '' };
}));
const ctx1 = game.dispatchCommand('start alice');
expect(ctx1!.state).toBe('yielded');
const ctx2 = game.dispatchCommand('attack');
expect(ctx2!.state).toBe('yielded');
const ctx3 = game.dispatchCommand('attack goblin --power 3');
expect(ctx3!.state).toBe('done');
expect(ctx3!.resolution).toEqual({ player: 'alice', action: 'attack' });
});
});
});

407
tests/samples/tic-tac-toe.test.ts
View File

@ -1,127 +1,346 @@
import { describe, it, expect } from 'vitest'; import { describe, it, expect } from 'vitest';
import { createGameContext } from '../../src/core/context'; import { createGameContext } from '../../src/core/game';
import { registerTicTacToeRules, startTicTacToe, type TicTacToeState } from '../../src/samples/tic-tac-toe'; import { createCommandRegistry } from '../../src/utils/command';
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';
describe('Tic-Tac-Toe', () => { function createTestContext() {
function createGame() { const registry = createCommandRegistry<IGameContext>();
const game = createGameContext(); registerTicTacToeCommands(registry);
registerTicTacToeRules(game); const ctx = createGameContext(registry);
return game; return { registry, ctx };
} }
function getBoardState(game: ReturnType<typeof createGame>) { function setupBoard(ctx: IGameContext) {
return game.latestContext<TicTacToeState>('tic-tac-toe')!.value; ctx.regions.add({
} id: 'board',
axes: [
{ name: 'x', min: 0, max: 2 },
{ name: 'y', min: 0, max: 2 },
],
children: [],
});
}
it('should initialize the board and start the game', () => { function addPiece(ctx: IGameContext, id: string, row: number, col: number) {
const game = createGame(); const board = ctx.regions.get('board');
startTicTacToe(game); const part: Part = {
id,
sides: 1,
side: 0,
region: board,
position: [row, col],
};
ctx.parts.add(part);
board.value.children.push(ctx.parts.get(id));
}
const state = getBoardState(game); describe('TicTacToe - helper functions', () => {
expect(state.currentPlayer).toBe('X'); describe('checkWinner', () => {
expect(state.winner).toBeNull(); it('should return null for empty board', () => {
expect(state.moveCount).toBe(0); const { ctx } = createTestContext();
setupBoard(ctx);
const board = game.regions.get('board'); expect(checkWinner(ctx)).toBeNull();
expect(board.value.axes).toHaveLength(2);
expect(board.value.axes[0].name).toBe('x');
expect(board.value.axes[1].name).toBe('y');
}); });
it('should play moves and determine a winner', () => { it('should detect horizontal win for X', () => {
const game = createGame(); const { ctx } = createTestContext();
startTicTacToe(game); setupBoard(ctx);
// X wins with column 0 addPiece(ctx, 'piece-1', 0, 0);
game.dispatchCommand('play X 0 0'); addPiece(ctx, 'piece-2', 1, 0);
game.dispatchCommand('play O 0 1'); addPiece(ctx, 'piece-3', 0, 1);
game.dispatchCommand('play X 1 0'); addPiece(ctx, 'piece-4', 1, 1);
game.dispatchCommand('play O 1 1'); addPiece(ctx, 'piece-5', 0, 2);
game.dispatchCommand('play X 2 0');
const state = getBoardState(game); expect(checkWinner(ctx)).toBe('X');
expect(state.winner).toBe('X');
expect(state.moveCount).toBe(5);
}); });
it('should reject out-of-bounds moves', () => { it('should detect horizontal win for O', () => {
const game = createGame(); const { ctx } = createTestContext();
startTicTacToe(game); setupBoard(ctx);
const beforeCount = getBoardState(game).moveCount; addPiece(ctx, 'piece-1', 2, 0);
addPiece(ctx, 'piece-2', 1, 0);
addPiece(ctx, 'piece-3', 2, 1);
addPiece(ctx, 'piece-4', 1, 1);
addPiece(ctx, 'piece-5', 0, 0);
addPiece(ctx, 'piece-6', 1, 2);
game.dispatchCommand('play X 5 5'); expect(checkWinner(ctx)).toBe('O');
game.dispatchCommand('play X -1 0');
game.dispatchCommand('play X 3 3');
expect(getBoardState(game).moveCount).toBe(beforeCount);
}); });
it('should reject moves on occupied cells', () => { it('should detect vertical win', () => {
const game = createGame(); const { ctx } = createTestContext();
startTicTacToe(game); setupBoard(ctx);
game.dispatchCommand('play X 1 1'); addPiece(ctx, 'piece-1', 0, 0);
expect(getBoardState(game).moveCount).toBe(1); addPiece(ctx, 'piece-2', 0, 1);
addPiece(ctx, 'piece-3', 1, 0);
addPiece(ctx, 'piece-4', 1, 1);
addPiece(ctx, 'piece-5', 2, 0);
// Try to play on the same cell expect(checkWinner(ctx)).toBe('X');
game.dispatchCommand('play O 1 1');
expect(getBoardState(game).moveCount).toBe(1);
}); });
it('should ignore moves after game is over', () => { it('should detect diagonal win (top-left to bottom-right)', () => {
const game = createGame(); const { ctx } = createTestContext();
startTicTacToe(game); setupBoard(ctx);
// X wins addPiece(ctx, 'piece-1', 0, 0);
game.dispatchCommand('play X 0 0'); addPiece(ctx, 'piece-2', 0, 1);
game.dispatchCommand('play O 0 1'); addPiece(ctx, 'piece-3', 1, 1);
game.dispatchCommand('play X 1 0'); addPiece(ctx, 'piece-4', 0, 2);
game.dispatchCommand('play O 1 1'); addPiece(ctx, 'piece-5', 2, 2);
game.dispatchCommand('play X 2 0');
expect(getBoardState(game).winner).toBe('X'); expect(checkWinner(ctx)).toBe('X');
const moveCountAfterWin = getBoardState(game).moveCount;
// Try to play more
game.dispatchCommand('play X 2 1');
game.dispatchCommand('play O 2 2');
expect(getBoardState(game).moveCount).toBe(moveCountAfterWin);
}); });
it('should detect a draw', () => { it('should detect diagonal win (top-right to bottom-left)', () => {
const game = createGame(); const { ctx } = createTestContext();
startTicTacToe(game); setupBoard(ctx);
// Fill board with no winner (cat's game) addPiece(ctx, 'piece-1', 0, 0);
// X: (1,1), (0,2), (2,2), (1,0), (2,1) addPiece(ctx, 'piece-2', 0, 2);
// O: (0,0), (2,0), (0,1), (1,2) addPiece(ctx, 'piece-3', 1, 0);
game.dispatchCommand('play X 1 1'); // X addPiece(ctx, 'piece-4', 1, 1);
game.dispatchCommand('play O 0 0'); // O addPiece(ctx, 'piece-5', 1, 2);
game.dispatchCommand('play X 0 2'); // X addPiece(ctx, 'piece-6', 2, 0);
game.dispatchCommand('play O 2 0'); // O
game.dispatchCommand('play X 2 2'); // X
game.dispatchCommand('play O 0 1'); // O
game.dispatchCommand('play X 1 0'); // X
game.dispatchCommand('play O 1 2'); // O
game.dispatchCommand('play X 2 1'); // X (last move, draw)
const state = getBoardState(game); expect(checkWinner(ctx)).toBe('O');
expect(state.winner).toBe('draw');
expect(state.moveCount).toBe(9);
}); });
it('should place parts on the board region at correct positions', () => { it('should return null for no winner', () => {
const game = createGame(); const { ctx } = createTestContext();
startTicTacToe(game); setupBoard(ctx);
game.dispatchCommand('play X 1 2'); addPiece(ctx, 'piece-1', 0, 0);
addPiece(ctx, 'piece-2', 0, 1);
addPiece(ctx, 'piece-3', 1, 2);
const board = game.regions.get('board'); expect(checkWinner(ctx)).toBeNull();
expect(board.value.children).toHaveLength(1); });
});
const piece = board.value.children[0].value; describe('isCellOccupied', () => {
expect(piece.position).toEqual([1, 2]); it('should return false for empty cell', () => {
const { ctx } = createTestContext();
setupBoard(ctx);
expect(isCellOccupied(ctx, 1, 1)).toBe(false);
});
it('should return true for occupied cell', () => {
const { ctx } = createTestContext();
setupBoard(ctx);
addPiece(ctx, 'piece-1', 1, 1);
expect(isCellOccupied(ctx, 1, 1)).toBe(true);
});
it('should return false for different cell', () => {
const { ctx } = createTestContext();
setupBoard(ctx);
addPiece(ctx, 'piece-1', 0, 0);
expect(isCellOccupied(ctx, 1, 1)).toBe(false);
});
});
describe('placePiece', () => {
it('should add a piece to the board', () => {
const { ctx } = createTestContext();
setupBoard(ctx);
placePiece(ctx, 1, 1, 1);
expect(ctx.parts.get('piece-1')).not.toBeNull();
expect(ctx.parts.get('piece-1').value.position).toEqual([1, 1]);
});
it('should add piece to board region children', () => {
const { ctx } = createTestContext();
setupBoard(ctx);
placePiece(ctx, 0, 0, 1);
const board = ctx.regions.get('board');
expect(board.value.children.length).toBe(1);
});
});
});
describe('TicTacToe - game flow', () => {
it('should have setup and turn commands registered', () => {
const { registry } = createTestContext();
expect(registry.has('setup')).toBe(true);
expect(registry.has('turn')).toBe(true);
});
it('should setup board when setup command runs', async () => {
const { ctx } = createTestContext();
const runPromise = ctx.commands.run('setup');
const promptEvent = await ctx.prompts.pop();
expect(promptEvent).not.toBeNull();
expect(promptEvent.schema.name).toBe('play');
promptEvent.reject(new Error('test end'));
const result = await runPromise;
expect(result.success).toBe(false);
});
it('should accept valid move via turn command', async () => {
const { ctx } = createTestContext();
setupBoard(ctx);
const runPromise = ctx.commands.run('turn X 1');
const promptEvent = await ctx.prompts.pop();
expect(promptEvent).not.toBeNull();
expect(promptEvent.schema.name).toBe('play');
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'));
const result = await runPromise;
expect(result.success).toBe(false);
expect(ctx.parts.get('piece-1')).not.toBeNull();
expect(ctx.parts.get('piece-1').value.position).toEqual([1, 1]);
});
it('should reject move for wrong player and re-prompt', async () => {
const { ctx } = createTestContext();
setupBoard(ctx);
const runPromise = ctx.commands.run('turn X 1');
const promptEvent1 = await ctx.prompts.pop();
promptEvent1.resolve({ name: 'play', params: ['O', 1, 1], options: {}, flags: {} });
const promptEvent2 = await ctx.prompts.pop();
expect(promptEvent2).not.toBeNull();
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'));
const result = await runPromise;
expect(result.success).toBe(false);
});
it('should reject move to occupied cell and re-prompt', async () => {
const { ctx } = createTestContext();
setupBoard(ctx);
addPiece(ctx, 'piece-0', 1, 1);
const runPromise = ctx.commands.run('turn X 1');
const promptEvent1 = await ctx.prompts.pop();
promptEvent1.resolve({ name: 'play', params: ['X', 1, 1], options: {}, flags: {} });
const promptEvent2 = await ctx.prompts.pop();
expect(promptEvent2).not.toBeNull();
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'));
const result = await runPromise;
expect(result.success).toBe(false);
});
it('should detect winner after winning move', async () => {
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: {} });
let promptNext = await ctx.prompts.pop();
promptNext.reject(new Error('next turn'));
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: {} });
promptNext = await ctx.prompts.pop();
promptNext.reject(new Error('next turn'));
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: {} });
promptNext = await ctx.prompts.pop();
promptNext.reject(new Error('next turn'));
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: {} });
promptNext = await ctx.prompts.pop();
promptNext.reject(new Error('next turn'));
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: {} });
result = await runPromise;
expect(result.success).toBe(true);
if (result.success) expect((result.result as any).winner).toBe('X');
});
it('should detect draw after 9 moves', async () => {
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: 'p2', pos: [2, 2] }, // O
{ id: 'p3', pos: [0, 2] }, // X
{ id: 'p4', pos: [2, 0] }, // O
{ id: 'p5', pos: [1, 0] }, // X
{ id: 'p6', pos: [0, 1] }, // O
{ id: 'p7', pos: [2, 1] }, // X
{ id: 'p8', pos: [1, 2] }, // O
];
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: {} });
const result = await runPromise;
expect(result.success).toBe(true);
if (result.success) expect((result.result as any).winner).toBe('draw');
}); });
}); });

104
tests/utils/async-queue.test.ts Normal file
View File

@ -0,0 +1,104 @@
import { describe, it, expect } from 'vitest';
import { AsyncQueue } from '../../src/utils/async-queue';
describe('AsyncQueue', () => {
describe('push', () => {
it('should add item to queue', () => {
const queue = new AsyncQueue<number>();
queue.push(1);
expect(queue.length).toBe(1);
});
});
describe('pop', () => {
it('should return item immediately if queue is not empty', async () => {
const queue = new AsyncQueue<number>();
queue.push(1);
queue.push(2);
const result = await queue.pop();
expect(result).toBe(1);
expect(queue.length).toBe(1);
});
it('should wait for item if queue is empty', async () => {
const queue = new AsyncQueue<number>();
const popPromise = queue.pop();
queue.push(42);
const result = await popPromise;
expect(result).toBe(42);
expect(queue.length).toBe(0);
});
it('should return items in FIFO order', async () => {
const queue = new AsyncQueue<number>();
queue.push(1);
queue.push(2);
queue.push(3);
expect(await queue.pop()).toBe(1);
expect(await queue.pop()).toBe(2);
expect(await queue.pop()).toBe(3);
});
});
describe('pushAll', () => {
it('should add all items to queue', async () => {
const queue = new AsyncQueue<number>();
queue.pushAll([1, 2, 3]);
expect(queue.length).toBe(3);
expect(await queue.pop()).toBe(1);
expect(await queue.pop()).toBe(2);
expect(await queue.pop()).toBe(3);
});
it('should accept any iterable', async () => {
const queue = new AsyncQueue<number>();
queue.pushAll(new Set([10, 20, 30]));
expect(await queue.pop()).toBe(10);
expect(await queue.pop()).toBe(20);
expect(await queue.pop()).toBe(30);
});
it('should resolve waiting pops', async () => {
const queue = new AsyncQueue<number>();
const pop1 = queue.pop();
const pop2 = queue.pop();
queue.pushAll([1, 2]);
expect(await pop1).toBe(1);
expect(await pop2).toBe(2);
expect(queue.length).toBe(0);
});
});
describe('length', () => {
it('should return 0 for empty queue', () => {
const queue = new AsyncQueue<number>();
expect(queue.length).toBe(0);
});
it('should reflect pending consumers as negative', () => {
const queue = new AsyncQueue<number>();
queue.pop(); // no await, so it's pending
expect(queue.length).toBe(-1);
});
it('should update after push and pop', async () => {
const queue = new AsyncQueue<number>();
queue.push(1);
queue.push(2);
expect(queue.length).toBe(2);
await queue.pop();
expect(queue.length).toBe(1);
});
});
});