chanjs 2.7.4 → 2.7.6

package/doc/Aop.md

@@ -1,269 +0,0 @@
-# Aop 轻量级切面类使用文档
-
-## 概述
-`Aop` 是一个轻量级的 JavaScript 切面编程（AOP）工具类，支持为对象方法注册并执行 `before`（前置）、`after`（后置）、`error`（异常）三种类型的切面函数，适用于日志记录、参数校验、异常处理等横切关注点场景。
-
-## 特性
-- 支持链式调用注册切面函数
-- 内置切面类型校验，仅支持 `before`/`after`/`error` 三种常用类型
-- 支持切面规则启用/禁用，灵活控制切面执行
-- 保留原方法上下文，保证方法执行正确性
-- 完善的错误处理，切面执行异常不阻断主流程
-
-## 安装与引入
-### 方式1：ESModule 引入
-```javascript
-import { Aop, aop } from './aop.js';
-```
-
-## 核心 API
-
-### 1. 切面注册（set）
-注册一个切面函数，返回当前实例支持链式调用。
-
-#### 语法
-```javascript
-aop.set(name, fn)
-```
-
-#### 参数
-| 参数 | 类型 | 说明 |
-|------|------|------|
-| name | string | 切面名称（非空字符串） |
-| fn | Function | 切面执行函数，入参为切面上下文对象 |
-
-#### 示例
-```javascript
-// 注册日志切面
-aop.set('logger', async (params) => {
-  console.log(`[${params.methodName}] 执行时间：${new Date().toISOString()}`);
-  console.log(`参数：`, params.args);
-});
-
-// 注册参数校验切面（链式调用）
-aop.set('paramCheck', async (params) => {
-  const [id] = params.args;
-  if (!id || typeof id !== 'number') {
-    throw new Error(`[${params.methodName}] 参数id必须是数字`);
-  }
-});
-```
-
-### 2. 获取切面（get）
-获取已注册的切面函数。
-
-#### 语法
-```javascript
-aop.get(name)
-```
-
-#### 参数
-| 参数 | 类型 | 说明 |
-|------|------|------|
-| name | string | 切面名称 |
-
-#### 返回值
-| 类型 | 说明 |
-|------|------|
-| Function \| null | 存在则返回切面函数，否则返回 null |
-
-#### 示例
-```javascript
-const logger = aop.get('logger');
-if (logger) {
-  console.log('日志切面已注册');
-}
-```
-
-### 3. 移除切面（remove）
-移除指定名称的切面函数。
-
-#### 语法
-```javascript
-aop.remove(name)
-```
-
-#### 参数
-| 参数 | 类型 | 说明 |
-|------|------|------|
-| name | string | 切面名称 |
-
-#### 示例
-```javascript
-// 移除日志切面
-aop.remove('logger');
-```
-
-### 4. 清空所有切面（clear）
-清空已注册的所有切面函数。
-
-#### 语法
-```javascript
-aop.clear()
-```
-
-#### 示例
-```javascript
-// 清空所有切面
-aop.clear();
-```
-
-### 5. 绑定切面到方法（wrap）
-核心方法，为目标对象的指定方法绑定切面规则。
-
-#### 语法
-```javascript
-aop.wrap(instance, config)
-```
-
-#### 参数
-| 参数 | 类型 | 说明 |
-|------|------|------|
-| instance | object | 目标实例（非空对象） |
-| config | object | 切面配置，格式：`{ 方法名: [{ type: 切面类型, enabled: 是否启用, 切面名称: 配置 }] }` |
-
-#### 配置规则说明
-| 字段 | 类型 | 说明 | 必填 | 默认值 |
-|------|------|------|------|--------|
-| type | string | 切面类型（before/after/error） | 是 | - |
-| enabled | boolean | 是否启用该规则 | 否 | true |
-| [切面名称] | any | 自定义配置，会透传给切面函数 | 否 | {} |
-
-#### 返回值
-| 类型 | 说明 |
-|------|------|
-| object | 绑定后的实例对象 |
-
-## 完整使用示例
-
-### 步骤1：定义目标类
-```javascript
-// 示例控制器类
-class UserController {
-  async getUser(id) {
-    console.log(`获取用户信息，ID：${id}`);
-    if (id === 0) {
-      throw new Error('用户ID不能为0');
-    }
-    return { id, name: '张三', age: 20 };
-  }
-}
-```
-
-### 步骤2：注册切面函数
-```javascript
-import { aop } from './aop.js';
-
-// 1. 注册参数校验切面
-aop.set('paramCheck', async (params) => {
-  const [id] = params.args;
-  console.log(`[paramCheck] 校验参数：id = ${id}`);
-  if (typeof id !== 'number') {
-    throw new Error(`参数id必须是数字，当前值：${id}`);
-  }
-});
-
-// 2. 注册日志切面
-aop.set('logger', async (params) => {
-  const { methodName, args, result, error } = params;
-  if (params.type === 'before') {
-    console.log(`[logger] 方法${methodName}开始执行，参数：`, args);
-  } else if (params.type === 'after') {
-    console.log(`[logger] 方法${methodName}执行完成，结果：`, result);
-  } else if (params.type === 'error') {
-    console.log(`[logger] 方法${methodName}执行异常：`, error.message);
-  }
-});
-
-// 3. 注册异常处理切面
-aop.set('errorHandler', async (params) => {
-  console.log(`[errorHandler] 捕获异常：${params.error.message}，执行兜底逻辑`);
-  // 可在这里添加异常上报、数据清理等逻辑
-});
-```
-
-### 步骤3：绑定切面到方法并使用
-```javascript
-// 创建实例
-const userController = new UserController();
-
-// 绑定切面规则
-aop.wrap(userController, {
-  getUser: [
-    // 前置切面：参数校验 + 日志
-    { type: 'before', enabled: true, paramCheck: true, logger: true },
-    // 后置切面：日志
-    { type: 'after', enabled: true, logger: true },
-    // 异常切面：日志 + 异常处理
-    { type: 'error', enabled: true, logger: true, errorHandler: true }
-  ]
-});
-
-// 测试正常执行
-async function testNormal() {
-  try {
-    const result = await userController.getUser(1);
-    console.log('最终结果：', result);
-  } catch (e) {
-    console.log('测试异常：', e.message);
-  }
-}
-
-// 测试异常执行
-async function testError() {
-  try {
-    const result = await userController.getUser(0);
-    console.log('最终结果：', result);
-  } catch (e) {
-    console.log('测试异常：', e.message);
-  }
-}
-
-// 执行测试
-testNormal();
-// testError();
-```
-
-### 执行结果（testNormal）
-```
-[paramCheck] 校验参数：id = 1
-[logger] 方法getUser开始执行，参数： [1]
-获取用户信息，ID：1
-[logger] 方法getUser执行完成，结果： { id: 1, name: '张三', age: 20 }
-最终结果： { id: 1, name: '张三', age: 20 }
-```
-
-### 执行结果（testError）
-```
-[paramCheck] 校验参数：id = 0
-[logger] 方法getUser开始执行，参数： [0]
-获取用户信息，ID：0
-[logger] 方法getUser执行异常： 用户ID不能为0
-[errorHandler] 捕获异常：用户ID不能为0，执行兜底逻辑
-测试异常： 用户ID不能为0
-```
-
-## 切面函数上下文参数说明
-切面函数的入参是一个上下文对象，包含以下字段：
-
-| 字段 | 类型 | 说明 | 可用切面类型 |
-|------|------|------|--------------|
-| ctx | object | 原方法的执行上下文（实例对象） | all |
-| methodName | string | 被包装的方法名称 | all |
-| args | Array | 原方法的入参数组（浅拷贝） | all |
-| originalMethod | Function | 原始未包装的方法 | all |
-| result | any | 原方法执行结果 | after |
-| error | Error | 原方法抛出的异常 | error |
-| params | object | 切面规则中配置的自定义参数 | all |
-
-## 注意事项
-1. **异步支持**：切面函数和被包装的方法均支持异步（async/await），内部会自动处理异步执行顺序
-2. **上下文保留**：原方法的 `this` 指向会被正确保留，无需额外处理
-3. **异常处理**：`error` 类型切面执行完成后，异常会被重新抛出，不会阻断原有异常流程
-4. **规则过滤**：`enabled: false` 的规则会被自动过滤，不执行对应的切面
-5. **切面名称冲突**：不要使用 `type`/`enabled` 作为切面名称（内置关键字）
-
-### 总结
-1. `Aop` 类核心提供切面注册（`set`）和方法包装（`wrap`）能力，仅支持 `before`/`after`/`error` 三种切面类型。
-2. 切面函数接收包含上下文、参数、结果/异常的完整入参，可灵活实现各类横切逻辑。
-3. 通过配置规则的 `enabled` 字段可动态控制切面是否生效，异常切面执行后会重新抛出异常，保证原有错误流程不受影响。

