@meng-xi/vite-plugin 0.1.4 → 0.1.6

package/dist/common/format/index.d.ts

@@ -22,34 +22,6 @@ interface DateFormatOptions {
     timestamp: 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;
 /**
  * 获取日期格式化参数
  *
@@ -64,93 +36,39 @@ declare function generateRandomHash(length?: number): string;
  */
 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 - 包含 `{{key}}` 占位符的模板字符串
+ * @param values - 占位符键值映射，支持合并多组变量（后者覆盖前者）
+ * @returns 替换占位符后的字符串
  *
- * @param template 模板字符串
- * @param values 占位符值映射
- * @returns 替换后的字符串
+ * @description 将模板中的 `{{key}}` 占位符替换为对应的值。
+ * 键名中的正则特殊字符会被自动转义，值中的 `$` 也会被安全处理。
  *
  * @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;
-/**
- * 将字符串转换为驼峰命名（camelCase）
- *
- * @param str 输入字符串
- * @param separators 分隔符正则，默认为斜杠和横线
- * @returns 驼峰命名字符串
+ * parseTemplate('Hello {{name}}!', { name: 'World' })
+ * // 'Hello World!'
  *
- * @example
- * ```typescript
- * toCamelCase('pages/user/profile')  // 'pagesUserProfile'
- * toCamelCase('user-profile-page')   // 'userProfilePage'
- * toCamelCase('/pages/index')        // 'pagesIndex'
- * ```
- */
-declare function toCamelCase(str: string, separators?: RegExp): string;
-/**
- * 将字符串转换为帕斯卡命名（PascalCase）
- *
- * @param str 输入字符串
- * @param separators 分隔符正则，默认为斜杠和横线
- * @returns 帕斯卡命名字符串
- *
- * @example
- * ```typescript
- * toPascalCase('pages/user/profile')  // 'PagesUserProfile'
- * toPascalCase('user-profile-page')   // 'UserProfilePage'
- * toPascalCase('/pages/index')        // 'PagesIndex'
+ * parseTemplate('{{YYYY}}-{{MM}}-{{DD}}', getDateFormatParams())
+ * // '2026-06-06'
  * ```
  */
-declare function toPascalCase(str: string, separators?: RegExp): string;
-/**
- * 移除 JSON 字符串中的注释
- *
- * @param jsonString 包含注释的 JSON 字符串
- * @returns 移除注释后的 JSON 字符串
- *
- * @example
- * ```typescript
- * stripJsonComments('{\n  // comment\n  "name": "test"\n}')
- * // '{\n  "name": "test"\n}'
- * ```
- */
-declare function stripJsonComments(jsonString: string): string;
+declare function parseTemplate(template: string, values: Record<string, string>): string;
 /**
- * 转义 HTML 属性值中的特殊字符，防止 XSS 注入
+ * 格式化日期字符串
  *
- * @param str - 需要转义的字符串
- * @returns 转义后的安全字符串
+ * @param date - 日期对象
+ * @param format - 格式字符串，支持 `{YYYY}`、`{MM}`、`{DD}`、`{HH}`、`{mm}`、`{ss}` 等占位符
+ * @returns 格式化后的日期字符串
  *
  * @example
  * ```typescript
- * escapeHtmlAttr('hello "world"')
- * // 'hello &quot;world&quot;'
- *
- * escapeHtmlAttr('<script>alert(1)</script>')
- * // '&lt;script&gt;alert(1)&lt;/script&gt;'
+ * formatDate(new Date(), '{YYYY}-{MM}-{DD}T{HH}:{mm}:{ss}')
+ * // '2026-06-06T15:30:00'
  * ```
  */
-declare function escapeHtmlAttr(str: string): string;
+declare function formatDate(date: Date, format: string): string;
 /**
  * 将字节数格式化为人类可读的文件大小字符串
  *
@@ -170,19 +88,6 @@ declare function escapeHtmlAttr(str: string): string;
  * ```
  */
 declare function formatFileSize(bytes: number): string;
-/**
- * 获取文件扩展名
- *
- * @param {string} filePath - 文件路径
- * @returns {string} 小写的文件扩展名（如 '.js'）
- *
- * @example
- * ```typescript
- * getExtension('dist/app.js')  // '.js'
- * getExtension('dist/style.CSS') // '.css'
- * ```
- */
-declare function getExtension(filePath: string): string;
 
-export { escapeHtmlAttr, formatDate, formatFileSize, generateRandomHash, getDateFormatParams, getExtension, padNumber, parseTemplate, stripJsonComments, toCamelCase, toPascalCase };
+export { formatDate, formatFileSize, getDateFormatParams, parseTemplate };
 export type { DateFormatOptions };

package/dist/common/format/index.mjs

@@ -1 +1 @@
-import{randomBytes as c}from"crypto";import l from"node:path";function o(e,t=2){return e.toString().padStart(t,"0")}function p(e=8){const t=Math.max(1,Math.min(64,e));return c(Math.ceil(t/2)).toString("hex").slice(0,t)}function i(e=new Date){return{YYYY:e.getFullYear().toString(),YY:e.getFullYear().toString().slice(-2),MM:o(e.getMonth()+1),DD:o(e.getDate()),HH:o(e.getHours()),mm:o(e.getMinutes()),ss:o(e.getSeconds()),SSS:o(e.getMilliseconds(),3),timestamp:e.getTime().toString()}}function g(e,t){const r=i(e);let n=t;for(const[a,s]of Object.entries(r))n=n.replace(new RegExp(`\\{${a}\\}`,"g"),s);return n}function m(e,t){let r=e;for(const[n,a]of Object.entries(t))r=r.replace(new RegExp(`\\{${n}\\}`,"g"),a);return r}function u(e,t=/[/-]/){return e.replace(/^\/+/,"").split(t).filter(Boolean).map((r,n)=>n===0?r.toLowerCase():r.charAt(0).toUpperCase()+r.slice(1).toLowerCase()).join("")}function f(e,t=/[/-]/){return e.replace(/^\/+/,"").split(t).filter(Boolean).map(r=>r.charAt(0).toUpperCase()+r.slice(1).toLowerCase()).join("")}function S(e){return e.replace(/\/\/.*$/gm,"").replace(/\/\*[\s\S]*?\*\//g,"")}function C(e){return e.replace(/&/g,"&amp;").replace(/"/g,"&quot;").replace(/</g,"&lt;").replace(/>/g,"&gt;")}function x(e){return e<1024?`${e}B`:e<1024*1024?`${(e/1024).toFixed(1)}KB`:`${(e/(1024*1024)).toFixed(2)}MB`}function M(e){return l.extname(e).toLowerCase()}export{C as escapeHtmlAttr,g as formatDate,x as formatFileSize,p as generateRandomHash,i as getDateFormatParams,M as getExtension,o as padNumber,m as parseTemplate,S as stripJsonComments,u as toCamelCase,f as toPascalCase};
+function e(t,n=2){return t.toString().padStart(n,"0")}function g(t=new Date){return{YYYY:t.getFullYear().toString(),YY:t.getFullYear().toString().slice(-2),MM:e(t.getMonth()+1),DD:e(t.getDate()),HH:e(t.getHours()),mm:e(t.getMinutes()),ss:e(t.getSeconds()),SSS:e(t.getMilliseconds(),3),timestamp:t.getTime().toString()}}function c(t,n){let r=t;for(const[o,i]of Object.entries(n)){const a=o.replace(/[.*+?^${}()|[\]\\]/g,"\\$&"),s=i.replace(/\$/g,"$$$$");r=r.replace(new RegExp(`\\{\\{${a}\\}\\}`,"g"),s)}return r}function l(t,n){const r=g(t);let o=n;for(const[i,a]of Object.entries(r))o=o.replace(new RegExp(`\\{${i}\\}`,"g"),a);return o}function u(t){return t<1024?`${t}B`:t<1024*1024?`${(t/1024).toFixed(1)}KB`:`${(t/(1024*1024)).toFixed(2)}MB`}export{l as formatDate,u as formatFileSize,g as getDateFormatParams,c as parseTemplate};

package/dist/common/fs/index.cjs

@@ -1 +1 @@
-"use strict";const s=require("fs"),f=require("path");function _interopDefaultCompat(u){return u&&typeof u=="object"&&"default"in u?u.default:u}const s__default=_interopDefaultCompat(s),f__default=_interopDefaultCompat(f),S=10;async function checkSourceExists(u){try{await s__default.promises.access(u,s__default.constants.F_OK)}catch(t){const e=t;throw e.code==="ENOENT"?new Error(`\u590D\u5236\u6587\u4EF6\u5931\u8D25\uFF1A\u6E90\u6587\u4EF6\u4E0D\u5B58\u5728 - ${u}`):e.code==="EACCES"?new Error(`\u590D\u5236\u6587\u4EF6\u5931\u8D25\uFF1A\u6CA1\u6709\u6743\u9650\u8BBF\u95EE\u6E90\u6587\u4EF6 - ${u}`):new Error(`\u590D\u5236\u6587\u4EF6\u5931\u8D25\uFF1A\u68C0\u67E5\u6E90\u6587\u4EF6\u65F6\u51FA\u9519 - ${u}\uFF0C\u9519\u8BEF\uFF1A${e.message}`)}}async function ensureTargetDir(u){try{await s__default.promises.mkdir(u,{recursive:!0})}catch(t){const e=t;throw e.code==="EACCES"?new Error(`\u590D\u5236\u6587\u4EF6\u5931\u8D25\uFF1A\u6CA1\u6709\u6743\u9650\u521B\u5EFA\u76EE\u6807\u76EE\u5F55 - ${u}`):new Error(`\u590D\u5236\u6587\u4EF6\u5931\u8D25\uFF1A\u521B\u5EFA\u76EE\u6807\u76EE\u5F55\u65F6\u51FA\u9519 - ${u}\uFF0C\u9519\u8BEF\uFF1A${e.message}`)}}async function readDirRecursive(u,t){const e=await s__default.promises.readdir(u,{withFileTypes:!0}),r=[];for(const n of e){const a=f__default.join(u,n.name),F=n.isFile(),c=n.isDirectory();if(r.push({path:a,isFile:F,isDirectory:c}),c&&t){const l=await readDirRecursive(a,t);r.push(...l)}}return r}async function shouldUpdateFile(u,t){try{const[e,r]=await Promise.all([s__default.promises.stat(u),s__default.promises.stat(t)]);return e.mtimeMs>r.mtimeMs||e.size!==r.size}catch{return!0}}async function fileExists(u){try{return await s__default.promises.access(u,s__default.constants.F_OK),!0}catch{return!1}}async function runWithConcurrency(u,t,e){const r=[];let n=0;async function a(){for(;n<u.length;){const c=n++,l=await t(u[c]);r[c]=l}}const F=Array(Math.min(e,u.length)).fill(null).map(()=>a());return await Promise.all(F),r}async function copySourceToTarget(u,t,e){const r=Date.now(),{recursive:n,overwrite:a,incremental:F=!1,parallelLimit:c=S}=e;let l=0,p=0,E=0;if((await s__default.promises.stat(u)).isDirectory()){await ensureTargetDir(t);const o=await readDirRecursive(u,n),w=o.filter(i=>i.isFile);E=o.filter(i=>i.isDirectory).length;const h=new Set;for(const i of w){const D=f__default.relative(u,i.path),y=f__default.dirname(f__default.join(t,D));h.add(y)}await Promise.all([...h].map(i=>ensureTargetDir(i)));const A=await runWithConcurrency(w,async i=>{const D=f__default.relative(u,i.path),y=f__default.join(t,D);let m=a;return m||(m=!await fileExists(y)),F&&m&&(m=await shouldUpdateFile(i.path,y)),m?(await s__default.promises.copyFile(i.path,y),{copied:!0,skipped:!1}):{copied:!1,skipped:!0}},c);for(const i of A)i.copied&&l++,i.skipped&&p++}else{await ensureTargetDir(f__default.dirname(t));let o=a;o||(o=!await fileExists(t)),F&&o&&(o=await shouldUpdateFile(u,t)),o?(await s__default.promises.copyFile(u,t),l++):p++}const d=Date.now()-r;return{copiedFiles:l,skippedFiles:p,copiedDirs:E,executionTime:d}}async function writeFileContent(u,t){try{await s__default.promises.writeFile(u,t,"utf-8")}catch(e){const r=e;throw r.code==="EACCES"?new Error(`\u5199\u5165\u6587\u4EF6\u5931\u8D25\uFF1A\u6CA1\u6709\u6743\u9650\u5199\u5165\u6587\u4EF6 - ${u}`):new Error(`\u5199\u5165\u6587\u4EF6\u5931\u8D25\uFF1A\u5199\u5165\u6587\u4EF6\u65F6\u51FA\u9519 - ${u}\uFF0C\u9519\u8BEF\uFF1A${r.message}`)}}async function readFileContent(u){try{return await s__default.promises.readFile(u,"utf-8")}catch(t){const e=t;throw e.code==="EACCES"?new Error(`\u8BFB\u53D6\u6587\u4EF6\u5931\u8D25\uFF1A\u6CA1\u6709\u6743\u9650\u8BFB\u53D6\u6587\u4EF6 - ${u}`):new Error(`\u8BFB\u53D6\u6587\u4EF6\u5931\u8D25\uFF1A\u8BFB\u53D6\u6587\u4EF6\u65F6\u51FA\u9519 - ${u}\uFF0C\u9519\u8BEF\uFF1A${e.message}`)}}function readFileSync(u){try{return s__default.readFileSync(u,"utf-8")}catch(t){const e=t;throw e.code==="EACCES"?new Error(`\u8BFB\u53D6\u6587\u4EF6\u5931\u8D25\uFF1A\u6CA1\u6709\u6743\u9650\u8BFB\u53D6\u6587\u4EF6 - ${u}`):new Error(`\u8BFB\u53D6\u6587\u4EF6\u5931\u8D25\uFF1A\u8BFB\u53D6\u6587\u4EF6\u65F6\u51FA\u9519 - ${u}\uFF0C\u9519\u8BEF\uFF1A${e.message}`)}}async function scanDirectory(u,t={}){const{includeExtensions:e=[],excludePatterns:r=[],filter:n}=t,a=[];async function F(c){const l=await s__default.promises.readdir(c,{withFileTypes:!0});for(const p of l){const E=f__default.join(c,p.name);if(p.isDirectory()){await F(E);continue}if(!p.isFile()||r.some(w=>w.startsWith("*")?E.endsWith(w.slice(1)):E.includes(w)))continue;const d=f__default.extname(p.name).toLowerCase();if(e.length>0&&!e.includes(d))continue;const o=await s__default.promises.stat(E);n&&!n(E,d,o.size)||a.push({filePath:E,size:o.size,extension:d})}}return await F(u),a}async function writeJsonReport(u,t,e=2){await writeFileContent(u,JSON.stringify(t,null,e))}exports.checkSourceExists=checkSourceExists,exports.copySourceToTarget=copySourceToTarget,exports.ensureTargetDir=ensureTargetDir,exports.fileExists=fileExists,exports.readDirRecursive=readDirRecursive,exports.readFileContent=readFileContent,exports.readFileSync=readFileSync,exports.runWithConcurrency=runWithConcurrency,exports.scanDirectory=scanDirectory,exports.shouldUpdateFile=shouldUpdateFile,exports.writeFileContent=writeFileContent,exports.writeJsonReport=writeJsonReport;
+"use strict";const s=require("fs"),u=require("path");function _interopDefaultCompat(t){return t&&typeof t=="object"&&"default"in t?t.default:t}const s__default=_interopDefaultCompat(s),u__default=_interopDefaultCompat(u),R=10;async function checkSourceExists(t){try{await s__default.promises.access(t,s__default.constants.F_OK)}catch(e){const i=e;throw i.code==="ENOENT"?new Error(`\u590D\u5236\u6587\u4EF6\u5931\u8D25\uFF1A\u6E90\u6587\u4EF6\u4E0D\u5B58\u5728 - ${t}`):i.code==="EACCES"?new Error(`\u590D\u5236\u6587\u4EF6\u5931\u8D25\uFF1A\u6CA1\u6709\u6743\u9650\u8BBF\u95EE\u6E90\u6587\u4EF6 - ${t}`):new Error(`\u590D\u5236\u6587\u4EF6\u5931\u8D25\uFF1A\u68C0\u67E5\u6E90\u6587\u4EF6\u65F6\u51FA\u9519 - ${t}\uFF0C\u9519\u8BEF\uFF1A${i.message}`)}}async function g(t){try{await s__default.promises.mkdir(t,{recursive:!0})}catch(e){const i=e;throw i.code==="EACCES"?new Error(`\u590D\u5236\u6587\u4EF6\u5931\u8D25\uFF1A\u6CA1\u6709\u6743\u9650\u521B\u5EFA\u76EE\u6807\u76EE\u5F55 - ${t}`):new Error(`\u590D\u5236\u6587\u4EF6\u5931\u8D25\uFF1A\u521B\u5EFA\u76EE\u6807\u76EE\u5F55\u65F6\u51FA\u9519 - ${t}\uFF0C\u9519\u8BEF\uFF1A${i.message}`)}}async function h(t,e){const i=await s__default.promises.readdir(t,{withFileTypes:!0}),r=[];for(const o of i){const c=u__default.join(t,o.name),l=o.isFile(),F=o.isDirectory();if(r.push({path:c,isFile:l,isDirectory:F}),F&&e){const p=await h(c,e);r.push(...p)}}return r}async function C(t,e){try{const[i,r]=await Promise.all([s__default.promises.stat(t),s__default.promises.stat(e)]);return i.mtimeMs>r.mtimeMs||i.size!==r.size}catch{return!0}}async function D(t){try{return await s__default.promises.access(t,s__default.constants.F_OK),!0}catch{return!1}}async function T(t,e,i){const r=[];let o=0;async function c(){for(;o<t.length;){const F=o++,p=await e(t[F]);r[F]=p}}const l=Array(Math.min(i,t.length)).fill(null).map(()=>c());return await Promise.all(l),r}async function copySourceToTarget(t,e,i){const r=Date.now(),{recursive:o,overwrite:c,incremental:l=!1,parallelLimit:F=R}=i;let p=0,w=0,f=0;if((await s__default.promises.stat(t)).isDirectory()){await g(e);const a=await h(t,o),E=a.filter(n=>n.isFile);f=a.filter(n=>n.isDirectory).length;const S=new Set;for(const n of E){const A=u__default.relative(t,n.path),d=u__default.dirname(u__default.join(e,A));S.add(d)}await Promise.all([...S].map(n=>g(n)));const x=await T(E,async n=>{const A=u__default.relative(t,n.path),d=u__default.join(e,A);let m=c;return m||(m=!await D(d)),l&&m&&(m=await C(n.path,d)),m?(await s__default.promises.copyFile(n.path,d),{copied:!0,skipped:!1}):{copied:!1,skipped:!0}},F);for(const n of x)n.copied&&p++,n.skipped&&w++}else{await g(u__default.dirname(e));let a=c;a||(a=!await D(e)),l&&a&&(a=await C(t,e)),a?(await s__default.promises.copyFile(t,e),p++):w++}const y=Date.now()-r;return{copiedFiles:p,skippedFiles:w,copiedDirs:f,executionTime:y}}async function writeFileContent(t,e){try{await s__default.promises.writeFile(t,e,"utf-8")}catch(i){const r=i;throw r.code==="EACCES"?new Error(`\u5199\u5165\u6587\u4EF6\u5931\u8D25\uFF1A\u6CA1\u6709\u6743\u9650\u5199\u5165\u6587\u4EF6 - ${t}`):new Error(`\u5199\u5165\u6587\u4EF6\u5931\u8D25\uFF1A\u5199\u5165\u6587\u4EF6\u65F6\u51FA\u9519 - ${t}\uFF0C\u9519\u8BEF\uFF1A${r.message}`)}}async function scanDirectory(t,e={}){const{includeExtensions:i=[],excludePatterns:r=[],filter:o}=e,c=[];async function l(F){const p=await s__default.promises.readdir(F,{withFileTypes:!0});for(const w of p){const f=u__default.join(F,w.name);if(w.isDirectory()){await l(f);continue}if(!w.isFile()||r.some(E=>E.startsWith("*")?f.endsWith(E.slice(1)):f.includes(E)))continue;const y=u__default.extname(w.name).toLowerCase();if(i.length>0&&!i.includes(y))continue;const a=await s__default.promises.stat(f);o&&!o(f,y,a.size)||c.push({filePath:f,size:a.size,extension:y})}}return await l(t),c}async function writeJsonReport(t,e,i=2){await writeFileContent(t,JSON.stringify(e,null,i))}function writeFileSyncSafely(t,e){const i=u__default.dirname(t);s__default.existsSync(i)||s__default.mkdirSync(i,{recursive:!0}),s__default.writeFileSync(t,e,"utf-8")}function shouldUpdateFileContent(t,e){if(!s__default.existsSync(t))return!0;try{return s__default.readFileSync(t,"utf-8")!==e}catch{return!0}}exports.checkSourceExists=checkSourceExists,exports.copySourceToTarget=copySourceToTarget,exports.scanDirectory=scanDirectory,exports.shouldUpdateFileContent=shouldUpdateFileContent,exports.writeFileContent=writeFileContent,exports.writeFileSyncSafely=writeFileSyncSafely,exports.writeJsonReport=writeJsonReport;

package/dist/common/fs/index.d.cts

@@ -45,75 +45,12 @@ interface CopyResult {
     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>;
-/**
- * 检查文件是否存在
- * @param filePath 文件路径
- * @returns 是否存在
- *
- * @example
- * ```typescript
- * if (await fileExists('/path/to/file')) {
- *   console.log('文件存在')
- * }
- * ```
- */
-declare function fileExists(filePath: string): Promise<boolean>;
-/**
- * 带并发限制的批量执行
- *
- * @param items 待处理项
- * @param handler 处理函数
- * @param concurrency 并发数
- * @returns 处理结果数组，顺序与输入项对应
- *
- * @example
- * ```typescript
- * const urls = ['url1', 'url2', 'url3', 'url4', 'url5']
- * const results = await runWithConcurrency(
- *   urls,
- *   async (url) => fetch(url),
- *   3 // 最多同时处理3个请求
- * )
- * ```
- */
-declare function runWithConcurrency<T, R>(items: T[], handler: (item: T) => Promise<R>, concurrency: number): Promise<R[]>;
 /**
  * 执行文件复制操作（优化版：并行IO）
  * @param sourcePath 源文件或目录路径
@@ -130,21 +67,6 @@ declare function copySourceToTarget(sourcePath: string, targetPath: string, opti
  * @throws 当写入过程中出现错误时抛出异常
  */
 declare function writeFileContent(filePath: string, content: string): Promise<void>;
-/**
- * 读取文件内容
- * @param filePath 文件路径
- * @returns 文件内容字符串
- * @throws 当读取过程中出现错误时抛出异常
- */
-declare function readFileContent(filePath: string): Promise<string>;
-/**
- * 同步读取文件内容
- * @param filePath 文件路径
- * @returns 文件内容字符串
- * @throws 当读取过程中出现错误时抛出异常
- * @deprecated 请使用异步版本 readFileContent
- */
-declare function readFileSync(filePath: string): string;
 /**
  * 扫描目录中的文件信息
  */
@@ -177,20 +99,11 @@ interface ScanDirectoryOptions {
  *
  * @description 递归遍历指定目录下的所有文件，收集每个文件的大小和扩展名信息，
  * 支持按扩展名、路径模式和自定义过滤函数进行过滤。
- * 这是通用的目录扫描函数，可被不同插件复用。
  *
  * @example
  * ```typescript
- * // 扫描所有 .js 文件
  * const jsFiles = await scanDirectory('dist', { includeExtensions: ['.js'] })
- *
- * // 排除 node_modules
  * const files = await scanDirectory('dist', { excludePatterns: ['node_modules'] })
- *
- * // 使用自定义过滤
- * const largeFiles = await scanDirectory('dist', {
- *   filter: (filePath, ext, size) => size > 1024
- * })
  * ```
  */
 declare function scanDirectory(dirPath: string, options?: ScanDirectoryOptions): Promise<ScannedFile[]>;
@@ -209,10 +122,44 @@ declare function scanDirectory(dirPath: string, options?: ScanDirectoryOptions):
  * @example
  * ```typescript
  * await writeJsonReport('dist/report.json', { timestamp: Date.now(), stats: [] })
- * await writeJsonReport('dist/report.json', data, 4)
  * ```
  */
 declare function writeJsonReport(filePath: string, data: object, indent?: number): Promise<void>;
+/**
+ * 同步写入文件内容，自动创建不存在的目录
+ *
+ * @param filePath 文件路径
+ * @param content 文件内容
+ *
+ * @description 同步写入文件，如果目标目录不存在会自动递归创建。
+ * 适用于构建钩子中需要同步写入的场景（如 `transform` 钩子）。
+ *
+ * @throws 当文件写入失败时（如权限不足），抛出 `NodeJS.ErrnoException`
+ *
+ * @example
+ * ```typescript
+ * writeFileSyncSafely('/project/src/auto-imports.d.ts', 'declare global { ... }')
+ * ```
+ */
+declare function writeFileSyncSafely(filePath: string, content: string): void;
+/**
+ * 检查文件内容是否需要更新（同步版本）
+ *
+ * @param filePath 文件路径
+ * @param newContent 新生成的文件内容
+ * @returns 如果需要更新返回 `true`，否则返回 `false`
+ *
+ * @description 对比现有文件内容与新生成的内容，
+ * 仅在内容发生变化时才需要写入，减少不必要的文件 IO 操作。
+ *
+ * @example
+ * ```typescript
+ * if (shouldUpdateFileContent('/project/src/auto-imports.d.ts', newContent)) {
+ *   writeFileSyncSafely('/project/src/auto-imports.d.ts', newContent)
+ * }
+ * ```
+ */
+declare function shouldUpdateFileContent(filePath: string, newContent: string): boolean;
 
-export { checkSourceExists, copySourceToTarget, ensureTargetDir, fileExists, readDirRecursive, readFileContent, readFileSync, runWithConcurrency, scanDirectory, shouldUpdateFile, writeFileContent, writeJsonReport };
+export { checkSourceExists, copySourceToTarget, scanDirectory, shouldUpdateFileContent, writeFileContent, writeFileSyncSafely, writeJsonReport };
 export type { CopyOptions, CopyResult, ScanDirectoryOptions, ScannedFile };

package/dist/common/fs/index.d.mts

@@ -45,75 +45,12 @@ interface CopyResult {
     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>;
-/**
- * 检查文件是否存在
- * @param filePath 文件路径
- * @returns 是否存在
- *
- * @example
- * ```typescript
- * if (await fileExists('/path/to/file')) {
- *   console.log('文件存在')
- * }
- * ```
- */
-declare function fileExists(filePath: string): Promise<boolean>;
-/**
- * 带并发限制的批量执行
- *
- * @param items 待处理项
- * @param handler 处理函数
- * @param concurrency 并发数
- * @returns 处理结果数组，顺序与输入项对应
- *
- * @example
- * ```typescript
- * const urls = ['url1', 'url2', 'url3', 'url4', 'url5']
- * const results = await runWithConcurrency(
- *   urls,
- *   async (url) => fetch(url),
- *   3 // 最多同时处理3个请求
- * )
- * ```
- */
-declare function runWithConcurrency<T, R>(items: T[], handler: (item: T) => Promise<R>, concurrency: number): Promise<R[]>;
 /**
  * 执行文件复制操作（优化版：并行IO）
  * @param sourcePath 源文件或目录路径
@@ -130,21 +67,6 @@ declare function copySourceToTarget(sourcePath: string, targetPath: string, opti
  * @throws 当写入过程中出现错误时抛出异常
  */
 declare function writeFileContent(filePath: string, content: string): Promise<void>;
-/**
- * 读取文件内容
- * @param filePath 文件路径
- * @returns 文件内容字符串
- * @throws 当读取过程中出现错误时抛出异常
- */
-declare function readFileContent(filePath: string): Promise<string>;
-/**
- * 同步读取文件内容
- * @param filePath 文件路径
- * @returns 文件内容字符串
- * @throws 当读取过程中出现错误时抛出异常
- * @deprecated 请使用异步版本 readFileContent
- */
-declare function readFileSync(filePath: string): string;
 /**
  * 扫描目录中的文件信息
  */
@@ -177,20 +99,11 @@ interface ScanDirectoryOptions {
  *
  * @description 递归遍历指定目录下的所有文件，收集每个文件的大小和扩展名信息，
  * 支持按扩展名、路径模式和自定义过滤函数进行过滤。
- * 这是通用的目录扫描函数，可被不同插件复用。
  *
  * @example
  * ```typescript
- * // 扫描所有 .js 文件
  * const jsFiles = await scanDirectory('dist', { includeExtensions: ['.js'] })
- *
- * // 排除 node_modules
  * const files = await scanDirectory('dist', { excludePatterns: ['node_modules'] })
- *
- * // 使用自定义过滤
- * const largeFiles = await scanDirectory('dist', {
- *   filter: (filePath, ext, size) => size > 1024
- * })
  * ```
  */
 declare function scanDirectory(dirPath: string, options?: ScanDirectoryOptions): Promise<ScannedFile[]>;
@@ -209,10 +122,44 @@ declare function scanDirectory(dirPath: string, options?: ScanDirectoryOptions):
  * @example
  * ```typescript
  * await writeJsonReport('dist/report.json', { timestamp: Date.now(), stats: [] })
- * await writeJsonReport('dist/report.json', data, 4)
  * ```
  */
 declare function writeJsonReport(filePath: string, data: object, indent?: number): Promise<void>;
+/**
+ * 同步写入文件内容，自动创建不存在的目录
+ *
+ * @param filePath 文件路径
+ * @param content 文件内容
+ *
+ * @description 同步写入文件，如果目标目录不存在会自动递归创建。
+ * 适用于构建钩子中需要同步写入的场景（如 `transform` 钩子）。
+ *
+ * @throws 当文件写入失败时（如权限不足），抛出 `NodeJS.ErrnoException`
+ *
+ * @example
+ * ```typescript
+ * writeFileSyncSafely('/project/src/auto-imports.d.ts', 'declare global { ... }')
+ * ```
+ */
+declare function writeFileSyncSafely(filePath: string, content: string): void;
+/**
+ * 检查文件内容是否需要更新（同步版本）
+ *
+ * @param filePath 文件路径
+ * @param newContent 新生成的文件内容
+ * @returns 如果需要更新返回 `true`，否则返回 `false`
+ *
+ * @description 对比现有文件内容与新生成的内容，
+ * 仅在内容发生变化时才需要写入，减少不必要的文件 IO 操作。
+ *
+ * @example
+ * ```typescript
+ * if (shouldUpdateFileContent('/project/src/auto-imports.d.ts', newContent)) {
+ *   writeFileSyncSafely('/project/src/auto-imports.d.ts', newContent)
+ * }
+ * ```
+ */
+declare function shouldUpdateFileContent(filePath: string, newContent: string): boolean;
 
-export { checkSourceExists, copySourceToTarget, ensureTargetDir, fileExists, readDirRecursive, readFileContent, readFileSync, runWithConcurrency, scanDirectory, shouldUpdateFile, writeFileContent, writeJsonReport };
+export { checkSourceExists, copySourceToTarget, scanDirectory, shouldUpdateFileContent, writeFileContent, writeFileSyncSafely, writeJsonReport };
 export type { CopyOptions, CopyResult, ScanDirectoryOptions, ScannedFile };