chanjs 2.7.3 → 2.7.5

package/utils/file.js

@@ -1,284 +1,113 @@
-import path from "path";
-import fs from "fs";
-
-/**
- * 获取当前文件的目录路径
- * @param {string} importMetaUrl - import.meta.url 的值
- * @returns {string} 当前文件的目录路径
- * @description
- * 使用 import.meta.url 获取当前模块的 URL，然后提取目录路径
- * 适用于 ES 模块中获取 __dirname 的替代方案
- * @example
- * const __dirname = dirname(import.meta.url);
- * const configPath = path.join(__dirname, 'config.json');
- */
-export function dirname(importMetaUrl) {
-  const url = new URL(importMetaUrl);
-  return path.dirname(url.pathname);
-}
-
 /**
- * 检查路径是否包含目录穿越字符或绝对路径
- * @private
- * @param {string} inputPath - 待检查的路径
- * @returns {boolean} 是否安全
+ * 文件系统操作工具
+ * 提供安全的文件读写/删除/目录扫描功能（内置路径穿越防御）
  */
-function _isPathSafe(inputPath) {
-  if (!inputPath || typeof inputPath !== 'string') return false;
-  // 拒绝绝对路径（/etc/passwd）和 Windows 盘符（C:\）
-  if (path.isAbsolute(inputPath) && !inputPath.startsWith(process.cwd())) return false;
-  // 拒绝目录穿越
-  const normalized = path.normalize(inputPath);
-  if (normalized.includes('..')) return false;
-  return true;
-}
+import path from "path";
+import fs from "fs";
+import logger from "./logger.js";
 
 /**
- * 校验 fullPath 是否落在 process.cwd() 内
- * 用 path.relative 避免 startsWith 前缀绕过（如 /project-evil 匹配 /project）
- * @private
- * @param {string} fullPath - 已解析的绝对路径
- * @returns {boolean} 是否在 cwd 内
+ * 路径安全校验：禁止越界项目根目录
+ * @param {string} inputPath
+ * @returns {string|null} 合法返回绝对路径，非法返回null
  */