package/doc/Email.md

@@ -1,114 +0,0 @@
-# 邮件发送工具模块文档
-## 1. 模块概述
-该模块基于 `nodemailer` 实现邮件发送功能，并提供注册验证码、重置密码验证码两类邮件的HTML模板生成能力，适用于系统中的邮件通知场景（如用户注册、密码重置）。
-
-## 2. 依赖
-- 第三方库：`nodemailer`（需提前安装）
-- 全局配置：`Chan.config` 需包含 `EMAIL`（邮件服务配置）和 `APP_NAME`（应用名称）字段
-
-## 3. 配置说明
-`Chan.config.EMAIL` 需包含以下配置项：
-
-| 配置项 | 类型 | 说明 |
-|--------|------|------|
-| HOST | string | 邮件服务器主机地址（如 smtp.qq.com） |
-| PORT | string/number | 邮件服务器端口（如 465、587） |
-| SECURE | string | 是否启用SSL加密（"true" 或 "false"） |
-| USER | string | 发件人邮箱账号 |
-| PASS | string | 发件人邮箱授权码/密码 |
-| FROM | string | 发件人显示格式（如 "应用名称 <xxx@xxx.com>"） |
-
-## 4. API 详情
-### 4.1 sendMail - 发送邮件
-#### 功能描述
-创建邮件传输器，验证邮件服务配置后发送邮件，支持纯文本和HTML格式内容。
-
-#### 函数签名
-```javascript
-async function sendMail(to, subject, text, html = null) => Promise<Object>
-```
-
-#### 参数说明
-| 参数名 | 类型 | 必填 | 默认值 | 说明 |
-|--------|------|------|--------|------|
-| to | string | 是 | - | 收件人邮箱地址 |
-| subject | string | 是 | - | 邮件主题 |
-| text | string | 是 | - | 邮件纯文本内容 |
-| html | string \| null | 否 | null | 邮件HTML内容，未传则使用text内容替代 |
-
-#### 返回值
-`Promise<Object>`：nodemailer 发送邮件后的响应对象（包含 messageId 等信息）。
-
-#### 异常抛出
-- 邮件服务配置验证失败：抛出 `Error("邮件服务未配置")`
-- 邮件发送失败：打印错误日志并抛出原错误对象
-
-#### 使用示例
-```javascript
-import { sendMail, genRegEmailHtml } from './chanjs/common/email.js';
-
-// 发送注册验证码邮件
-async function sendRegCodeEmail(email, code) {
-  const subject = `${Chan.config.APP_NAME} 注册验证码`;
-  const text = `您的注册验证码是：${code}，有效期10分钟。`;
-  const html = genRegEmailHtml(code);
-  
-  try {
-    const result = await sendMail(email, subject, text, html);
-    console.log("邮件发送成功：", result.messageId);
-  } catch (error) {
-    console.error("发送失败：", error);
-  }
-}
-```
-
-### 4.2 genRegEmailHtml - 生成注册验证码邮件HTML模板
-#### 功能描述
-生成美观的注册验证码邮件HTML字符串，包含应用名称、验证码、有效期等信息。
-
-#### 函数签名
-```javascript
-function genRegEmailHtml(code, minutes = 10) => string
-```
-
-#### 参数说明
-| 参数名 | 类型 | 必填 | 默认值 | 说明 |
-|--------|------|------|--------|------|
-| code | string | 是 | - | 注册验证码 |
-| minutes | number | 否 | 10 | 验证码有效期（分钟） |
-
-#### 返回值
-`string`：完整的邮件HTML字符串。
-
-### 4.3 genResetPasswordEmail - 生成重置密码邮件HTML模板
-#### 功能描述
-生成重置密码验证码的邮件HTML字符串，样式与注册邮件区分，突出重置密码场景。
-
-#### 函数签名
-```javascript
-function genResetPasswordEmail(code, minutes = 10) => string
-```
-
-#### 参数说明
-| 参数名 | 类型 | 必填 | 默认值 | 说明 |
-|--------|------|------|--------|------|
-| code | string | 是 | - | 重置密码验证码 |
-| minutes | number | 否 | 10 | 验证码有效期（分钟） |
-
-#### 返回值
-`string`：完整的邮件HTML字符串。
-
-## 5. 模板样式说明
-- 注册邮件模板：头部背景色为蓝色（#007bff），最大宽度750px，整体风格简洁清晰。
-- 重置密码邮件模板：头部背景色为绿色（#28a745），最大宽度600px，布局与注册邮件一致，文案适配重置密码场景。
-- 两类模板均包含：应用名称、验证码醒目展示、有效期提示、版权信息，适配主流邮箱的HTML渲染规则。
-
-## 6. 异常处理建议
-1. 调用 `sendMail` 时务必使用 `try/catch` 捕获异常，避免程序崩溃；
-2. 邮件服务配置错误（如HOST/PORT错误）会触发“邮件服务未配置”异常，需检查 `Chan.config.EMAIL` 配置；
-3. 发送失败（如收件人邮箱格式错误、服务器拒绝）需记录详细错误日志，便于排查问题。
-
-## 7. 扩展建议
-1. 可新增更多邮件模板（如通知类、营销类），参考现有模板结构封装；
-2. 可添加邮件发送重试机制，提升稳定性；
-3. 可将模板样式抽离为配置项，支持自定义主题色、模板宽度等。

