@meng-xi/vite-plugin 0.0.2 → 0.0.4

package/dist/common/index.d.ts

@@ -0,0 +1,235 @@
+export { V as Validator } from '../shared/vite-plugin.CiHfwMiN.js';
+
+/**
+ * 复制操作的选项接口
+ */
+interface CopyOptions {
+    /**
+     * 是否支持递归复制
+     */
+    recursive: boolean;
+    /**
+     * 是否覆盖同名文件
+     */
+    overwrite: boolean;
+    /**
+     * 是否启用增量复制
+     */
+    incremental?: boolean;
+    /**
+     * 并行处理的最大文件数
+     */
+    parallelLimit?: number;
+    /**
+     * 是否跳过空目录
+     */
+    skipEmptyDirs?: boolean;
+}
+/**
+ * 复制结果接口
+ */
+interface CopyResult {
+    /**
+     * 复制的文件数量
+     */
+    copiedFiles: number;
+    /**
+     * 跳过的文件数量
+     */
+    skippedFiles: number;
+    /**
+     * 复制的目录数量
+     */
+    copiedDirs: number;
+    /**
+     * 总执行时间（毫秒）
+     */
+    executionTime: number;
+}
+
+/**
+ * 文件/目录条目信息
+ */
+interface FileEntry {
+    /** 完整路径 */
+    path: string;
+    /** 是否为文件 */
+    isFile: boolean;
+    /** 是否为目录 */
+    isDirectory: boolean;
+}
+/**
+ * 检查源文件是否存在
+ * @param sourcePath 源文件路径
+ * @throws 当源文件不存在或无法访问时抛出异常
+ */
+declare function checkSourceExists(sourcePath: string): Promise<void>;
+/**
+ * 创建目标目录
+ * @param targetPath 目标目录路径
+ * @throws 当无法创建目标目录时抛出异常
+ */
+declare function ensureTargetDir(targetPath: string): Promise<void>;
+/**
+ * 读取目录内容（优化版：一次性获取文件类型信息）
+ * @param dirPath 目录路径
+ * @param recursive 是否递归读取
+ * @returns 文件和目录条目列表
+ */
+declare function readDirRecursive(dirPath: string, recursive: boolean): Promise<FileEntry[]>;
+/**
+ * 检查文件是否需要更新
+ * @param sourceFile 源文件路径
+ * @param targetFile 目标文件路径
+ * @returns 是否需要更新
+ */
+declare function shouldUpdateFile(sourceFile: string, targetFile: string): Promise<boolean>;
+/**
+ * 执行文件复制操作（优化版：并行IO）
+ * @param sourcePath 源文件或目录路径
+ * @param targetPath 目标文件或目录路径
+ * @param options 复制选项
+ * @returns 复制结果
+ * @throws 当复制过程中出现错误时抛出异常
+ */
+declare function copySourceToTarget(sourcePath: string, targetPath: string, options: CopyOptions): Promise<CopyResult>;
+/**
+ * 写入文件内容
+ * @param filePath 文件路径
+ * @param content 文件内容
+ * @throws 当写入过程中出现错误时抛出异常
+ */
+declare function writeFileContent(filePath: string, content: string): Promise<void>;
+/**
+ * 同步读取文件内容
+ * @param filePath 文件路径
+ * @returns 文件内容字符串
+ * @throws 当读取过程中出现错误时抛出异常
+ */
+declare function readFileSync(filePath: string): string;
+
+/**
+ * 数字补零格式化
+ *
+ * @param num 要格式化的数字
+ * @param length 目标长度
+ * @returns 补零后的字符串
+ *
+ * @example
+ * ```typescript
+ * padNumber(5, 2)  // '05'
+ * padNumber(12, 3) // '012'
+ * padNumber(123, 2) // '123'
+ * ```
+ */
+declare function padNumber(num: number, length?: number): string;
+/**
+ * 生成随机哈希字符串
+ *
+ * @param length 哈希长度，范围 1-64
+ * @returns 随机哈希字符串
+ *
+ * @example
+ * ```typescript
+ * generateRandomHash(8)  // 'a1b2c3d4'
+ * generateRandomHash(16) // 'a1b2c3d4e5f6g7h8'
+ * ```
+ */
+declare function generateRandomHash(length?: number): string;
+/**
+ * 日期格式化选项
+ */
+interface DateFormatOptions {
+    /** 四位年份 */
+    YYYY: string;
+    /** 两位年份 */
+    YY: string;
+    /** 两位月份 */
+    MM: string;
+    /** 两位日期 */
+    DD: string;
+    /** 两位小时（24小时制） */
+    HH: string;
+    /** 两位分钟 */
+    mm: string;
+    /** 两位秒数 */
+    ss: string;
+    /** 三位毫秒 */
+    SSS: string;
+    /** 时间戳（毫秒） */
+    timestamp: string;
+}
+/**
+ * 获取日期格式化参数
+ *
+ * @param date 日期对象
+ * @returns 日期格式化参数对象
+ *
+ * @example
+ * ```typescript
+ * const params = getDateFormatParams(new Date())
+ * // { YYYY: '2026', MM: '02', DD: '03', HH: '15', mm: '30', ss: '00', ... }
+ * ```
+ */
+declare function getDateFormatParams(date?: Date): DateFormatOptions;
+/**
+ * 格式化日期
+ *
+ * @param date 日期对象
+ * @param format 格式模板
+ * @returns 格式化后的日期字符串
+ *
+ * @example
+ * ```typescript
+ * formatDate(new Date(), '{YYYY}-{MM}-{DD}')         // '2026-02-03'
+ * formatDate(new Date(), '{YYYY}{MM}{DD}{HH}{mm}{ss}') // '20260203153000'
+ * formatDate(new Date(), '{YYYY}.{MM}.{DD}')         // '2026.02.03'
+ * ```
+ */
+declare function formatDate(date: Date, format: string): string;
+/**
+ * 解析模板字符串，替换占位符
+ *
+ * @param template 模板字符串
+ * @param values 占位符值映射
+ * @returns 替换后的字符串
+ *
+ * @example
+ * ```typescript
+ * parseTemplate('{name}-{version}', { name: 'app', version: '1.0.0' })
+ * // 'app-1.0.0'
+ * ```
+ */
+declare function parseTemplate(template: string, values: Record<string, string>): string;
+
+/**
+ * 深度合并对象
+ *
+ * @description 将多个源对象深度合并到一个新对象中。
+ * - undefined 值会被跳过，不会覆盖已有值
+ * - 嵌套对象会递归合并
+ * - 数组会直接覆盖，不会合并
+ * - null 值会覆盖已有值
+ *
+ * @param sources 源对象列表
+ * @returns 合并后的对象
+ *
+ * @example
+ * ```typescript
+ * // 基本合并
+ * deepMerge({ a: 1 }, { b: 2 }) // { a: 1, b: 2 }
+ *
+ * // undefined 不覆盖
+ * deepMerge({ a: 1 }, { a: undefined }) // { a: 1 }
+ *
+ * // 嵌套对象合并
+ * deepMerge({ a: { b: 1 } }, { a: { c: 2 } }) // { a: { b: 1, c: 2 } }
+ *
+ * // 数组覆盖
+ * deepMerge({ a: [1, 2] }, { a: [3, 4] }) // { a: [3, 4] }
+ * ```
+ */
+declare function deepMerge<T extends Record<string, any>>(...sources: Partial<T>[]): T;
+
+export { checkSourceExists, copySourceToTarget, deepMerge, ensureTargetDir, formatDate, generateRandomHash, getDateFormatParams, padNumber, parseTemplate, readDirRecursive, readFileSync, shouldUpdateFile, writeFileContent };
+export type { DateFormatOptions };