-function _isWithinCwd(fullPath) {
+export function safePath(inputPath) {
+  if (!inputPath || typeof inputPath !== "string") return null;
+  const fullPath = path.resolve(process.cwd(), inputPath);
   const rel = path.relative(process.cwd(), fullPath);
-  return !rel.startsWith('..') && !path.isAbsolute(rel);
+  if (rel.startsWith("..") || path.isAbsolute(rel)) return null;
+  return fullPath;
 }
 
 /**
- * 删除图片文件
- * @param {string} filePath - 相对于项目根目录的文件路径
- * @returns {boolean} 如果文件存在并被删除返回 true，否则返回 false
- * @description
- * 删除指定路径的图片文件
- * 路径是相对于项目根目录（process.cwd()）的
- *
- * 安全改进：
- * - 增加防御性路径校验，拒绝绝对路径和目录穿越
- * - 解析后最终路径必须落在 process.cwd() 内，否则拒绝
- * - 业务层即使忘做校验也不会被利用删除任意文件
- * @example
- * const deleted = delImg('/uploads/avatar/123.jpg');
- * if (deleted) {
- *   console.log('图片已删除');
- * }
+ * 删除文件
+ * @param {string} filePath 相对于项目根目录的文件路径
+ * @returns {boolean}
  */
 export function delImg(filePath) {
-  if (!_isPathSafe(filePath)) {
-    console.error('[delImg] 拒绝不安全路径:', filePath);
+  const fullPath = safePath(filePath);
+  if (!fullPath) {
+    logger.error("[delImg] 非法路径/路径越界:", filePath);
     return false;
   }
-  const fullPath = path.resolve(process.cwd(), filePath);
-  // 二次校验：解析后必须仍在 cwd 内（用 relative 避免 startsWith 前缀绕过）
-  if (!_isWithinCwd(fullPath)) {
-    console.error('[delImg] 路径越界:', filePath);
-    return false;
-  }
-  if (fs.existsSync(fullPath)) {
-    fs.unlinkSync(fullPath);
-    return true;
-  }
-  return false;
-}
-
-/**
- * 获取文件树结构
- * @param {string} dirPath - 目录路径
- * @param {boolean} [recursive=true] - 是否递归获取子目录
- * @returns {Array} 文件树数组
- * @description
- * 递归读取目录下的所有文件和子目录，返回树形结构
- * @example
- * const tree = getFileTree('/path/to/directory');
- * // 返回: [{ name: 'file.html', path: '/path/to/directory/file.html', type: 'file' }, ...]
- */
-export function getFileTree(dirPath, recursive = true, basePath = null) {
-  // 路径安全校验：拒绝不安全路径直接返回空数组
-  if (!_isPathSafe(dirPath)) {
-    console.error('[getFileTree] 拒绝不安全路径:', dirPath);
-    return [];
-  }
-  if (!fs.existsSync(dirPath)) {
-    return [];
-  }
-
-  const stats = fs.statSync(dirPath);
-  if (!stats.isDirectory()) {
-    return [];
-  }
-
-  // 二次校验：解析后必须仍在 cwd 内
-  const fullPath = path.resolve(process.cwd(), dirPath);
-  if (!_isWithinCwd(fullPath)) {
-    console.error('[getFileTree] 路径越界:', dirPath);
-    return [];
-  }
-
-  const items = [];
-  const files = fs.readdirSync(dirPath);
-  
-  const base = basePath || process.cwd();
-
-  for (const file of files) {
-    const filePath = path.join(dirPath, file);
-    const fileStats = fs.statSync(filePath);
-
-    if (fileStats.isDirectory() && recursive) {
-      const children = getFileTree(filePath, recursive, basePath);
-      items.push({
-        name: file,
-        path: filePath,
-        type: 'directory',
-        children: children
-      });
-    } else if (fileStats.isFile()) {
-      const relativePath = path.relative(base, filePath).replace(/\\/g, '/');
-      items.push({
-        name: file,
-        path: filePath,
-        relativePath: relativePath.startsWith('public') ? '/' + relativePath.replace(/^\//, '') : filePath,
-        type: 'file',
-        size: fileStats.size
-      });
+  try {
+    if (fs.existsSync(fullPath)) {
+      fs.unlinkSync(fullPath);
+      return true;
     }
+    return false;
+  } catch (err) {
+    logger.error("[delImg] 删除文件异常", fullPath, err.message);
+    return false;
   }
-
-  return items;
 }
 
 /**
- * 读取文件内容
- * @param {string} filePath - 文件路径
- * @returns {string} 文件内容
- * @description
- * 读取指定文件的内容
- *
- * 安全改进：
- * - 增加防御性路径校验，拒绝绝对路径和目录穿越
- * - 解析后最终路径必须落在 process.cwd() 内，否则拒绝
- * - 与 saveFileContent 保持一致的安全策略
- * @example
- * const content = readFileContent('/path/to/file.html');
+ * 读取文本文件内容
+ * @param {string} filePath
+ * @returns {string} utf8 文件文本内容
+ * @throws 非法路径或文件不存在时抛异常
  */
 export function readFileContent(filePath) {
-  if (!_isPathSafe(filePath)) {
-    throw new Error(`[readFileContent] 拒绝不安全路径: ${filePath}`);
-  }
-  const fullPath = path.isAbsolute(filePath) ? filePath : path.resolve(process.cwd(), filePath);
-  // 二次校验：解析后必须仍在 cwd 内（用 relative 避免 startsWith 前缀绕过）
-  if (!_isWithinCwd(fullPath)) {
-    throw new Error(`[readFileContent] 路径越界: ${filePath}`);
-  }
-  if (!fs.existsSync(fullPath)) {
-    throw new Error('文件不存在');
-  }
-
-  const stats = fs.statSync(fullPath);
-  if (!stats.isFile()) {
-    throw new Error('路径不是文件');
-  }
-
-  return fs.readFileSync(fullPath, 'utf-8');
+  const fullPath = safePath(filePath);
+  if (!fullPath) throw new Error(`[readFileContent] 拒绝不安全/越界路径: ${filePath}`);
+  if (!fs.existsSync(fullPath)) throw new Error("文件不存在");
+  if (!fs.statSync(fullPath).isFile()) throw new Error("目标路径不是文件");
+  return fs.readFileSync(fullPath, "utf-8");
 }
 
 /**
- * 保存文件内容
- * @param {string} filePath - 文件路径
- * @param {string} content - 文件内容
- * @returns {void}
- * @description
- * 将内容保存到指定文件，如果目录不存在会自动创建
- *
- * 安全改进：
- * - 增加防御性路径校验，拒绝绝对路径和目录穿越
- * - 解析后最终路径必须落在 process.cwd() 内，否则拒绝
- * - 业务层即使忘做校验也不会被写入任意路径
- * @example
- * saveFileContent('/path/to/file.html', '<html>...</html>');
+ * 保存/覆写文件，不存在目录自动递归创建
+ * @param {string} filePath
+ * @param {string} content
+ * @throws 非法路径时抛异常
  */
 export function saveFileContent(filePath, content) {
-  if (!_isPathSafe(filePath)) {
-    throw new Error(`[saveFileContent] 拒绝不安全路径: ${filePath}`);
-  }
-  const fullPath = path.isAbsolute(filePath) ? filePath : path.resolve(process.cwd(), filePath);
-  // 二次校验：解析后必须仍在 cwd 内
-  if (!_isWithinCwd(fullPath)) {
-    throw new Error(`[saveFileContent] 路径越界: ${filePath}`);
-  }
-
+  const fullPath = safePath(filePath);
+  if (!fullPath) throw new Error(`[saveFileContent] 拒绝不安全/越界路径: ${filePath}`);
   const dirPath = path.dirname(fullPath);
-
-  if (!fs.existsSync(dirPath)) {
-    fs.mkdirSync(dirPath, { recursive: true });
-  }
-
-  fs.writeFileSync(fullPath, content, 'utf-8');
+  if (!fs.existsSync(dirPath)) fs.mkdirSync(dirPath, { recursive: true });
+  fs.writeFileSync(fullPath, content, "utf-8");
 }
 
 /**
- * 检查路径是否安全
- * @param {string} targetPath - 目标路径
- * @param {string} basePath - 基础路径
- * @returns {boolean} 路径是否安全
- * @description
- * 检查目标路径是否在基础路径范围内，防止路径遍历攻击
- * @example
- * const safe = isPathSafe('/project/file.html', '/project');
+ * 获取指定目录下一级文件夹名称列表（过滤隐藏目录）
+ * @param {string} folderPath
+ * @returns {string[]}
  */
-export function isPathSafe(targetPath, basePath) {
-  const normalizedTarget = path.normalize(targetPath);
-  const normalizedBase = path.normalize(basePath);
-  
-  if (normalizedTarget.includes('..')) {
-    return false;
+export function getFolders(folderPath) {
+  const fullPath = safePath(folderPath);
+  if (!fullPath) {
+    logger.error("[getFolders] 非法路径/路径越界:", folderPath);
+    return [];
+  }
+  try {
+    if (!fs.existsSync(fullPath)) return [];
+    return fs.readdirSync(fullPath)
+      .filter(name => !name.startsWith(".") && fs.statSync(path.join(fullPath, name)).isDirectory());
+  } catch (err) {
+    logger.error("[getFolders] 读取目录异常", fullPath, err.message);
+    return [];
   }
-  
-  const relativePath = path.relative(normalizedBase, normalizedTarget);
-  return !relativePath.startsWith('..');
 }
 
 /**
- * 获取指定文件夹下的所有文件夹
- * @param {string} folderPath - 文件夹路径
- * @returns {Array<string>} 文件夹名称数组
- * @description
- * 同步获取指定文件夹下的所有文件夹（不包含隐藏文件）
- * @example
- * const folders = getFolders('/path/to/directory');
- * // 返回: ['default', 'test', ...]
+ * 同步获取目录下一级全部 .html 文件名称
+ * @param {string} folderPath
+ * @returns {string[]}
  */
-export function getFolders(folderPath) {
-  // 路径安全校验：拒绝不安全路径直接返回空数组
-  if (!_isPathSafe(folderPath)) {
-    console.error('[getFolders] 拒绝不安全路径:', folderPath);
-    return [];
-  }
-  if (!fs.existsSync(folderPath)) {
+export function getHtmlFilesSync(folderPath) {
+  const fullPath = safePath(folderPath);
+  if (!fullPath) {
+    logger.error("[getHtmlFilesSync] 非法路径/路径越界:", folderPath);
     return [];
   }
-  // 二次校验：解析后必须仍在 cwd 内
-  const fullPath = path.resolve(process.cwd(), folderPath);
-  if (!_isWithinCwd(fullPath)) {
-    console.error('[getFolders] 路径越界:', folderPath);
+  try {
+    if (!fs.existsSync(fullPath)) return [];
+    return fs.readdirSync(fullPath)
+      .filter(name => fs.statSync(path.join(fullPath, name)).isFile() && path.extname(name).toLowerCase() === ".html");
+  } catch (err) {
+    logger.error("[getHtmlFilesSync] 读取目录异常", fullPath, err.message);
     return [];
   }
-
-  const items = fs.readdirSync(folderPath);
-  const folders = [];
-  
-  for (const item of items) {
-    if (item.startsWith('.')) continue;
-    
-    const itemPath = path.join(folderPath, item);
-    try {
-      const stat = fs.statSync(itemPath);
-      if (stat.isDirectory()) {
-        folders.push(item);
-      }
-    } catch (err) {
-      continue;
-    }
-  }
-  
-  return folders;
 }

package/utils/filter.js

@@ -1,35 +1,32 @@
 /**
- * 从数组中的每个对象筛选指定字段
- * @param {Array<Object>} data - 要处理的对象数组
- * @param {Array<string>} fields - 需要保留的字段名数组
- * @returns {Array<Object>} 只包含指定字段的新对象数组
- * @description
- * 遍历数组中的每个对象，只保留指定的字段
- * 返回一个新的数组，不修改原始数据
+ * 从对象数组批量筛选指定字段，返回全新数组与全新对象，不修改原始入参数据
  * @example
- * const data = [
- *   { id: 1, name: '张三', age: 25, email: 'test@example.com' },
- *   { id: 2, name: '李四', age: 30, email: 'demo@example.com' }
- * ];
- * const result = filterFields(data, ['id', 'name']);
- * console.log(result);
- * // [
- * //   { id: 1, name: '张三' },
- * //   { id: 2, name: '李四' }
- * // ]
+ *   filterFields([{ id: 1, name: '张三', age: 25 }], ['id', 'name'])
+ *   // [{ id: 1, name: '张三' }]
+ * @param {Array<Object>} data 原始对象数组
+ * @param {string[]} fields 需要保留的字段名列表
+ * @returns {Array<Object>} 仅包含指定字段的新对象数组
  */
 export function filterFields(data, fields) {
-  if (!Array.isArray(data) || data.length === 0) {
-    return [];
-  }
+  // 校验数组参数，非数组直接返回空数组
+  if (!Array.isArray(data)) return [];
+  // 字段列表非数组/空数组直接返回空对象数组
+  if (!Array.isArray(fields) || fields.length === 0) return data.map(() => ({}));
+
   return data.map((item) => {
-    const filteredItem = {};
+    // 当前项不是普通对象，返回空对象规避取值报错
+    if (item === null || typeof item !== "object" || Array.isArray(item)) {
+      return {};
+    }
+    const filtered = {};
     for (const field of fields) {
-      // 用原型上的方法调用，避免 item 重写 hasOwnProperty 导致原型污染
+      // 跳过非字符串字段名，避免异常key
+      if (typeof field !== "string") continue;
+      // 使用原型方法，防止item重写hasOwnProperty造成原型污染漏洞
       if (Object.prototype.hasOwnProperty.call(item, field)) {
-        filteredItem[field] = item[field];
+        filtered[field] = item[field];
       }
     }
-    return filteredItem;
+    return filtered;
   });
-}
+}

package/utils/html.js

@@ -1,5 +1,12 @@
 /**
- * 标准 HTML 编码（art-template {{}} 使用）
+ * HTML 处理工具
+ * 提供 HTML 实体编解码、script标签深度转义、HTML文本提取图片URL功能
+ */
+
+/**
+ * 标准 HTML 实体编码（适配 art-template {{ }} 插值输出）
+ * @param {any} str 待转义文本
+ * @returns {string}
  */
 export function htmlEncode(str) {
   if (typeof str !== 'string') return '';
@@ -12,47 +19,56 @@ export function htmlEncode(str) {
 }
 
 /**
- * 【适配 art-template {{@}}】二次转义 script 标签
- * 必须这样写才能防 XSS！
+ * 深度危险标签二次转义（适配 art-template {{@ }} 原始输出防XSS）
+ * 双重转义 script/iframe/object/embed/form 标签
+ * @param {any} str 待处理HTML文本
+ * @returns {string}
  */
 export const escapeScript = (str) => {
   if (typeof str !== 'string') return '';
-  return str
-    // 二次转义 → 经过 {{@}} 解码后变成 <script>
-    .replace(/<script\b[^>]*>/gi, '&amp;lt;script&amp;gt;')
-    .replace(/<\/script>/gi, '&amp;lt;/script&amp;gt;');
+  // 一次性匹配所有危险开始/结束标签，统一替换为双重转义
+  return str.replace(/<\/?(script|iframe|object|embed|form)\b[^>]*>/gi, (match) => {
+    return match.replace(/</g, '&amp;lt;').replace(/>/g, '&amp;gt;');
+  });
 };
 
 /**
- * HTML 解码
- * 支持：命名实体（amp/lt/gt/quot/apos/nbsp）+ 十六进制数字实体（&#x...;）+ 十进制数字实体（&#...;）
+ * HTML 实体解码
+ * 支持：命名实体(amp/lt/gt/quot/apos/nbsp)、十进制数字实体、十六进制Unicode实体
+ * @param {any} str 带实体编码的字符串
+ * @returns {string}
  */
+const NAMED_ENTITIES = { '&amp;': '&', '&lt;': '<', '&gt;': '>', '&quot;': '"', '&apos;': "'", '&nbsp;': ' ' };
+
 export function htmlDecode(str) {
   if (typeof str !== 'string') return '';
-  const entities = {
-    '&amp;': '&',
-    '&lt;': '<',
-    '&gt;': '>',
-    '&quot;': '"',
-    '&apos;': "'",
-    '&nbsp;': ' ',
-  };
   return str
-    .replace(/&(amp|lt|gt|quot|apos|nbsp);/g, m => entities[m])
-    // 十六进制数字实体：&#x3C; → <（含 2/3/4/5/6 位 Unicode）
-    .replace(/&#x([0-9a-f]+);/gi, (_, h) => {
-      try {
-        return String.fromCodePoint(parseInt(h, 16));
-      } catch {
-        return '';
-      }
+    .replace(/&(amp|lt|gt|quot|apos|nbsp);/g, match => NAMED_ENTITIES[match])
+    .replace(/&#x([0-9a-f]+);/gi, (_, hexStr) => {
+      try { return String.fromCodePoint(parseInt(hexStr, 16)); }
+      catch { return ''; }
     })
-    // 十进制数字实体：&#60; → <
-    .replace(/&#(\d+);/g, (_, d) => {
-      try {
-        return String.fromCodePoint(parseInt(d, 10));
-      } catch {
-        return '';
-      }
+    .replace(/&#(\d+);/g, (_, decStr) => {
+      try { return String.fromCodePoint(parseInt(decStr, 10)); }
+      catch { return ''; }
     });
-}
+}
+
+/**
+ * 从HTML字符串中批量提取全部img标签src图片地址
+ * @param {string} str 富文本/HTML源码
+ * @returns {string[]}
+ */
+export function filterImgFromStr(str) {
+  if (typeof str !== 'string' || str.trim() === '') return [];
+
+  const imgReg = /<img\b[^>]*?(?:>|\/>)/gi;
+  const srcReg = /src\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+))/i;
+
+  const tagList = str.match(imgReg);
+  if (!tagList) return [];
+
+  return tagList
+    .map(tag => tag.match(srcReg)?.[1]?.trim())
+    .filter(Boolean);
+}

package/utils/index.js

@@ -1,22 +1,33 @@
 /**
- * 通用工具模块 - 时间/文件/HTML/IP/数据解析/树/过滤
+ * 工具聚合层
+ *
+ * 业务侧使用方式：
+ *   import { helper } from "chanjs";
+ *   const { tree, getIp, formatDateFields } = helper;
+ *
+ * 也可直接从子模块导入（精确引用）：
+ *   import { getIp } from "chanjs/utils/ip.js";
  */
+
 // 时间处理
-export { formatTime, formatDateFields } from "./time.js";
+export { formatDateFields } from "./time.js";
 
 // 文件操作
 export {
-  dirname,
   delImg,
-  getFileTree,
   readFileContent,
   saveFileContent,
-  isPathSafe,
   getFolders,
+  getHtmlFilesSync,
 } from "./file.js";
 
 // HTML 处理
-export { htmlDecode, htmlEncode, escapeScript } from "./html.js";
+export {
+  htmlEncode,
+  htmlDecode,
+  escapeScript,
+  filterImgFromStr,
+} from "./html.js";
 
 // IP 获取
 export { getIp } from "./ip.js";
@@ -25,10 +36,13 @@ export { getIp } from "./ip.js";
 export { request } from "./request.js";
 
 // 数据解析
-export { dataParse, arrToObj, parseJsonFields, buildTree } from "./data-parse.js";
+export { arrToObj, getChildrenId } from "./data-parse.js";
 
 // 树形结构
 export { tree, treeById } from "./tree.js";
 
 // 字段过滤
 export { filterFields } from "./filter.js";
+
+// 分页工具
+export { pages } from "./pages.js";