mm_mongodb 1.4.7 → 1.4.9

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) [2024] [邱文武]
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -2,6 +2,13 @@
 
 MongoDB数据库操作模块，提供了简洁易用的API、缓存功能以及**完整的Redis兼容接口**。
 
+## 项目信息
+
+- **当前版本**: 1.4.9
+- **更新日期**: 2024-12-23
+- **Gitee地址**: [https://gitee.com/qiuwenwu91/mm_mongodb](https://gitee.com/qiuwenwu91/mm_mongodb)
+- **Node.js 版本要求**: >= 14.0.0（推荐 16.0.0 及以上）
+
 ## 功能特点
 
 - ✅ 支持MongoDB连接池管理
@@ -13,7 +20,7 @@ MongoDB数据库操作模块，提供了简洁易用的API、缓存功能以及*
 - ✅ 环境变量配置支持
 - ✅ 完善的错误处理和重试机制
 - ✅ 查询注入防护
-- ✅ 事件系统：支持监听关键操作的事件
+- ✅ 事件系统：支持监听关键操作的事件，包括操作前、操作后和错误事件
 
 ## 安装
 
@@ -140,6 +147,84 @@ await db.createIndex('users', { name: 1 }, { unique: true });
 await db.createTTLIndex('logs', { createdAt: 1 }, 3600); // 3600秒后过期
 ```
 
+## 事件系统
+
+mm_mongodb提供了完整的事件系统，允许您监听各种数据库操作的前后事件，便于进行日志记录、性能监控、数据校验等操作。
+
+### 支持的事件
+
+| 事件名称 | 触发时机 | 事件参数 |
+|--------|--------|--------|
+| `set_before` | 在执行set操作前 | `{ table, key, value }` |
+| `set_after` | 在执行set操作后 | `{ table, key, value, result }` |
+| `set_error` | 在set操作出错时 | `{ table, key, value, error }` |
+| `del_before` | 在执行del操作前 | `{ table, key }` |
+| `del_after` | 在执行del操作后 | `{ table, key, result }` |
+| `del_error` | 在del操作出错时 | `{ table, key, error }` |
+| `add_before` | 在执行add操作前 | `{ table, key, value }` |
+| `add_after` | 在执行add操作后 | `{ table, key, value, result, exists }` |
+| `add_error` | 在add操作出错时 | `{ table, key, value, error }` |
+
+### 事件参数说明
+
+- `table`: 操作的表名
+- `key`: 操作的键名
+- `value`: 操作的值
+- `result`: 操作的结果
+- `error`: 错误信息（仅在错误事件中）
+- `exists`: 键是否已存在（仅在add_after事件中）
+
+### 使用示例
+
+```javascript
+const { MongoDB } = require('mm_mongodb');
+const db = new MongoDB();
+
+// 连接数据库
+await db.open();
+
+// 监听set操作前事件
+db.on('set_before', (data) => {
+    console.log(`准备设置缓存: ${data.key} = ${JSON.stringify(data.value)}`);
+    // 可以在这里进行数据校验、权限检查等
+});
+
+// 监听set操作后事件
+db.on('set_after', (data) => {
+    console.log(`缓存设置成功: ${data.key}, 结果:`, data.result);
+    // 可以在这里记录日志、触发其他操作等
+});
+
+// 监听add操作后事件，特别注意exists标记
+db.on('add_after', (data) => {
+    if (data.exists) {
+        console.log(`键 ${data.key} 已存在，未添加新值`);
+    } else {
+        console.log(`成功添加新键: ${data.key}`);
+    }
+});
+
+// 监听错误事件
+db.on('set_error', (data) => {
+    console.error(`设置缓存失败: ${data.key}, 错误:`, data.error);
+});
+
+// 执行操作，触发事件
+await db.set('test_key', 'test_value');
+
+// 测试add方法的exists标记
+await db.add('test_key', 'another_value'); // 键已存在，exists将为true
+```
+
+### 应用场景
+
+1. **数据校验和验证**：在操作前事件中验证数据的有效性
+2. **访问控制和权限管理**：检查是否有权限执行特定操作
+3. **性能监控**：记录操作执行时间，监控系统性能
+4. **审计日志**：记录所有关键操作的详细信息
+5. **缓存一致性维护**：在数据变更时更新相关缓存
+6. **业务规则执行**：在特定操作前后执行业务逻辑
+
 ## Redis兼容API使用指南
 
 mm_mongodb提供了**完整的Redis兼容API**，使您可以使用熟悉的Redis命令与MongoDB进行交互。这对于从Redis迁移到MongoDB或在两者间切换使用非常有用。
@@ -499,6 +584,29 @@ new MongoDB(scope = 'default', dir = '', config = {})
 
 邱文武 - [qww.elins.cn](http://qww.elins.cn)
 
-## 许可证
+## 贡献指南
+
+欢迎参与mm_mongodb项目的开发和改进！以下是贡献代码的基本步骤：
+
+1. **Fork 仓库**：在Gitee上Fork项目到您的账户
+2. **克隆仓库**：`git clone https://gitee.com/您的用户名/mm_mongodb.git`
+3. **创建分支**：`git checkout -b feature/your-feature-name`
+4. **提交更改**：`git commit -m "feat: 添加新功能描述"`
+5. **推送分支**：`git push origin feature/your-feature-name`
+6. **创建PR**：在Gitee上提交Pull Request
+
+## 问题反馈
+
+如果您在使用过程中遇到任何问题或有改进建议，请通过以下方式反馈：
+
+- **Gitee Issues**：[https://gitee.com/qiuwenwu91/mm_mongodb/issues](https://gitee.com/qiuwenwu91/mm_mongodb/issues)
+- **NPM 链接**：[https://www.npmjs.com/package/mm_mongodb](https://www.npmjs.com/package/mm_mongodb)
+
+## 鸣谢
+
+感谢所有为mm_mongodb项目做出贡献的开发者和用户！
+
+## 相关链接
 
-MIT
+- **MongoDB 官方文档**：[https://docs.mongodb.com/](https://docs.mongodb.com/)
+- **Node.js MongoDB 驱动**：[https://www.npmjs.com/package/mongodb](https://www.npmjs.com/package/mongodb)