mm_mongodb 1.5.1 → 1.5.3

package/README.md

@@ -1,612 +1,353 @@
-# mm_mongodb
-
-MongoDB数据库操作模块，提供了简洁易用的API、缓存功能以及**完整的Redis兼容接口**。
-
-## 项目信息
-
-- **当前版本**: 1.5.0
-- **更新日期**: 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连接池管理
-- ✅ 自动连接和重连机制
-- ✅ 事务支持
-- ✅ 索引管理
-- ✅ 缓存功能
-- ✅ **完整的Redis兼容API**：支持Redis风格的键值操作、列表、集合、有序集合、哈希等数据类型
-- ✅ 环境变量配置支持
-- ✅ 完善的错误处理和重试机制
-- ✅ 查询注入防护
-- ✅ 事件系统：支持监听关键操作的事件，包括操作前、操作后和错误事件
-
-## 安装
-
-```bash
-npm install mm_mongodb
-```
-
-## 配置
-
-### 基本配置
-
-在项目根目录创建 `config.tpl.json` 文件，配置如下：
-
-```json
-{
-    "mongodb": {
-        "url": "mongodb://username:password@host:port/database",
-        "poolSize": 20,
-        "minPoolSize": 5,
-        "maxPoolSize": 100,
-        "waitQueueTimeoutMS": 10000,
-        "connectTimeoutMS": 10000,
-        "socketTimeoutMS": 45000,
-        "authSource": "admin",
-        "authMechanism": "DEFAULT"
-    }
-}
-```
-
-### 环境变量配置
-
-支持通过环境变量配置MongoDB连接信息，优先级高于配置文件：
-
-- `MONGO_URL`：MongoDB连接字符串
-- `MONGO_HOST`：MongoDB主机地址
-- `MONGO_PORT`：MongoDB端口
-- `MONGO_USERNAME`：MongoDB用户名
-- `MONGO_PASSWORD`：MongoDB密码
-- `MONGO_DATABASE`：MongoDB数据库名
-- `MONGO_AUTH_SOURCE`：认证源数据库
-- `MONGO_AUTH_MECHANISM`：认证机制
-
-## 使用示例
-
-### 基本使用
-
-```javascript
-const { MongoDB } = require('mm_mongodb');
-
-// 创建MongoDB实例
-const db = new MongoDB();
-
-// 连接数据库
-await db.open();
-
-// 创建表
-await db.createTable('users');
-
-// 插入数据
-await db.insert('users', { name: '张三', age: 25 });
-
-// 查询数据
-const result = await db.get('users', { name: '张三' });
-
-// 更新数据
-await db.set('users', { name: '张三' }, { age: 26 });
-
-// 删除数据
-await db.del('users', { name: '张三' });
-
-// 关闭连接
-await db.close();
-```
-
-### 使用连接池
-
-```javascript
-const { mongodb_admin } = require('mm_mongodb');
-
-// 获取连接池实例
-const db = mongodb_admin('default');
-
-// 使用连接池
-await db.open();
-const data = await db.get('users', {});
-```
-
-### 使用事务
-
-```javascript
-const { MongoDB } = require('mm_mongodb');
-const db = new MongoDB();
-
-await db.open();
-
-// 开始事务
-const session = await db.startTransaction();
-
-try {
-    // 在事务中执行操作
-    await db.insert('users', { name: '李四', age: 30 }, { session });
-    await db.insert('orders', { userId: '李四', amount: 100 }, { session });
-    
-    // 提交事务
-    await db.commitTransaction(session);
-    $.log.debug('事务提交成功');
-} catch (error) {
-    // 回滚事务
-    await db.rollbackTransaction(session);
-    $.log.error('事务回滚:', error);
-}
-```
-
-### 创建索引
-
-```javascript
-const db = new MongoDB();
-await db.open();
-
-// 创建普通索引
-await db.createIndex('users', { name: 1 }, { unique: true });
-
-// 创建TTL索引（数据过期自动删除）
-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) => {
-    $.log.debug(`准备设置缓存: ${data.key} = ${JSON.stringify(data.value)}`);
-    // 可以在这里进行数据校验、权限检查等
-});
-
-// 监听set操作后事件
-db.on('set_after', (data) => {
-    $.log.debug(`缓存设置成功: ${data.key}, 结果:`, data.result);
-    // 可以在这里记录日志、触发其他操作等
-});
-
-// 监听add操作后事件，特别注意exists标记
-db.on('add_after', (data) => {
-    if (data.exists) {
-        $.log.debug(`键 ${data.key} 已存在，未添加新值`);
-    } else {
-        $.log.debug(`成功添加新键: ${data.key}`);
-    }
-});
-
-// 监听错误事件
-db.on('set_error', (data) => {
-    $.log.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或在两者间切换使用非常有用。
-
-### 快速开始
-
-```javascript
-const { mongodb_cache_admin } = require('mm_mongodb');
-
-// 获取Redis兼容的缓存实例
-const cache = mongodb_cache_admin('default');
-
-// 连接数据库（重要：必须先连接）
-await cache.open();
-
-// 基本操作示例
-await cache.set('name', 'Redis Compatible');
-const value = await cache.get('name');
-```
-
-### 核心缓存方法
-
-| 方法名 | 说明 | 示例 |
-|-------|------|------|
-| `set(key, value, seconds)` | 设置键值，支持过期时间 | `await cache.set('name', 'value', 60);` |
-| `get(key)` | 获取键值 | `const value = await cache.get('name');` |
-| `del(key)` | 删除键 | `await cache.del('name');` |
-| `has(key)` / `exists(key)` | 判断键是否存在 | `const exists = await cache.has('name');` |
-| `clear(prefix)` | 清空缓存（可选前缀过滤） | `await cache.clear('temp:*');` |
-| `keys(pattern)` | 获取匹配的键名 | `const keys = await cache.keys('user:*');` |
-| `ttl(key)` | 获取剩余过期时间 | `const ttl = await cache.ttl('name');` |
-| `expire(key, seconds)` | 设置过期时间 | `await cache.expire('name', 60);` |
-| `add(key, value)` | 添加缓存（如果存在则不覆盖） | `await cache.add('counter', 1);` |
-| `addInt(key, value)` | 增加整数值 | `await cache.addInt('counter', 10);` |
-| `addFloat(key, value)` | 增加浮点数值 | `await cache.addFloat('score', 0.5);` |
-| `addStr(key, value)` | 追加字符串 | `await cache.addStr('message', ' World');` |
-| `sort(prefix, count, type)` | 排序并获取 | `const sorted = await cache.sort('user:*', 10, 'asc');` |
-
-### 哈希表操作
-
-```javascript
-// 设置哈希字段
-await cache.hset('user:1', 'name', '张三');
-
-// 获取哈希字段
-const name = await cache.hget('user:1', 'name');
-
-// 获取哈希所有字段和值
-const user = await cache.hgetall('user:1');
-
-// 批量设置哈希字段
-await cache.hmset('user:2', { name: '李四', age: 30 });
-
-// 批量获取哈希字段
-const values = await cache.hmget('user:2', 'name', 'age');
-
-// 删除哈希字段
-await cache.hdel('user:1', 'name');
-
-// 批量删除哈希字段
-await cache.hdelMulti('user:2', 'name', 'age');
-
-// 判断哈希字段是否存在
-const exists = await cache.hexists('user:1', 'name');
-
-// 获取哈希字段数量
-const count = await cache.hlen('user:1');
-
-// 获取哈希所有字段名
-const keys = await cache.hkeys('user:1');
-
-// 获取哈希所有字段值
-const vals = await cache.hvals('user:1');
-```
-
-### 列表操作
-
-```javascript
-// 从右侧推入元素
-await cache.rpush('messages', '你好');
-
-// 从左侧推入元素
-await cache.lpush('messages', 'Hello');
-
-// 获取列表长度
-const length = await cache.llen('messages');
-
-// 获取列表指定范围的元素
-const range = await cache.lrange('messages', 0, 1); // 获取前两个元素
-
-// 获取列表指定索引的元素
-const message = await cache.lindex('messages', 0);
-
-// 从左侧弹出元素
-const firstMessage = await cache.lpop('messages');
-
-// 从右侧弹出元素
-const lastMessage = await cache.rpop('messages');
-
-// 修改列表指定索引的元素
-await cache.lset('messages', 0, 'Updated Message');
-
-// 删除列表中的元素
-await cache.lrem('messages', 2, 'value'); // 删除前2个值为'value'的元素
-
-// 裁剪列表
-await cache.ltrim('messages', 0, 4); // 保留前5个元素
-```
-
-### 集合操作
-
-```javascript
-// 添加集合成员
-await cache.sadd('users:online', 'user1');
-
-// 批量添加集合成员
-await cache.saddMulti('users:online', 'user2', 'user3');
-
-// 获取集合所有成员
-const members = await cache.smembers('users:online');
-
-// 判断成员是否在集合中
-const isOnline = await cache.sismember('users:online', 'user1');
-
-// 获取集合成员数量
-const count = await cache.scard('users:online');
-
-// 移除集合成员
-await cache.srem('users:online', 'user1');
-
-// 批量移除集合成员
-await cache.sremMulti('users:online', 'user2', 'user3');
-
-// 计算两个集合的差集
-const offlineUsers = await cache.sdiff('users:all', 'users:online');
-
-// 计算两个集合的交集
-const activeUsers = await cache.sinter('users:online', 'users:paid');
-
-// 计算两个集合的并集
-const allUsers = await cache.sunion('users:online', 'users:offline');
-```
-
-### 有序集合操作
-
-```javascript
-// 添加有序集合成员
-await cache.zadd('ranking', 'user1', 100);
-
-// 获取有序集合成员数量
-const count = await cache.zcard('ranking');
-
-// 获取有序集合成员分数
-const score = await cache.zscore('ranking', 'user1');
-
-// 按分数范围获取有序集合成员
-const topUsers = await cache.zrangebyscore('ranking', 0, 100);
-
-// 移除有序集合成员
-await cache.zrem('ranking', 'user1');
-```
-
-### 批量操作
-
-```javascript
-// 批量设置键值
-await cache.mset({ 'key1': 'value1', 'key2': 'value2' });
-
-// 批量获取键值
-const values = await cache.mget('key1', 'key2', 'key3');
-
-// 批量删除键
-await cache.del('key1', 'key2', 'key3');
-```
-
-### 数值操作
-
-```javascript
-// 原子递增
-await cache.incr('counter'); // 自增1
-
-// 原子递减
-await cache.decr('counter'); // 自减1
-
-// 增加指定整数
-await cache.addInt('counter', 10); // 增加10
-
-// 减少指定整数
-await cache.addInt('counter', -5); // 减少5
-```
-
-## 事件系统
-
-mm_mongodb的缓存模块实现了事件系统，可以监听各种操作的发生。增删改类方法会触发相应的事件，而查询类方法不触发事件以提高性能。
-
-### 事件命名规范
-
-所有事件严格遵循以下命名格式：
-- 操作前事件：`action_before`
-- 操作后事件：`action_after`
-- 操作错误事件：`action_error`
-
-其中`action`为方法名，例如`set`、`del`、`add`等。
-
-### 事件示例
-
-```javascript
-// 监听事件
-cache.on('set_before', (data) => {
-    $.log.debug('设置缓存前:', data);
-});
-
-cache.on('set_after', (data) => {
-    $.log.debug('设置缓存后:', data);
-});
-
-cache.on('set_error', (data) => {
-    $.log.error('设置缓存错误:', data);
-});
-```
-
-### 支持事件的方法
-
-以下增删改类方法支持事件触发，每种方法都会触发对应的`action_before`、`action_after`和`action_error`事件：
-
-- 原子操作：incr, decr, addInt, addFloat
-- 字符串操作：append, addStr
-- 列表操作：rpush, lpush, lset, lrem, ltrim, lpop, rpop
-- 集合操作：sadd, saddMulti, srem, sremMulti
-- 哈希操作：hset, hmset, hdel, hdelMulti
-- 有序集合操作：zadd, zrem
-- 键操作：set, del, expire, mset, add
-
-### 事件参数
-
-事件回调函数接收的参数通常包含以下信息：
-- 操作涉及的键（key）
-- 操作涉及的值（value）
-- 操作结果（仅在after事件中）
-- 错误信息（仅在error事件中）
-
-具体参数结构取决于触发事件的方法类型。
-
-## 性能优化建议
-
-1. **使用连接池**：优先使用`mongodb_admin`和`mongodb_cache_admin`创建的连接池实例
-2. **合理设置索引**：为常用查询字段创建索引
-3. **查询优化**：避免全表扫描，使用精确查询
-4. **批量操作**：优先使用批量操作方法如`mset`、`mget`等
-5. **过期时间**：为临时数据设置合理的过期时间，避免数据膨胀
-6. **Redis兼容模式**：使用字符串键名可以简化操作，与Redis保持一致的使用体验
-
-## 从Redis迁移指南
-
-从Redis迁移到使用mm_mongodb的Redis兼容API时，只需以下步骤：
-
-1. 安装mm_mongodb：`npm install mm_mongodb`
-2. 修改导入语句：将Redis客户端导入改为`mongodb_cache_admin`
-3. 添加连接初始化：调用`await cache.open()`确保连接已建立
-4. 保持命令调用不变：大多数Redis命令可以直接使用
-
-```javascript
-// Redis客户端示例
-// const redis = require('redis');
-// const client = redis.createClient();
-// await client.connect();
-
-// mm_mongodb替换示例
-const { mongodb_cache_admin } = require('mm_mongodb');
-const cache = mongodb_cache_admin('default');
-await cache.open(); // 确保连接已建立
-
-// 后续命令调用保持不变
-await cache.set('key', 'value');
-const value = await cache.get('key');
-```
-
-## API文档
-
-### MongoDB类
-
-#### 构造函数
-
-```javascript
-new MongoDB(scope = 'default', dir = '', config = {})
-```
-- `scope`：作用域，用于区分不同的连接池
-- `dir`：配置文件路径
-- `config`：配置对象
-
-#### 连接管理
-
-- `open()`：连接数据库
-- `close()`：关闭数据库连接
-- `setUrl(url)`：设置连接URL
-- `setConfig(config)`：设置配置
-
-#### 表操作
-
-- `createTable(tableName)`：创建表
-- `dropTable(tableName)`：删除表
-- `existsTable(tableName)`：检查表是否存在
-
-#### 数据操作
-
-- `insert(tableName, data)`：插入数据
-- `insertBatch(tableName, datas)`：批量插入数据
-- `get(tableName, query, options)`：查询数据
-- `getOne(tableName, query, options)`：查询单条数据
-- `set(tableName, query, data, options)`：修改数据
-- `del(tableName, query, options)`：删除数据
-- `count(tableName, query)`：统计数量
-
-#### 事务支持
-
-- `startTransaction()`：开始事务，返回会话对象
-- `commitTransaction(session)`：提交事务
-- `rollbackTransaction(session)`：回滚事务
-
-#### 索引管理
-
-- `createIndex(tableName, keys, options)`：创建索引
-- `createTTLIndex(tableName, keys, expireAfterSeconds)`：创建TTL索引
-- `getIndexes(tableName)`：获取索引信息
-- `dropIndex(tableName, indexName)`：删除索引
-
-### Redis兼容API
-
-详细的Redis兼容API见上方「Redis兼容API使用指南」章节。支持以下类别的API：
-
-- **核心缓存方法**：set, get, del, has, exists, clear, keys, ttl, expire等
-- **哈希表操作**：hset, hget, hgetall, hmset, hmget, hdel, hdelMulti, hexists, hkeys, hvals, hlen等
-- **列表操作**：rpush, lpush, lrange, lindex, llen, lpop, rpop, lset, lrem, ltrim等
-- **集合操作**：sadd, saddMulti, srem, sremMulti, smembers, scard, sismember, sdiff, sinter, sunion等
-- **有序集合操作**：zadd, zrem, zrangebyscore, zscore, zcard等
-- **批量操作**：mget, mset等
-- **数值操作**：incr, decr, addInt, addFloat等
-
-## 安全注意事项
-
-1. 密码会自动进行URI编码，确保安全传输
-2. 支持查询条件注入防护
-3. 自动加载环境变量中的敏感信息，避免硬编码
-4. 连接错误时会自动重试，提高稳定性
-5. 避免使用未经处理的用户输入作为查询条件
-
-## 兼容性表格
-
-查看详细的方法兼容性对比表格，请参考项目中的 [compatibility_table.md](https://github.com/qwwang/mm_mongodb/blob/main/compatibility_table.md) 文件。
-
-## 依赖
-
-- [mm_logs](https://www.npmjs.com/package/mm_logs)：日志模块
-- [mongodb](https://www.npmjs.com/package/mongodb)：MongoDB官方驱动
-
-## 作者
-
-邱文武 - [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项目做出贡献的开发者和用户！
-
-## 相关链接
-
-- **MongoDB 官方文档**：[https://docs.mongodb.com/](https://docs.mongodb.com/)
-- **Node.js MongoDB 驱动**：[https://www.npmjs.com/package/mongodb](https://www.npmjs.com/package/mongodb)
+# mm_mongodb
+
+A powerful MongoDB database operation module with Redis-compatible API, connection pooling, and event system support.
+
+[![npm version](https://img.shields.io/npm/v/mm_mongodb.svg)](https://www.npmjs.com/package/mm_mongodb)
+[![License](https://img.shields.io/npm/l/mm_mongodb.svg)](https://github.com/qwwang/mm_mongodb/blob/main/LICENSE)
+[![Node.js Version](https://img.shields.io/badge/node.js-%3E%3D14.0.0-brightgreen.svg)](https://nodejs.org/)
+
+## Features
+
+- ✅ **Complete Redis-compatible API** - Use familiar Redis commands with MongoDB
+- ✅ **Connection Pool Management** - Efficient connection pooling with automatic reconnection
+- ✅ **Transaction Support** - Full ACID transactions with session management
+- ✅ **Event System** - Comprehensive event system for monitoring operations
+- ✅ **Index Management** - Easy index creation and management
+- ✅ **TTL Support** - Automatic data expiration with TTL indexes
+- ✅ **Environment Variable Configuration** - Flexible configuration via environment variables
+- ✅ **Query Injection Protection** - Built-in security against NoSQL injection
+- ✅ **Performance Optimized** - Optimized for high-performance database operations
+
+## Installation
+
+```bash
+npm install mm_mongodb
+```
+
+## Quick Start
+
+### Basic Usage
+
+```javascript
+const { MongoDB } = require('mm_mongodb');
+
+// Create MongoDB instance
+const db = new MongoDB();
+
+// Connect to database
+await db.open();
+
+// Create collection
+await db.createTable('users');
+
+// Insert data
+await db.insert('users', { name: 'John', age: 25 });
+
+// Query data
+const result = await db.get('users', { name: 'John' });
+
+// Update data
+await db.set('users', { name: 'John' }, { age: 26 });
+
+// Delete data
+await db.del('users', { name: 'John' });
+
+// Close connection
+await db.close();
+```
+
+### Redis-Compatible API
+
+```javascript
+const { mongodb_cache_admin } = require('mm_mongodb');
+
+// Get Redis-compatible cache instance
+const cache = mongodb_cache_admin('default');
+
+// Connect to database
+await cache.open();
+
+// Use Redis-style commands
+await cache.set('name', 'Redis Compatible');
+const value = await cache.get('name');
+await cache.del('name');
+
+// Hash operations
+await cache.hset('user:1', 'name', 'John');
+const name = await cache.hget('user:1', 'name');
+
+// List operations
+await cache.lpush('messages', 'Hello');
+await cache.rpush('messages', 'World');
+const messages = await cache.lrange('messages', 0, -1);
+
+// Set operations
+await cache.sadd('users:online', 'user1', 'user2');
+const members = await cache.smembers('users:online');
+```
+
+## Configuration
+
+### Environment Variables
+
+Configure MongoDB connection via environment variables:
+
+```bash
+MONGO_URL=mongodb://username:password@host:port/database
+MONGO_HOST=localhost
+MONGO_PORT=27017
+MONGO_USERNAME=username
+MONGO_PASSWORD=password
+MONGO_DATABASE=database
+MONGO_AUTH_SOURCE=admin
+```
+
+### Configuration File
+
+Create `config.tpl.json` in your project root:
+
+```json
+{
+    "mongodb": {
+        "url": "mongodb://username:password@host:port/database",
+        "poolSize": 20,
+        "minPoolSize": 5,
+        "maxPoolSize": 100,
+        "waitQueueTimeoutMS": 10000,
+        "connectTimeoutMS": 10000,
+        "socketTimeoutMS": 45000,
+        "authSource": "admin",
+        "authMechanism": "DEFAULT"
+    }
+}
+```
+
+## API Documentation
+
+### Core MongoDB Class
+
+#### Constructor
+
+```javascript
+new MongoDB(scope = 'default', dir = '', config = {})
+```
+
+#### Connection Management
+
+- `open()` - Connect to database
+- `close()` - Close database connection
+- `setUrl(url)` - Set connection URL
+- `setConfig(config)` - Set configuration
+
+#### Collection Operations
+
+- `createTable(tableName)` - Create collection
+- `dropTable(tableName)` - Drop collection
+- `existsTable(tableName)` - Check if collection exists
+
+#### Data Operations
+
+- `insert(tableName, data)` - Insert document
+- `insertBatch(tableName, datas)` - Batch insert documents
+- `get(tableName, query, options)` - Query documents
+- `getOne(tableName, query, options)` - Query single document
+- `set(tableName, query, data, options)` - Update documents
+- `del(tableName, query, options)` - Delete documents
+- `count(tableName, query)` - Count documents
+
+#### Transaction Support
+
+- `startTransaction()` - Start transaction
+- `commitTransaction(session)` - Commit transaction
+- `rollbackTransaction(session)` - Rollback transaction
+
+#### Index Management
+
+- `createIndex(tableName, keys, options)` - Create index
+- `createTTLIndex(tableName, keys, expireAfterSeconds)` - Create TTL index
+- `getIndexes(tableName)` - Get index information
+- `dropIndex(tableName, indexName)` - Drop index
+
+### Redis-Compatible API
+
+#### Key-Value Operations
+
+- `set(key, value, seconds)` - Set key with optional expiration
+- `get(key)` - Get value by key
+- `del(key)` - Delete key
+- `has(key)` / `exists(key)` - Check if key exists
+- `clear(prefix)` - Clear keys with optional prefix
+- `keys(pattern)` - Get matching keys
+- `ttl(key)` - Get time to live
+- `expire(key, seconds)` - Set expiration time
+- `add(key, value)` - Add key if not exists
+
+#### Hash Operations
+
+- `hset(key, field, value)` - Set hash field
+- `hget(key, field)` - Get hash field
+- `hgetall(key)` - Get all hash fields
+- `hmset(key, object)` - Set multiple hash fields
+- `hmget(key, ...fields)` - Get multiple hash fields
+- `hdel(key, field)` - Delete hash field
+- `hdelMulti(key, ...fields)` - Delete multiple hash fields
+- `hexists(key, field)` - Check if hash field exists
+- `hkeys(key)` - Get all hash field names
+- `hvals(key)` - Get all hash field values
+- `hlen(key)` - Get number of hash fields
+
+#### List Operations
+
+- `lpush(key, value)` - Push to left of list
+- `rpush(key, value)` - Push to right of list
+- `lrange(key, start, stop)` - Get list range
+- `lindex(key, index)` - Get list element by index
+- `llen(key)` - Get list length
+- `lpop(key)` - Pop from left of list
+- `rpop(key)` - Pop from right of list
+- `lset(key, index, value)` - Set list element by index
+- `lrem(key, count, value)` - Remove list elements
+- `ltrim(key, start, stop)` - Trim list
+
+#### Set Operations
+
+- `sadd(key, ...members)` - Add set members
+- `saddMulti(key, ...members)` - Add multiple set members
+- `srem(key, member)` - Remove set member
+- `sremMulti(key, ...members)` - Remove multiple set members
+- `smembers(key)` - Get all set members
+- `scard(key)` - Get set size
+- `sismember(key, member)` - Check if member exists in set
+- `sdiff(key1, key2)` - Get set difference
+- `sinter(key1, key2)` - Get set intersection
+- `sunion(key1, key2)` - Get set union
+
+#### Sorted Set Operations
+
+- `zadd(key, member, score)` - Add sorted set member
+- `zrem(key, member)` - Remove sorted set member
+- `zrangebyscore(key, min, max)` - Get members by score range
+- `zscore(key, member)` - Get member score
+- `zcard(key)` - Get sorted set size
+
+#### Batch Operations
+
+- `mset(object)` - Set multiple keys
+- `mget(...keys)` - Get multiple keys
+- `del(...keys)` - Delete multiple keys
+
+#### Numeric Operations
+
+- `incr(key)` - Increment by 1
+- `decr(key)` - Decrement by 1
+- `addInt(key, value)` - Add integer value
+- `addFloat(key, value)` - Add float value
+- `addStr(key, value)` - Append string
+
+## Event System
+
+mm_mongodb provides a comprehensive event system for monitoring database operations:
+
+```javascript
+const db = new MongoDB();
+await db.open();
+
+// Listen to operation events
+db.on('set_before', (data) => {
+    console.log('Before set operation:', data);
+});
+
+db.on('set_after', (data) => {
+    console.log('After set operation:', data);
+});
+
+db.on('set_error', (data) => {
+    console.error('Set operation error:', data);
+});
+
+// Trigger events
+await db.set('test_key', 'test_value');
+```
+
+### Supported Events
+
+- `{action}_before` - Before operation execution
+- `{action}_after` - After operation completion
+- `{action}_error` - On operation error
+
+Where `{action}` can be: `set`, `del`, `add`, `hset`, `lpush`, `sadd`, `zadd`, etc.
+
+## Performance Optimization
+
+1. **Use Connection Pooling** - Always use `mongodb_admin` or `mongodb_cache_admin` for connection pooling
+2. **Create Appropriate Indexes** - Index frequently queried fields
+3. **Use Batch Operations** - Prefer `mset`, `mget`, `insertBatch` for multiple operations
+4. **Set Expiration Times** - Use TTL indexes for temporary data
+5. **Optimize Queries** - Avoid full collection scans, use precise queries
+
+## Migration from Redis
+
+Migrating from Redis to mm_mongodb is straightforward:
+
+```javascript
+// Redis client (original)
+// const redis = require('redis');
+// const client = redis.createClient();
+// await client.connect();
+
+// mm_mongodb (replacement)
+const { mongodb_cache_admin } = require('mm_mongodb');
+const cache = mongodb_cache_admin('default');
+await cache.open();
+
+// Your Redis commands remain the same
+await cache.set('key', 'value');
+const value = await cache.get('key');
+```
+
+## Security Considerations
+
+- Passwords are automatically URI-encoded for secure transmission
+- Built-in query injection protection
+- Environment variables for sensitive configuration
+- Automatic connection retry for improved stability
+- Avoid using raw user input in queries
+
+## Dependencies
+
+- [mm_logs](https://www.npmjs.com/package/mm_logs) - Logging module
+- [mongodb](https://www.npmjs.com/package/mongodb) - Official MongoDB driver
+
+## Compatibility
+
+- **Node.js**: >= 14.0.0 (Recommended: 16.0.0+)
+- **MongoDB**: 4.0+
+
+## Contributing
+
+We welcome contributions! Please follow these steps:
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/your-feature`
+3. Commit your changes: `git commit -m "feat: add your feature"`
+4. Push to the branch: `git push origin feature/your-feature`
+5. Submit a pull request
+
+## Issues and Support
+
+If you encounter any issues or have questions:
+
+- **GitHub Issues**: [https://github.com/qwwang/mm_mongodb/issues](https://github.com/qwwang/mm_mongodb/issues)
+- **NPM Package**: [https://www.npmjs.com/package/mm_mongodb](https://www.npmjs.com/package/mm_mongodb)
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Author
+
+Qiu Wenwu - [qww.elins.cn](http://qww.elins.cn)
+
+## Acknowledgments
+
+Thanks to all contributors and users who have helped improve mm_mongodb!