boardgame-core/src/utils/command/command-runner.ts

import type { Command, CommandSchema } from './types';
import { parseCommand } from './command-parse';
import { applyCommandSchema } from './command-validate';

export type PromptEvent = {
    schema: CommandSchema;
    /** 当前等待输入的玩家 */
    currentPlayer: string | null;
    /**
     * 尝试提交命令
     * @param commandOrInput Command 对象或命令字符串
     * @returns null - 验证成功，Promise 已 resolve
     * @returns string - 验证失败，返回错误消息，Promise 未 resolve
     */
    tryCommit: (commandOrInput: Command | string) => string | null;
    /** 取消 prompt，Promise 被 reject */
    cancel: (reason?: string) => void;
};

export type CommandRunnerEvents = {
    prompt: PromptEvent;
    /** 当 prompt 结束（tryCommit 成功或 cancel）时触发 */
    promptEnd: void;
};

export type CommandResult<T=unknown> = {
    success: true;
    result: T;
} | {
    success: false;
    error: string;
}

export type PromptValidator<TResult,TArgs extends any[]=any[]> = (...params: TArgs) => TResult;

export type CommandRunnerContext<TContext> = {
    context: TContext;
    run: <T=unknown>(input: string) => Promise<CommandResult<T>>;
    runParsed: <T=unknown>(command: Command) => Promise<CommandResult<T>>;
    prompt: <TResult,TArgs extends any[]=any[]>(schema: CommandSchema | string, validator: PromptValidator<TResult,TArgs>, currentPlayer?: string | null) => Promise<TResult>;
    on: <T extends keyof CommandRunnerEvents>(event: T, listener: (e: CommandRunnerEvents[T]) => void) => void;
    off: <T extends keyof CommandRunnerEvents>(event: T, listener: (e: CommandRunnerEvents[T]) => void) => void;
};

export type CommandRunnerHandler<TContext, TResult> = (
    this: CommandRunnerContext<TContext>,
    command: Command
) => Promise<TResult>;

export type CommandRunner<TContext, TResult = unknown> = {
    schema: CommandSchema;
    run: CommandRunnerHandler<TContext, TResult>;
};

export type CommandFunction<TContext> = (ctx: TContext, ...args: any[]) => Promise<unknown>;
export type CommandDef<TContext,TFunc extends CommandFunction<TContext>> = {
    schema: string | CommandSchema,
    run: TFunc;
}