onebot-commander/dist/cjs/commander.d.ts

OneBot12 Message Segment Commander - TypeScript version with dual ESM/CJS format support

import { MessageSegment, CallbackFunction } from './types';
import { PatternToken } from './pattern_token';
/**
 * OneBot Commander 主类
 *
 * 用于解析和匹配 OneBot12 消息段的命令解析器。
 * 支持复杂的模式匹配、参数提取和链式回调处理。
 *
 * @example
 * ```typescript
 * const commander = new Commander('hello <name:text>');
 * commander.action((params) => {
 *   console.log(`Hello, ${params.name}!`);
 * });
 * ```
 */
export declare class Commander {
    /** 回调函数数组，用于链式处理匹配结果 */
    private callbacks;
    /** 解析后的模式令牌数组 */
    private tokens;
    /** 类型化字面量的字段映射配置 */
    private typedLiteralFields;
    /** 缓存的回调链执行器 */
    private callbackChain;
    /**
     * 默认的类型化字面量字段映射规则
     *
     * 定义了不同消息段类型对应的数据字段：
     * - text: 使用 'text' 字段
     * - face: 使用 'id' 字段
     * - image: 使用 'file' 或 'url' 字段（支持多字段）
     * - at: 使用 'user_id' 字段
     */
    static DEFAULT_TYPED_LITERAL_FIELD_MAP: Record<string, string | string[]>;
    /**
     * 构造函数
     *
     * @param pattern - 命令模式字符串，定义匹配规则
     * @param typedLiteralFields - 自定义的类型化字面量字段映射（可选）
     *
     * @throws {ValidationError} 当模式为空或格式错误时抛出
     *
     * @example
     * ```typescript
     * // 基础用法
     * const commander = new Commander('hello <name:text>');
     *
     * // 自定义字段映射
     * const customCommander = new Commander('{image:avatar.png}<name:text>', {
     *   image: 'src'  // 使用 'src' 字段而不是默认的 'file' 或 'url'
     * });
     * ```
     */
    constructor(pattern: string, typedLiteralFields?: Record<string, string | string[]>);
    /**
     * 添加回调函数到处理链
     *
     * 支持同步和异步回调函数，可以链式调用。
     * 回调函数会按添加顺序执行，前一个回调的返回值会作为下一个回调的参数。
     *
     * @param callback - 回调函数，接收匹配参数和剩余消息段
     * @returns 当前实例，支持链式调用
     *
     * @example
     * ```typescript
     * commander
     *   .action((params) => {
     *     console.log('First action:', params);
     *     return params.name.toUpperCase();
     *   })
     *   .action((upperName) => {
     *     console.log('Second action:', upperName);
     *     return `Hello, ${upperName}!`;
     *   });
     * ```
     */
    action(callback: CallbackFunction): Commander;
    /**
     * 获取或创建优化的回调链执行器
     */
    private getCallbackChain;
    /**
     * 同步匹配消息段并执行回调链
     *
     * 根据模式匹配消息段，如果匹配成功则按顺序执行所有回调函数。
     * 每个回调函数的返回值会作为下一个回调函数的参数。
     *
     * @param segments - OneBot12 消息段数组
     * @returns 返回最后一个回调函数的返回值数组，如果匹配失败返回空数组
     *
     * @throws {ValidationError} 当消息段参数无效时抛出
     *
     * @example
     * ```typescript
     * const segments = [
     *   { type: 'text', data: { text: 'hello Alice' } }
     * ];
     *
     * const result = commander.match(segments);
     * // result 包含所有回调函数的最终返回值
     * ```
     */
    match(segments: MessageSegment[]): any[];
    /**
     * 异步匹配消息段并执行回调链
     *
     * 异步版本的 match 方法，支持异步回调函数。
     * 会自动检测回调函数的返回值是否为 Promise，并正确处理异步执行。
     *
     * @param segments - OneBot12 消息段数组
     * @returns 返回 Promise<匹配结果数组>，如果匹配失败返回 Promise<空数组>
     *
     * @throws {ValidationError} 当消息段参数无效时抛出
     *
     * @example
     * ```typescript
     * const segments = [
     *   { type: 'text', data: { text: 'hello Alice' } }
     * ];
     *
     * const result = await commander.matchAsync(segments);
     * // result 包含所有异步回调函数的最终返回值
     * ```
     */
    matchAsync(segments: MessageSegment[]): Promise<any[]>;
    /**
     * 获取解析后的模式令牌
     *
     * 主要用于调试和测试，返回模式解析器生成的令牌数组。
     *
     * @returns 模式令牌数组
     *
     * @example
     * ```typescript
     * const commander = new Commander('hello <name:text>');
     * const tokens = commander.getTokens();
     * console.log(tokens); // 显示解析后的令牌结构
     * ```
     */
    getTokens(): PatternToken[];
}
/**
 * 便捷函数：创建命令匹配器实例
 *
 * 这是一个工厂函数，提供更简洁的 API 来创建 Commander 实例。
 *
 * @param pattern - 命令模式字符串
 * @param typedLiteralFields - 自定义的类型化字面量字段映射（可选）
 * @returns 新创建的 Commander 实例
 *
 * @example
 * ```typescript
 * // 使用便捷函数创建实例
 * const commander = match('hello <name:text>');
 *
 * // 等同于
 * const commander = new Commander('hello <name:text>');
 * ```
 */
export declare function match(pattern: string, typedLiteralFields?: Record<string, string | string[]>): Commander;