package/doc/Event.md

@@ -1,232 +0,0 @@
-# chanjs Event 类使用文档
-## 概述
-`chanjs` 中的 `Event` 类基于 Node.js 内置 `EventEmitter` 封装，提供轻量级的事件订阅/发布能力，支持事件注册、触发、注销等核心操作，接口简洁且保持与原生 `EventEmitter` 兼容，适用于业务中解耦组件间的通信场景。
-
-## 前置准备
-### 1. 引入方式
-```javascript
-import { Event } from "chanjs";
-
-// 方式1：创建实例使用
-const event = new Event();
-
-// 方式2：直接使用内置单例（推荐全局通信）
-import { event } from "chanjs";
-```
-
-### 2. 通用约定
-- 事件名（`eventName`）建议使用**语义化字符串**（如 `user:login`、`order:created`），避免命名冲突
-- 监听器函数（`listener`）接收的参数为触发事件时传入的 `data`，支持任意类型数据
-- 所有方法均返回当前 `Event` 实例，支持**链式调用**
-
-## 核心方法使用指南
-### 1. 注册事件监听器 - on
-#### 作用
-为指定事件注册一个持久化的监听器（事件触发时会执行该函数），支持为同一事件注册多个监听器。
-#### 传参格式
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| eventName | String | 是 | 事件名称（如 `user:login`） |
-| listener | Function | 是 | 事件触发时执行的回调函数，参数为触发事件传入的 `data` |
-#### 使用示例
-```javascript
-// 注册单个事件监听器
-event.on("user:login", (data) => {
-  console.log("用户登录事件触发：", data);
-  // 业务逻辑：记录登录日志、更新最后登录时间等
-});
-
-// 为同一事件注册多个监听器
-event.on("order:created", (orderData) => {
-  console.log("订单创建-日志记录：", orderData.id);
-});
-event.on("order:created", (orderData) => {
-  console.log("订单创建-消息推送：", orderData.userId);
-});
-
-// 链式调用注册多个事件
-event
-  .on("article:add", (article) => console.log("新增文章：", article.title))
-  .on("article:delete", (id) => console.log("删除文章ID：", id));
-```
-
-### 2. 触发事件 - emit
-#### 作用
-触发指定名称的事件，执行该事件下所有已注册的监听器，并传递数据给监听器函数。
-#### 传参格式
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| eventName | String | 是 | 要触发的事件名称 |
-| data | Any | 否 | 传递给监听器的事件数据（任意类型：对象、数组、基本类型等） |
-#### 使用示例
-```javascript
-// 触发用户登录事件，传递用户数据
-event.emit("user:login", {
-  userId: 1001,
-  username: "test_user",
-  loginTime: new Date(),
-  ip: "127.0.0.1"
-});
-
-// 触发订单创建事件，传递订单数据
-const orderData = {
-  id: "ORD20260323001",
-  userId: 1001,
-  amount: 99.9,
-  createTime: new Date()
-};
-event.emit("order:created", orderData);
-
-// 触发无数据的事件
-event.emit("system:refresh");
-```
-
-### 3. 注销事件监听器 - off
-#### 作用
-注销指定事件下的某个具体监听器，仅移除该监听器，不影响同一事件的其他监听器。
-#### 传参格式
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| eventName | String | 是 | 事件名称 |
-| listener | Function | 是 | 要注销的监听器函数（需与注册时的函数引用一致） |
-#### 使用示例
-```javascript
-// 定义可复用的监听器函数
-const loginListener = (data) => {
-  console.log("用户登录监听器：", data);
-};
-
-// 注册监听器
-event.on("user:login", loginListener);
-
-// 触发事件（监听器会执行）
-event.emit("user:login", { userId: 1001 });
-
-// 注销指定监听器
-event.off("user:login", loginListener);
-
-// 再次触发事件（该监听器不再执行）
-event.emit("user:login", { userId: 1001 });
-
-// 链式注销多个监听器
-const articleAddListener = (data) => console.log("新增文章：", data);
-const articleDelListener = (id) => console.log("删除文章：", id);
-
-event
-  .on("article:add", articleAddListener)
-  .on("article:delete", articleDelListener)
-  .off("article:add", articleAddListener)
-  .off("article:delete", articleDelListener);
-```
-
-### 4. 注销所有事件监听器 - removeAllListeners
-#### 作用
-注销指定事件下的**所有**监听器，或注销所有事件的所有监听器（不传参数时）。
-#### 传参格式
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| eventName | String | 否 | 事件名称（不传则注销所有事件的监听器） |
-#### 使用示例
-```javascript
-// 注册多个监听器
-event
-  .on("order:created", (data) => console.log("监听器1：", data))
-  .on("order:created", (data) => console.log("监听器2：", data))
-  .on("user:login", (data) => console.log("登录监听器：", data));
-
-// 注销order:created事件的所有监听器
-event.removeAllListeners("order:created");
-// 触发该事件（无监听器执行）
-event.emit("order:created", { id: "ORD001" });
-
-// 注销所有事件的所有监听器（全局清空）
-event.removeAllListeners();
-// 触发任何事件都无监听器执行
-event.emit("user:login", { userId: 1001 });
-```
-
-## 高级使用场景
-### 场景1：一次性事件监听（扩展）
-原生 `EventEmitter` 支持 `once` 方法（注册仅执行一次的监听器），`Event` 类继承该能力，可直接使用：
-```javascript
-// 注册仅执行一次的监听器
-event.once("config:update", (config) => {
-  console.log("配置更新（仅执行一次）：", config);
-});
-
-// 第一次触发（监听器执行）
-event.emit("config:update", { theme: "dark" });
-// 第二次触发（监听器已自动注销，不执行）
-event.emit("config:update", { theme: "light" });
-```
-
-### 场景2：业务模块解耦示例
-```javascript
-// 模块A：用户模块
-import { event } from "chanjs";
-
-class UserModule {
-  async login(username, password) {
-    // 登录逻辑
-    const user = { id: 1001, username };
-    // 触发登录事件，无需关心其他模块逻辑
-    event.emit("user:login", user);
-    return user;
-  }
-}
-
-// 模块B：日志模块
-import { event } from "chanjs";
-
-class LogModule {
-  constructor() {
-    // 监听登录事件，记录日志
-    event.on("user:login", (user) => {
-      console.log(`[LOG] 用户${user.username}(${user.id})于${new Date()}登录`);
-    });
-  }
-}
-
-// 模块C：消息模块
-import { event } from "chanjs";
-
-class MessageModule {
-  constructor() {
-    // 监听登录事件，推送消息
-    event.on("user:login", (user) => {
-      console.log(`[MSG] 向用户${user.id}推送登录成功消息`);
-    });
-  }
-}
-
-// 业务入口
-const userModule = new UserModule();
-const logModule = new LogModule();
-const messageModule = new MessageModule();
-
-// 执行登录，自动触发日志和消息模块的逻辑
-await userModule.login("test_user", "123456");
-```
-
-### 场景3：错误事件处理
-```javascript
-// 注册全局错误事件监听器
-event.on("error", (err) => {
-  console.error("全局事件错误：", err);
-  // 业务逻辑：错误上报、告警等
-});
-
-// 触发错误事件（建议使用Error对象传递错误信息）
-event.emit("error", new Error("订单创建失败：库存不足"));
-```
-
-## 注意事项
-1. 注销监听器时，`off` 方法传入的 `listener` 必须与 `on` 注册时的函数**引用一致**，匿名函数无法被注销；
-2. 事件名建议使用 `模块:动作` 的命名规范（如 `user:login`、`order:created`），避免全局命名冲突；
-3. 若监听器函数执行过程中抛出异常，不会阻断其他监听器执行，但需自行捕获异常避免程序崩溃；
-4. 单例 `event` 适用于全局通信，若需隔离事件作用域，可创建多个 `Event` 实例（`new Event()`）。
-
-## 总结
-1. `Event` 类核心提供 `on`（注册）、`emit`（触发）、`off`（注销）、`removeAllListeners`（清空）四个方法，覆盖事件通信全流程；
-2. 基于 Node.js `EventEmitter` 实现，兼容原生方法（如 `once`），接口简洁易上手；
-3. 适用于业务模块解耦场景，通过事件发布/订阅模式减少模块间直接依赖，提升代码可维护性。

