@meng-xi/vite-plugin 0.0.2 → 0.0.4

package/README-en.md

@@ -12,11 +12,11 @@
 
 </div>
 
-> - This is a toolkit that provides practical plugins for Vite, helping developers simplify the build process and improve development efficiency.
+> - This is a toolkit that provides practical plugins for Vite, and also serves as a complete **Vite Plugin Development Framework**.
 > - Extends Vite build process functionality, providing automated processing solutions for common build tasks.
 > - All plugins support detailed configuration options, allowing customization based on project needs to meet different usage scenarios.
 > - Plugins provide error handling mechanisms to ensure build processes can catch errors, improving build reliability.
-> - Adopts modular design, plugins can be used individually or in combination, flexibly responding to different project needs.
+> - Export core components like BasePlugin, Logger, Validator, allowing developers to build custom plugins based on the same infrastructure.
 
 ---
 
@@ -41,7 +41,7 @@ pnpm add @meng-xi/vite-plugin --save-dev
 
 ### Basic Usage
 
-Import and use the plugins in your Vite configuration file:
+#### Using Built-in Plugins
 
 ```typescript
 import { defineConfig } from 'vite'
@@ -63,28 +63,42 @@ export default defineConfig({
 })
 ```
 
-### Import All
-
-You can also use default import to import all plugins:
+#### Developing Custom Plugins
 
 ```typescript
-import { defineConfig } from 'vite'
-import vitePlugin from '@meng-xi/vite-plugin'
-
-export default defineConfig({
-	plugins: [
-		// Copy file plugin
-		vitePlugin.copyFile({
-			sourceDir: 'src/assets',
-			targetDir: 'dist/assets'
-		}),
-
-		// Inject icon plugin
-		vitePlugin.injectIco({
-			base: '/assets'
-		})
-	]
-})
+import { BasePlugin, createPluginFactory, Validator } from '@meng-xi/vite-plugin'
+import type { Plugin } from 'vite'
+
+interface MyPluginOptions {
+	path: string
+	enabled?: boolean
+	verbose?: boolean
+	errorStrategy?: 'throw' | 'log' | 'ignore'
+}
+
+class MyPlugin extends BasePlugin<MyPluginOptions> {
+	protected getDefaultOptions() {
+		return {
+			path: './default'
+		}
+	}
+
+	protected validateOptions(): void {
+		this.validator.field('path').required().string().validate()
+	}
+
+	protected getPluginName(): string {
+		return 'my-plugin'
+	}
+
+	protected addPluginHooks(plugin: Plugin): void {
+		plugin.buildStart = () => {
+			this.logger.info(`Plugin started with path: ${this.options.path}`)
+		}
+	}
+}
+
+export const myPlugin = createPluginFactory(MyPlugin)
 ```
 
 ## Plugin Details

package/README.md

@@ -14,16 +14,16 @@
 
 ## 简介
 
-`@meng-xi/vite-plugin` 是一个为 Vite 提供实用插件的工具包，帮助开发者简化构建流程，提高开发效率。
+`@meng-xi/vite-plugin` 是一个为 Vite 提供实用插件的工具包，也是一个**完整的插件开发框架**。该框架提供了常用功能的核心工具方法供扩展支持其他拓展工作开展快速开发。
 
 ## 特性
 
 - **增强 Vite 构建流程**：提供实用插件集合，扩展 Vite 功能，简化构建过程中的常见任务，提高开发效率
-- **模块化插件架构**：采用模块化设计，插件可单独使用或组合使用，灵活应对不同项目需求
+- **插件开发框架**：导出核心组件如 BasePlugin、Logger、Validator，允许开发者基于相同基础设施构建自定义插件
 - **高度可配置**：所有功能支持详细配置选项，可根据项目需求自定义行为，满足多样化场景
