chanjs 2.1.1 → 2.3.1

package/helper/file.js

@@ -1,208 +1,158 @@
-import fs from "fs/promises";
-import { accessSync, unlinkSync, existsSync, mkdirSync } from "fs";
-import path from "path";
-import { fileURLToPath } from "url";
-
-export const dirname = (url) => {
-  const __filename = fileURLToPath(url);
-  return path.dirname(__filename);
-};
-
-/**
- * 获取指定路径的文件树结构
- *
- * @param {string} basePath - 要扫描的基础路径
- * @param {boolean} [deep=true] - 是否深度遍历子目录
- * @returns {Promise<Array<Object>>} 文件树数组，每个元素包含文件/目录信息
- * @returns {string} return[].name - 名称
- * @returns {string} return[].path - 完整路径
- * @returns {string} return[].relativePath - 相对于APP_PATH的路径
- * @returns {'directory'|'file'} return[].type - 类型（目录或文件）
- * @returns {number} return[].size - 大小（字节）
- * @returns {Date} return[].modified - 最后修改时间
- * @returns {number} return[].depth - 深度
- * @returns {Array<Object>} [return[].children] - 子目录内容（仅目录有）
- * @throws {Error} 当路径不存在或没有访问权限时抛出错误
- */
-export const getFileTree = async (basePath, deep = true) => {
-  try {
-    const stats = await fs.stat(basePath);
-    if (!stats.isDirectory()) {
-      return [];
-    }
-
-    const items = await fs.readdir(basePath);
-    const tree = [];
-
-    for (const item of items) {
-      const itemPath = path.join(basePath, item);
-      const itemStats = await fs.stat(itemPath);
-
-      const treeItem = {
-        name: item,
-        path: itemPath,
-        relativePath: path.relative(ROOT_PATH, itemPath),
-        type: itemStats.isDirectory() ? "directory" : "file",
-        size: itemStats.size,
-        modified: itemStats.mtime,
-        depth:
-          itemPath.split(path.sep).length -
-          path.resolve(ROOT_PATH).split(path.sep).length,
-      };
-
-      if (treeItem.type === "directory" && deep) {
-        treeItem.children = await getFileTree(itemPath, deep);
-      }
-
-      tree.push(treeItem);
-    }
-
-    // 排序：文件夹在前，文件在后，名称按字母顺序排列
-    return tree.sort((a, b) => {
-      if (a.type === b.type) {
-        return a.name.localeCompare(b.name, undefined, { sensitivity: "base" });
-      }
-      return a.type === "directory" ? -1 : 1;
-    });
-  } catch (error) {
-    console.error(`获取文件树失败: ${basePath}`, error);
-    throw error;
-  }
-};
-
-/**
- * 读取文件内容（UTF-8编码）
- *
- * @param {string} filePath - 要读取的文件路径
- * @returns {Promise<string>} 文件内容字符串
- * @throws {Error} 当文件不存在、无法读取或不是文件时抛出错误
- */
-export const readFileContent = async (filePath) => {
-  try {
-    // 先检查路径是否安全
-    if (!isPathSafe(filePath, APP_PATH) && !isPathSafe(filePath, ROOT_PATH)) {
-      throw new Error(`路径不安全: ${filePath}`);
-    }
-
-    // 检查是否为文件
-    const stats = await fs.stat(filePath);
-    if (!stats.isFile()) {
-      throw new Error(`不是文件: ${filePath}`);
-    }
-
-    return await fs.readFile(filePath, "utf8");
-  } catch (error) {
-    console.error(`读取文件失败: ${filePath}`, error);
-    throw error;
-  }
-};
-
-/**
- * 保存内容到文件（UTF-8编码）
- *
- * @param {string} filePath - 要保存的文件路径
- * @param {string} content - 要写入的内容
- * @returns {Promise<void>} 无返回值
- * @throws {Error} 当路径不安全、无法写入或发生其他错误时抛出错误
- */
-export const saveFileContent = async (filePath, content) => {
-  try {
-    // 先检查路径是否安全
-    if (!isPathSafe(filePath, APP_PATH) && !isPathSafe(filePath, ROOT_PATH)) {
-      throw new Error(`路径不安全: ${filePath}`);
-    }
-
-    // 确保目录存在
-    const dirname = path.dirname(filePath);
-    await fs.mkdir(dirname, { recursive: true });
-
-    // 写入文件
-    await fs.writeFile(filePath, content, "utf8");
-  } catch (error) {
-    console.error(`保存文件失败: ${filePath}`, error);
-    throw error;
-  }
-};
-
-/**
- * 验证路径是否在基础路径范围内（防止路径遍历攻击）
- *
- * @param {string} requestedPath - 要验证的路径
- * @param {string} basePath - 基础路径，requestedPath必须在此路径下
- * @returns {boolean} 如果路径安全则返回true，否则返回false
- */
-export const isPathSafe = (requestedPath, basePath) => {
-  const resolvedRequestedPath = path.resolve(requestedPath);
-  const resolvedBasePath = path.resolve(basePath);
-  // 检查请求的路径是否以基础路径为前缀
-  return resolvedRequestedPath.startsWith(resolvedBasePath);
-};
-
-/**
- * 删除指定路径的图片文件
- *
- * @param {string} link - 图片文件的路径
- * @returns {boolean} 成功删除返回true，否则返回false
- * @description 同步操作，会检查文件是否存在后再删除
- */
-export function delImg(link) {
-  try {
-    // 先检查路径是否安全
-    if (!isPathSafe(link, APP_PATH)) {
-      console.error(`路径不安全: ${link}`);
-      return false;
-    }
-
-    // 检查文件是否存在
-    accessSync(link);
-
-    // 删除文件
-    unlinkSync(link);
-    return true;
-  } catch (err) {
-    console.error(`删除图片失败: ${link}`, err);
-    return false;
-  }
-}
-
-/**
- * 递归创建目录（同步操作）
- *
- * @param {string} dirname - 要创建的目录路径
- * @returns {boolean} 成功创建或目录已存在返回true，否则返回false
- * @description 类似于mkdir -p命令，会创建所有不存在的父目录
- */
-export function mkdirsSync(dirname) {
-  try {
-    // 先检查路径是否安全
-    if (!isPathSafe(dirname, APP_PATH)) {
-      console.error(`路径不安全: ${dirname}`);
-      return false;
-    }
-
-    if (existsSync(dirname)) {
-      return true;
-    }
-
-    // 递归创建父目录
-    const parentDir = path.dirname(dirname);
-    if (mkdirsSync(parentDir)) {
-      mkdirSync(dirname);
-      return true;
-    }
-
-    return false;
-  } catch (err) {
-    console.error(`创建目录失败: ${dirname}`, err);
-    return false;
-  }
-}
-
-export default {
-  mkdirsSync,
-  delImg,
-  isPathSafe,
-  saveFileContent,
-  readFileContent,
-  getFileTree,
-};
+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);
+}
+
+/**
+ * 删除图片文件
+ * @param {string} filePath - 相对于项目根目录的文件路径
+ * @returns {boolean} 如果文件存在并被删除返回 true，否则返回 false
+ * @description
+ * 删除指定路径的图片文件
+ * 路径是相对于项目根目录（process.cwd()）的
+ * 如果文件不存在，不会抛出错误，直接返回 false
+ * @example
+ * const deleted = delImg('/uploads/avatar/123.jpg');
+ * if (deleted) {
+ *   console.log('图片已删除');
+ * }
+ */
+export function delImg(filePath) {
+  const fullPath = path.join(process.cwd(), filePath);
+  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 (!fs.existsSync(dirPath)) {
+    return [];
+  }
+
+  const stats = fs.statSync(dirPath);
+  if (!stats.isDirectory()) {
+    return [];
+  }
+
+  const items = [];
+  const files = fs.readdirSync(dirPath);
+  
+  const base = basePath || process.cwd();
+
+  for (const file of files) {
+    const fullPath = path.join(dirPath, file);
+    const fileStats = fs.statSync(fullPath);
+
+    if (fileStats.isDirectory() && recursive) {
+      const children = getFileTree(fullPath, recursive, basePath);
+      items.push({
+        name: file,
+        path: fullPath,
+        type: 'directory',
+        children: children
+      });
+    } else if (fileStats.isFile()) {
+      const relativePath = path.relative(base, fullPath).replace(/\\/g, '/');
+      items.push({
+        name: file,
+        path: fullPath,
+        relativePath: relativePath.startsWith('public') ? '/' + relativePath.replace(/^\//, '') : fullPath,
+        type: 'file',
+        size: fileStats.size
+      });
+    }
+  }
+
+  return items;
+}
+
+/**
+ * 读取文件内容
+ * @param {string} filePath - 文件路径
+ * @returns {string} 文件内容
+ * @description
+ * 读取指定文件的内容
+ * @example
+ * const content = readFileContent('/path/to/file.html');
+ */
+export function readFileContent(filePath) {
+  if (!fs.existsSync(filePath)) {
+    throw new Error('文件不存在');
+  }
+
+  const stats = fs.statSync(filePath);
+  if (!stats.isFile()) {
+    throw new Error('路径不是文件');
+  }
+
+  return fs.readFileSync(filePath, 'utf-8');
+}
+
+/**
+ * 保存文件内容
+ * @param {string} filePath - 文件路径
+ * @param {string} content - 文件内容
+ * @returns {void}
+ * @description
+ * 将内容保存到指定文件，如果目录不存在会自动创建
+ * @example
+ * saveFileContent('/path/to/file.html', '<html>...</html>');
+ */
+export function saveFileContent(filePath, content) {
+  const dirPath = path.dirname(filePath);
+  
+  if (!fs.existsSync(dirPath)) {
+    fs.mkdirSync(dirPath, { recursive: true });
+  }
+
+  fs.writeFileSync(filePath, content, 'utf-8');
+}
+
+/**
+ * 检查路径是否安全
+ * @param {string} targetPath - 目标路径
+ * @param {string} basePath - 基础路径
+ * @returns {boolean} 路径是否安全
+ * @description
+ * 检查目标路径是否在基础路径范围内，防止路径遍历攻击
+ * @example
+ * const safe = isPathSafe('/project/file.html', '/project');
+ */
+export function isPathSafe(targetPath, basePath) {
+  const normalizedTarget = path.normalize(targetPath);
+  const normalizedBase = path.normalize(basePath);
+  
+  if (normalizedTarget.includes('..')) {
+    return false;
+  }
+  
+  const relativePath = path.relative(normalizedBase, normalizedTarget);
+  return !relativePath.startsWith('..');
+}

package/helper/filter.js

@@ -0,0 +1,34 @@
+/**
+ * 从数组中的每个对象筛选指定字段
+ * @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: '李四' }
+ * // ]
+ */
+export function filterFields(data, fields) {
+  if (!Array.isArray(data) || data.length === 0) {
+    return [];
+  }
+  return data.map((item) => {
+    const filteredItem = {};
+    for (const field of fields) {
+      if (item.hasOwnProperty(field)) {
+        filteredItem[field] = item[field];
+      }
+    }
+    return filteredItem;
+  });
+}

package/helper/html.js

@@ -1,47 +1,30 @@
-/**
- * 处理最常用的HTML特殊字符实体 - 编码
- * @param {string} str - 需要编码的字符串
- * @returns {string} 编码后的字符串
- */
-export const htmlEncode = (str) => {
-  // 非字符串直接返回，避免报错
-  if (typeof str !== "string") return str;
-
-  // 一次性替换所有特殊字符，减少函数调用
-  return str.replace(
-    /[&<>"' ]/g,
-    (match) =>
-      ({
-        "&": "&amp;",
-        "<": "&lt;",
-        ">": "&gt;",
-        '"': "&quot;",
-        "'": "&#39;",
-        " ": "&nbsp;",
-      }[match])
-  );
-};
-
-/**
- * 处理最常用的HTML特殊字符实体 - 解码
- * @param {string} str - 需要解码的字符串
- * @returns {string} 解码后的字符串
- */
-export const htmlDecode = (str) => {
-  // 非字符串直接返回，避免报错
-  if (typeof str !== "string") return str;
-
-  // 一次性替换所有常见实体，减少函数调用
-  return str.replace(
-    /&amp;|&lt;|&gt;|&nbsp;|&#39;|&quot;/g,
-    (match) =>
-      ({
-        "&amp;": "&",
-        "&lt;": "<",
-        "&gt;": ">",
-        "&nbsp;": " ",
-        "&#39;": "'",
-        "&quot;": '"',
-      }[match])
-  );
-};
+/**
+ * 解码 HTML 实体字符
+ * @param {string} str - 包含 HTML 实体的字符串
+ * @returns {string} 解码后的字符串，如果输入为空则返回空字符串
+ * @description
+ * 将 HTML 实体字符转换为对应的普通字符
+ * 支持的实体字符：
+ * - &amp; -> &
+ * - &lt; -> <
+ * - &gt; -> >
+ * - &quot; -> "
+ * - &apos; -> '
+ * - &nbsp; -> 空格
+ * @example
+ * const html = '&lt;div&gt;Hello &amp; World&lt;/div&gt;';
+ * const decoded = htmlDecode(html);
+ * console.log(decoded); // '<div>Hello & World</div>'
+ */
+export function htmlDecode(str) {
+  if (!str) return "";
+  const htmlEntities = {
+    "&amp;": "&",
+    "&lt;": "<",
+    "&gt;": ">",
+    "&quot;": '"',
+    "&apos;": "'",
+    "&nbsp;": " ",
+  };
+  return str.replace(/&[a-z]+;/gi, (match) => htmlEntities[match] || match);
+}

package/helper/index.js

@@ -1,5 +1,29 @@
-import { db } from "./db.js";
-import { loaderSort, loadConfig } from "./loader.js";
-import { formatTime, formatDateFields } from "./time.js";
-
-export { db, loaderSort, loadConfig, formatTime, formatDateFields };
+export { db } from "./db.js";
+export { prefixDbConfig } from "./db.js";
+export { loaderSort, loadConfig, clearConfigCache, bindInstance, loadController } from "./loader.js";
+export { formatTime } from "./time.js";
+export { formatDateFields } from "./time.js";
+export { default as Cache } from "./cache.js";
+export { dirname } from "./file.js";
+export { delImg } from "./file.js";
+export { getFileTree } from "./file.js";
+export { readFileContent } from "./file.js";
+export { saveFileContent } from "./file.js";
+export { isPathSafe } from "./file.js";
+export { htmlDecode } from "./html.js";
+export { getIp } from "./ip.js";
+export { verifyToken } from "./jwt.js";
+export { generateToken } from "./jwt.js";
+export { setToken } from "./jwt.js";
+export { getToken } from "./jwt.js";
+export { signData } from "./sign.js";
+export { verifySign } from "./sign.js";
+export { aesEncrypt } from "./sign.js";
+export { aesDecrypt } from "./sign.js";
+export { request } from "./request.js";
+export { dataParse } from "./data-parse.js";
+export { arrToObj } from "./data-parse.js";
+export { parseJsonFields } from "./data-parse.js";
+export { buildTree } from "./data-parse.js";
+export { tree, treeById } from "./tree.js";
+export { filterFields } from "./filter.js";

package/helper/ip.js

@@ -1,35 +1,52 @@
 /**
- * 获取用户登录IP地址
- * @param {Object} req - Express请求对象
- * @returns {string} 格式化后的IP地址，默认返回空字符串
+ * 从请求对象中获取客户端真实 IP 地址
+ * @param {Object} req - Express 请求对象
+ * @param {string} [req.ip] - Express 解析的 IP（已包含代理头部解析）
+ * @param {Object} [req.headers] - 请求头对象
+ * @param {string} [req.headers.cf-connecting-ip] - Cloudflare 连接 IP
+ * @returns {string} 客户端 IP 地址，如果无法获取则返回 "0.0.0.0"
+ * @description
+ * 从 Express 的 req.ip 获取客户端 IP。
+ * 
+ * 注意：需要在 App.js 中设置 trust proxy：
+ * app.set("trust proxy", true);
+ * 
+ * 设置 trust proxy 后，Express 会自动从以下头部解析真实 IP：
+ * - X-Forwarded-For（反向代理，如 Nginx）
+ * - X-Real-IP
+ * - CF-Connecting-IP（Cloudflare CDN）
+ * 
+ * 此方法按优先级从以下来源获取 IP 地址：
+ * 1. req.ip（Express 自动解析，已包含代理头部处理）
+ * 2. cf-connecting-ip 请求头（Cloudflare CDN，优先级更高）
+ * 3. 默认值 "0.0.0.0"
+ * 
+ * 此方法适用于部署在反向代理（如 Nginx）或 CDN 后端的应用
+ * @example
+ * app.use((req, res, next) => {
+ *   const ip = getIp(req);
+ *   console.log(`访问 IP: ${ip}`);
+ *   next();
+ * });
  */
-export const getIp = (req) => {
-  // 优先级从高到低获取可能的IP来源
-  const ipSources = [
-    req.ip, // Express内置的IP获取（已处理代理）
-    req.connection?.remoteAddress, // 底层连接的远程地址
-    req.socket?.remoteAddress, // 套接字的远程地址
-    req.connection?.socket?.remoteAddress, // 连接套接字的远程地址
-  ];
-
-  // 从来源中找到第一个有效IP字符串
-  let ip = ipSources.find(
-    (source) => typeof source === "string" && source.trim() !== ""
-  );
-
-  // 若未找到有效IP，直接返回空
-  if (!ip) return "";
-
-  // 处理多IP情况（取第一个）
-  ip = ip.split(",").shift().trim();
-
-  // IPv6转IPv4处理
-  if (ip === "::1") {
-    return "127.0.0.1"; // 本地环回地址
+export function getIp(req) {
+  if (req.ip) {
+    const ip = req.ip;
+    
+    const isLocalAddress = ip === '::1' || 
+                           ip === '127.0.0.1' || 
+                           ip === '0.0.0.0' ||
+                           ip === 'localhost';
+    
+    if (!isLocalAddress) {
+      return ip;
+    }
   }
-  if (ip.startsWith("::ffff:")) {
-    return ip.slice(7); // 去除IPv6映射的IPv4前缀
+  
+  const headers = req.headers || {};
+  if (headers["cf-connecting-ip"]) {
+    return headers["cf-connecting-ip"];
   }
-
-  return ip;
-};
+  
+  return null;
+}