package/global/env.js

@@ -1,11 +0,0 @@
-import dotenv from "dotenv";
-import path from "path";
-import { Paths } from "../config/paths.js";
-
-/**
- * 环境变量配置加载
- * 从.env文件加载环境变量到process.env
- */
-
-const envFile = process.env.ENV_FILE || ".env.prd";
-dotenv.config({ path: path.join(Paths.rootPath, envFile) });

package/global/import.js

@@ -1,39 +0,0 @@
-import fs from "fs/promises";
-import { pathToFileURL } from "url";
-import { createRequire } from "module";
-
-/**
- * 动态导入文件
- * @param {string} filepath - 文件路径
- * @returns {Promise<Module|null>} 模块对象，失败返回null
- */
-const importFile = async (filepath) => {
-  if (!filepath || typeof filepath !== "string") {
-    console.error("错误: 文件路径必须是有效的字符串");
-    return null;
-  }
-
-  try {
-    await fs.access(filepath);
-    const fileUrl = pathToFileURL(filepath).href;
-    const module = await import(fileUrl);
-    return module.default || module;
-  } catch (error) {
-    if (error.code === "ENOENT") {
-      console.error(`文件不存在: ${filepath}`);
-    } else if (error.code === "EACCES") {
-      console.error(`没有权限访问文件: ${filepath}`);
-    } else {
-      console.error(`导入文件时出错 [${filepath}]:`, error.message);
-    }
-    return null;
-  }
-};
-
-/**
- * CommonJS风格的require函数
- * 用于在ES模块中加载CommonJS模块
- */
-export const importjs = createRequire(import.meta.url);
-
-export { importFile };

package/global/index.js

@@ -1,8 +0,0 @@
-/**
- * 全局模块入口
- * 导入所有全局配置和功能
- */
-
-
-import "./import.js";
-import "./env.js";