package/dist/common/index.mjs

@@ -0,0 +1 @@
+export{c as checkSourceExists,a as copySourceToTarget,e as ensureTargetDir,f as formatDate,g as generateRandomHash,b as getDateFormatParams,p as padNumber,d as parseTemplate,r as readDirRecursive,h as readFileSync,s as shouldUpdateFile,w as writeFileContent}from"../shared/vite-plugin.HZb-1B5l.mjs";export{V as Validator,d as deepMerge}from"../shared/vite-plugin.B88RyRN8.mjs";import"fs";import"path";import"crypto";

package/dist/factory/index.cjs

@@ -0,0 +1 @@
+"use strict";const index=require("../shared/vite-plugin.DqWt65U-.cjs");require("../logger/index.cjs"),require("fs"),require("path"),require("crypto"),require("../shared/vite-plugin.IGZeStMa.cjs"),exports.BasePlugin=index.BasePlugin,exports.createPluginFactory=index.createPluginFactory;

package/dist/factory/index.d.cts

@@ -0,0 +1,260 @@
+import { ResolvedConfig, Plugin } from 'vite';
+import { B as BasePluginOptions, O as OptionsNormalizer, P as PluginFactory } from '../shared/vite-plugin.UkE7CdSe.cjs';
+import { P as PluginLogger, a as LoggerOptions } from '../shared/vite-plugin.B3PARlU9.cjs';
+import { V as Validator } from '../shared/vite-plugin.CiHfwMiN.cjs';
+
+/**
+ * 基础插件抽象类，提供插件开发的核心功能和生命周期管理
+ *
+ * @class BasePlugin
+ * @template T - 插件配置类型，必须继承自 BasePluginOptions
+ * @abstract
+ * @description 该类是所有插件的基类，提供了插件配置管理、日志记录、生命周期管理等核心功能
+ * @example
+ * ```typescript
+ * class MyPlugin extends BasePlugin<MyPluginOptions> {
+ *   protected getPluginName() {
+ *     return 'my-plugin'
+ *   }
+ *
+ *   protected addPluginHooks(plugin: Plugin) {
+ *     // 添加插件钩子
+ *   }
+ * }
+ * ```
+ */
+declare abstract class BasePlugin<T extends BasePluginOptions = BasePluginOptions> {
+    /**
+     * 插件配置
+     *
+     * @protected
+     * @description 插件配置，包含插件的运行参数和选项
+     */
+    protected options: Required<T>;
+    /**
+     * 插件日志记录器
+     *
+     * @protected
+     * @description 插件日志记录器，用于记录插件运行时的日志信息
+     */
+    protected logger: PluginLogger;
+    /**
+     * 插件配置验证器
+     *
+     * @protected
+     * @description 插件配置验证器，用于验证插件配置参数是否符合要求
+     */
+    protected validator: Validator<T>;
+    /**
+     * Vite 配置
+     *
+     * @protected
+     * @description Vite 配置，包含 Vite 构建的运行参数和选项
+     */
+    protected viteConfig: ResolvedConfig | null;
+    /**
+     * 插件构造函数
+     *
+     * @param options 插件配置
+     * @param loggerConfig 日志配置，可选
+     *
+     * @protected
+     * @description 插件构造函数，初始化插件配置、日志记录器和验证插件参数
+     */
+    constructor(options: T, loggerConfig?: LoggerOptions);
+    /**
+     * 获取插件的默认配置选项
+     *
+     * @protected
+     * @abstract
+     * @returns {Partial<T>} 插件特定的默认配置
+     * @description 子类必须实现此方法，以提供插件特定的默认配置值
+     */
+    protected abstract getDefaultOptions(): Partial<T>;
+    /**
+     * 合并插件配置，将用户提供的配置与默认配置合并
+     *
+     * @protected
+     * @template T - 插件配置类型，必须继承自 BasePluginOptions
+     * @param {T} options - 用户提供的插件配置
+     * @returns {Required<T>} 合并后的完整插件配置，包含所有必填字段
+     * @description 将用户提供的配置与基础默认值、插件特定默认值进行深度合并，确保所有必填字段都有值
+     * @example
+     * ```typescript
+     * const userOptions = { enabled: false }
+     * const mergedOptions = this.mergeOptions(userOptions)
+     * // mergedOptions 将包含基础默认值和插件特定默认值
+     * ```
+     */
+    protected mergeOptions(options: T): Required<T>;
+    /**
+     * 初始化日志记录器
+     *
+     * @private
+     * @param {LoggerOptions} loggerConfig - 日志配置对象，可选
+     * @returns {PluginLogger} 插件日志代理对象，用于记录插件日志
+     * @description 使用单例 Logger 创建插件特定的日志代理对象
+     */
+    private initLogger;
+    /**
+     * 验证插件配置参数，确保配置符合要求
+     *
+     * @protected
+     * @virtual
+     * @returns {void} 无返回值
+     * @throws {Error} 如果配置参数无效，抛出包含错误信息的异常
+     * @description 该方法在插件初始化时被调用，用于验证插件配置的有效性。子类可以重写此方法以添加自定义验证逻辑
+     * @example
+     * ```typescript
+     * protected validateOptions(): void {
+     *   if (!this.options.sourceDir) {
+     *     throw new Error('sourceDir 是必填项')
+     *   }
+     *
+     *   if (!this.options.targetDir) {
+     *     throw new Error('targetDir 是必填项')
+     *   }
+     * }
+     * ```
+     */
+    protected validateOptions(): void;
+    /**
+     * 获取插件名称
+     *
+     * @protected
+     * @returns {string} 插件的名称，用于 Vite 插件系统识别
+     */
+    protected abstract getPluginName(): string;
+    /**
+     * 获取插件执行时机
+     *
+     * @protected
+     * @returns {Plugin['enforce']} 插件的执行时机，可选值为 'pre'、'post' 或 undefined
+     * @description 'post' 表示插件在 Vite 构建后期执行
+     */
+    protected getEnforce(): Plugin['enforce'];
+    /**
+     * 处理配置解析完成事件
+     *
+     * @param config 解析后的 Vite 配置
+     *
+     * @protected
+     * @description 处理 Vite 配置解析完成事件，将解析后的配置存储到插件实例中
+     */
+    protected onConfigResolved(config: ResolvedConfig): void;
+    /**
+     * 添加插件钩子到 Vite 插件对象
+     *
+     * @protected
+     * @abstract
+     * @param {Plugin} plugin - Vite 插件对象，用于添加钩子
+     * @returns {void} 无返回值
+     * @description 添加插件钩子到 Vite 插件对象，用于在构建过程中执行插件逻辑
+     */
+    protected abstract addPluginHooks(plugin: Plugin): void;
+    /**
+     * 安全执行同步函数，自动处理执行过程中可能出现的错误
+     *
+     * @protected
+     * @template T - 函数的返回值类型
+     * @param {() => T} fn - 要执行的同步函数
+     * @param {string} context - 执行上下文描述，用于错误日志记录
+     * @returns {T | undefined} 函数的执行结果，如果执行过程中发生错误，根据错误策略返回 undefined 或抛出错误
+     * @description 该方法封装了同步函数的执行，自动处理可能出现的错误，根据插件配置的 errorStrategy 决定如何处理错误
+     * @example
+     * ```typescript
+     * // 安全执行同步操作
+     * const result = this.safeExecuteSync(() => {
+     *   return someSyncOperation()
+     * }, '执行同步操作')
+     *
+     * // 如果 someSyncOperation() 抛出错误，会根据 errorStrategy 处理
+     * ```
+     */
+    protected safeExecuteSync<T>(fn: () => T, context: string): T | undefined;
+    /**
+     * 安全执行异步函数，自动处理执行过程中可能出现的错误
+     *
+     * @protected
+     * @async
+     * @template T - 异步函数的返回值类型
+     * @param {() => Promise<T>} fn - 要执行的异步函数
+     * @param {string} context - 执行上下文描述，用于错误日志记录
+     * @returns {Promise<T | undefined>} 异步函数的执行结果，如果执行过程中发生错误，根据错误策略返回 undefined 或抛出错误
+     * @description 该方法封装了异步函数的执行，自动处理可能出现的错误，根据插件配置的 errorStrategy 决定如何处理错误
+     * @example
+     * ```typescript
+     * // 安全执行异步操作
+     * const result = await this.safeExecute(async () => {
+     *   return await someAsyncOperation()
+     * }, '执行异步操作')
+     *
+     * // 如果 someAsyncOperation() 抛出错误，会根据 errorStrategy 处理
+     * ```
+     */
+    protected safeExecute<T>(fn: () => Promise<T>, context: string): Promise<T | undefined>;
+    /**
+     * 处理插件执行过程中出现的错误，根据配置的错误策略决定如何处理
+     *
+     * @protected
+     * @template T - 返回值类型，仅当错误策略为 'log' 或 'ignore' 时返回 undefined
+     * @param {unknown} error - 捕获到的错误对象
+     * @param {string} context - 错误发生的上下文描述，用于错误日志记录
+     * @returns {T | undefined} 当错误策略为 'log' 或 'ignore' 时返回 undefined，否则抛出错误
+     * @description 根据插件配置的 errorStrategy 处理错误：
+     * - 'throw': 记录错误日志并抛出错误，中断执行
+     * - 'log': 记录错误日志但不抛出错误，继续执行
+     * - 'ignore': 记录错误日志但不抛出错误，继续执行
+     * - 默认：记录错误日志并抛出错误
+     * @example
+     * ```typescript
+     * // 当 errorStrategy 为 'throw' 时
+     * this.handleError(new Error('测试错误'), '测试上下文') // 记录错误日志并抛出错误
+     *
+     * // 当 errorStrategy 为 'log' 时
+     * this.handleError(new Error('测试错误'), '测试上下文') // 记录错误日志并返回 undefined
+     * ```
+     */
+    protected handleError<T>(error: unknown, context: string): T | undefined;
+    /**
+     * 将插件实例转换为 Vite 插件对象，用于 Vite 构建系统
+     *
+     * @public
+     * @returns {Plugin} Vite 插件对象，包含插件名称、执行时机和各种钩子函数
+     * @description 该方法创建并返回一个符合 Vite 插件规范的对象，设置了插件的基本信息和 configResolved 钩子，然后调用 addPluginHooks 方法添加插件特定的钩子
+     * @example
+     * ```typescript
+     * // 创建插件实例
+     * const pluginInstance = new MyPlugin(options)
+     *
+     * // 转换为 Vite 插件
+     * const vitePlugin = pluginInstance.toPlugin()
+     *
+     * // 导出 Vite 插件
+     * export const myPlugin = vitePlugin
+     * ```
+     */
+    toPlugin(): Plugin;
+}
+/**
+ * 创建插件工厂函数，用于生成 Vite 插件实例
+ *
+ * @template T - 插件配置类型，必须继承自 BasePluginOptions
+ * @template P - 插件实例类型，必须继承自 BasePlugin<T>
+ * @template R - 原始配置类型
+ * @param {new (options: T, loggerConfig?: LoggerOptions) => P} PluginClass - 插件类构造函数
+ * @param {OptionsNormalizer<T, R>} [normalizer] - 选项标准化器，可选
+ * @returns {PluginFactory<T, R>} 插件工厂函数，接收插件配置并返回 Vite 插件实例
+ * @description 该函数创建一个插件工厂，用于生成 Vite 插件实例。工厂函数接收插件配置，支持可选的标准化器，创建插件实例，转换为 Vite 插件对象，并在插件对象上添加对原始插件实例的引用
+ * @example
+ * ```typescript
+ * // 基本使用
+ * const myPluginFactory = createPluginFactory(MyPlugin)
+ *
+ * // 带标准化器的使用（支持字符串或对象）
+ * const myPluginWithNormalizer = createPluginFactory(MyPlugin, (opt) => typeof opt === 'string' ? { path: opt } : opt)
+ * ```
+ */
+declare function createPluginFactory<T extends BasePluginOptions, P extends BasePlugin<T>, R = T>(PluginClass: new (options: T, loggerConfig?: LoggerOptions) => P, normalizer?: OptionsNormalizer<T, R>): PluginFactory<T, R>;
+
+export { BasePlugin, createPluginFactory };