-- **环境感知能力**：支持根据构建环境条件执行插件功能，智能控制不同环境下的行为
-- **详细日志输出**：提供可选的详细日志，帮助开发者了解执行过程，便于调试和问题排查
-- **类型安全**：完全使用 TypeScript 开发，提供完整类型定义，确保使用过程中的类型安全
+- **单例日志系统**：统一的日志管理器，支持插件级别的日志控制，便于调试和问题排查
+- **类型安全验证**：强类型配置验证器，确保插件配置正确性，提供完整的 TypeScript 类型定义
+- **插件工厂模式**：支持选项标准化器，轻松处理异构输入，简化插件开发工作流
 - **无缝集成**：与 Vite 构建流程无缝集成，无需复杂配置即可快速启用
 - **优化开发体验**：简化常见构建任务，减少手动操作，让开发者专注于核心业务逻辑
 
@@ -46,6 +46,65 @@ yarn add @meng-xi/vite-plugin --save-dev
 pnpm add @meng-xi/vite-plugin --save-dev
 ```
 
+## 基本使用
+
+### 使用内置插件
+
+```typescript
+import { defineConfig } from 'vite'
+import { copyFile, injectIco } from '@meng-xi/vite-plugin'
+
+export default defineConfig({
+	plugins: [
+		copyFile({
+			sourceDir: 'src/assets',
+			targetDir: 'dist/assets'
+		}),
+		injectIco({
+			base: '/assets'
+		})
+	]
+})
+```
+
+### 开发自定义插件
+
+```typescript
+import { BasePlugin, createPluginFactory, Validator } from '@meng-xi/vite-plugin'
+import type { Plugin } from 'vite'
+
+interface MyPluginOptions {
+	path: string
+	enabled?: boolean
+	verbose?: boolean
+	errorStrategy?: 'throw' | 'log' | 'ignore'
+}
+
+class MyPlugin extends BasePlugin<MyPluginOptions> {
+	protected getDefaultOptions() {
+		return {
+			path: './default'
+		}
+	}
+
+	protected validateOptions(): void {
+		this.validator.field('path').required().string().validate()
+	}
+
+	protected getPluginName(): string {
+		return 'my-plugin'
+	}
+
+	protected addPluginHooks(plugin: Plugin): void {
+		plugin.buildStart = () => {
+			this.logger.info(`Plugin started with path: ${this.options.path}`)
+		}
+	}
+}
+
+export const myPlugin = createPluginFactory(MyPlugin)
+```
+
 ## 更新日志
 
 [CHANGELOG](https://github.com/MengXi-Studio/vite-plugin/releases)

package/dist/common/index.cjs

@@ -0,0 +1 @@
+"use strict";const format=require("../shared/vite-plugin.D6NYITpX.cjs"),validation=require("../shared/vite-plugin.IGZeStMa.cjs");require("fs"),require("path"),require("crypto"),exports.checkSourceExists=format.checkSourceExists,exports.copySourceToTarget=format.copySourceToTarget,exports.ensureTargetDir=format.ensureTargetDir,exports.formatDate=format.formatDate,exports.generateRandomHash=format.generateRandomHash,exports.getDateFormatParams=format.getDateFormatParams,exports.padNumber=format.padNumber,exports.parseTemplate=format.parseTemplate,exports.readDirRecursive=format.readDirRecursive,exports.readFileSync=format.readFileSync,exports.shouldUpdateFile=format.shouldUpdateFile,exports.writeFileContent=format.writeFileContent,exports.Validator=validation.Validator,exports.deepMerge=validation.deepMerge;

package/dist/common/index.d.cts

@@ -0,0 +1,235 @@
+export { V as Validator } from '../shared/vite-plugin.CiHfwMiN.cjs';
+
+/**
+ * 复制操作的选项接口
+ */
+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.d.mts

@@ -0,0 +1,235 @@
+export { V as Validator } from '../shared/vite-plugin.CiHfwMiN.mjs';
+
+/**
+ * 复制操作的选项接口
+ */
+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 };