takin/lib/runner/index.d.ts

Front end engineering base toolchain and scaffold

import { z } from 'zod';
import { CommandOptions } from '../cli';
import { Config, UsedPluginsMap } from '../config';
import { Generator } from '../generator';
import { Logger } from '../logger';
import { Plugin } from '../plugin';
import { UserConfig } from '../types';
import './customZod';
import { isHookRegistered, registerHook, registerHooks, RunnerHookFactories, RunnerHooks } from './hooks';
import { MethodsContainer } from './methods';
export { RunnerHookFactories, registerHook, registerHooks, RunnerHooks, isHookRegistered };
export declare type Zod = typeof z;
export interface RunnerAddCommandActionOptions {
    /**
     * 命令名称
     */
    name: string;
    /**
     * 插件名称
     */
    pluginName: string;
    /**
     * 命令需要执行的函数
     */
    callback: (command: CommandOptions) => any;
}
/**
 * runner 上下文, 可用于插件之间传递信息
 */
export declare type RunnerContext = Map<any, any>;
/**
 * Runner 初始化选项
 */
export interface RunnerOptions {
    config: Config;
    userConfig: UserConfig;
    command?: CommandOptions;
    plugins?: Plugin[];
    context?: RunnerContext | Record<string, any>;
}
/**
 * 用于扩展 Runner 属性或方法
 *
 * @example
 * const takinInstance = takin('name')
 *
 * // 步骤一: 这里扩展方法或属性的类型
 * declare module 'takin' {
 *   interface RunnerExtendable {
 *      customProp: any
 *      customMethod(..args: any[]): void
 *   }
 * }
 *
 * // 步骤二: 这里通过 extendRunner 提供扩展方法和属性的实现
 * takinInstance.hooks.extendRunner.tap('ExtendRunnerPluginName', (Runner) => {
 *   return class extends Runner {
 *     override customProp: any
 *     override customMethod(..args: any[]): void
 *   }
 * })
 *
 * // 完成步骤一和步骤二之后
 * // 插件 apply 方法拿到的 runner 就会包含 customProp 属性和 customMethod 方法
 */
export declare abstract class RunnerExtendable {
}
/**
 * 命令运行器
 */
export declare class Runner<R = any> extends RunnerExtendable {
    /**
     * 命令名称, cli commandName
     */
    commandName?: CommandOptions['name'];
    /**
     * 命令参数, 如: cli commandName arg1 arg2
     */
    commandArgs?: CommandOptions['args'];
    /**
     * 命令选项, 如: cli commandName arg1 --option1 --option2
     */
    commandOptions?: CommandOptions['options'];
    /**
     * 当前 Runner 对应的用户配置
     */
    userConfig: UserConfig;
    /**
     * Runner 命令被触发的方式, 用于辅助判断执行结果的退出方式和抛错方式
     * - cli 代表命令是从命令行中解析出来的
     * - api 代表命令是直接通过 API 传入的
     */
    commandInvokedBy: 'cli' | 'api';
    /**
     * runner id 用于 debug 显示
     */
    readonly runnerId: number;
    /**
     * runner 支持的 hooks, 可通过 registerHook 或 registerHooks 方法进行扩展
     */
    readonly hooks: RunnerHooks;
    /**
     * 配置类实例, 提供用户配置、部分功能开关、名称设置、缓存文件夹及临时文件夹等功能
     */
    readonly config: Config;
    /**
     * Runner 的 logger 实例
     */
    readonly logger: Logger;
    /**
     * 脚手架生成器
     */
    readonly generator: typeof Generator;
    /**
     * Runner 上下文, Map 对象, 可用于当前 Runner 运行期间的数据交换或存储
     */
    readonly context: RunnerContext;
    /**
     * Runner 共享方法, 用于插件之间共享方法
     */
    readonly methods: MethodsContainer;
    private cli;
    private result?;
    private plugins;
    private currentPluginName?;
    /**
     * 执行 Runner
     */
    static run({ config, userConfig, command, plugins, context }: RunnerOptions): Promise<Runner>;
    /**
     * @constructor
     * @param config - Config 实例
     * @param userConfig - 本地执行的用户配置
     * @param context - 传入的 Runner 上下文
     */
    constructor(config: Config, userConfig: UserConfig, context?: RunnerContext | Record<string, any>);
    /**
     * 获取当前工作目录
     * @returns 当前工作目录
     */
    getCwd(): string;
    /**
     * 获取 runner 运行后的结果
     */
    getResult(): R | undefined;
    /**
     * 获取已载入的插件
     */
    getPlugins(): UsedPluginsMap;
    /**
     * 获取当前插件的名称
     */
    getCurrentPluginName(): string;
    /**
     * 获取命令配置
     */
    getCommandOptions(): CommandOptions;
    /**
     * 获取 runner 名称
     */
    getRunnerName(): string;
    /**
     * 基于传入的命令或命令行参数运行 runner
     * @param command - 指定需要运行的命令及参数
     * @param plugins - 当前 runner 需要运行的插件列表
     * @returns 命令执行的结果
     */
    run(command?: CommandOptions, plugins?: Plugin[]): Promise<R | void>;
    /**
     * 运行 runner
     */
    private _run;
    /**
     * 添加可执行的命令
     * @param options - 选项
     */
    addCommandAction({ name, pluginName, callback }: RunnerAddCommandActionOptions): void;
    /**
     * 运行命令对应的 action
     */
    invokeCommandAction(command?: CommandOptions): Promise<void>;
    /**
     * 解析命令行或传入的命令
     * @param command - 命令配置
     * @returns 解析后的命令
     */
    private prepareCliAndParseMatchedCommand;
    /**
     * 执行所有插件
     */
    private applySpecificOrAllPlugins;
}