monsqlize 1.0.2 → 1.0.5

package/CHANGELOG.md

@@ -1,7 +1,7 @@
 # 变更日志 (CHANGELOG)
 
 > **说明**: 版本摘要，详细需求见 [STATUS.md](STATUS.md)  
-> **最后更新**: 2025-12-29
+> **最后更新**: 2025-12-31
 
 ---
 
@@ -9,11 +9,131 @@
 
 | 版本 | 日期 | 变更摘要 | 详细 |
 |------|------|---------|------|
+| [v1.0.3](STATUS.md#v103) | 2025-12-31 | 新增 Model 层（Schema 验证、自定义方法、生命周期钩子、自动时间戳） | [查看](STATUS.md#v103) |
+| [v1.0.2](STATUS.md#v102) | 2025-12-30 | 新增批量操作方法（deleteBatch/updateBatch） | [查看](STATUS.md#v102) |
 | [v1.0.1](STATUS.md#v101) | 2025-12-29 | 稳定版本，生产就绪 | [查看](STATUS.md#v101) |
 | [v1.0.0](STATUS.md#v100) | 2025-12-03 | 正式发布，生产就绪，已发布到 npm | [查看](STATUS.md#v100) |
 
 ---
 
+## 🆕 v1.0.3 变更详情（2025-12-31）
+
+### 新增功能 ✨
+
+**Model 层** - ORM 式的数据模型功能
+- ✅ **Schema 验证** - 集成 schema-dsl，自动验证数据格式
+- ✅ **自定义方法** - instance 方法注入到文档，static 方法挂载到 Model
+- ✅ **生命周期钩子** - before/after 钩子支持（find/insert/update/delete）
+- ✅ **索引自动创建** - 初始化时自动创建索引
+- ✅ **枚举配置** - 可在 schema 中引用的枚举定义
+- ✅ **自动时间戳** - 自动管理 createdAt/updatedAt，支持自定义字段名
+
+### 核心 API 🔧
+
+```javascript
+// 定义 Model
+Model.define('users', {
+    schema: (dsl) => dsl({ username: 'string!', email: 'email!' }),
+    methods: (model) => ({
+        instance: { checkPassword(pwd) { return this.password === pwd; } },
+        static: { async findByUsername(name) { return await model.findOne({ username: name }); } }
+    }),
+    hooks: (model) => ({
+        insert: { before: async (ctx, docs) => ({ ...docs, createdAt: new Date() }) }
+    }),
+    indexes: [{ key: { username: 1 }, unique: true }]
+});
+
+// 使用 Model
+const User = msq.model('users');
+const user = await User.findByUsername('admin');
+if (user.checkPassword('secret')) console.log('登录成功');
+```
+
+### 测试覆盖 ✅
+
+- 新增 45 个单元测试
+  - Model 基础功能：16个（100%通过）
+  - ModelInstance：23个
+  - Hooks：6个
+- 测试覆盖率：~90%
+
+### 文档完善 📖
+
+- 新增 `docs/model.md` - 完整 API 文档（495行，精简版）
+- 新增 `docs/model-methods-design.md` - 设计文档（295行）
+- 新增 `examples/model/basic.js` - 基础使用示例
+- 新增 `examples/model/advanced.js` - 高级功能示例
+- 新增 TypeScript 类型定义（+300行）
+- 更新 `README.md`、`docs/INDEX.md`
+
+### 设计亮点 💡
+
+- ✅ **业界标准** - 参考 Mongoose、Sequelize，降低学习成本
+- ✅ **Schema 缓存** - 编译一次，重复使用，性能优化
+- ✅ **方法注入** - 自动注入到查询结果，使用自然
+- ✅ **TypeScript 支持** - 完整的泛型类型定义
+- ✅ **灵活配置** - 所有选项都可选，渐进式采用
+
+### 使用场景 🎯
+
+- ✅ 需要数据验证的场景
+- ✅ 需要扩展文档方法的场景
+- ✅ 需要生命周期控制的场景
+- ✅ 需要类 ORM 体验的场景
+
+---
+
+## 🆕 v1.0.2 变更详情（2025-12-30）
+
+### 新增功能 ✨
+
+**批量操作方法** - 支持大数据量场景
+- ✅ **deleteBatch** - 批量删除方法
+  - 流式查询，恒定内存占用（12KB）
+  - 支持进度监控（实时百分比）
+  - 4种错误处理策略（stop/skip/collect/retry）
+  - 自动重试机制
+  - 性能：36,385 条/秒（100万条数据实测）
+  
+- ✅ **updateBatch** - 批量更新方法
+  - 流式查询，恒定内存占用（12KB）
+  - 支持进度监控（实时百分比）
+  - 支持所有 MongoDB 更新操作符
+  - 4种错误处理策略 + 自动重试
+  - 性能：35,365 条/秒（100万条数据实测）
+
+### 性能数据 📊
+
+```
+批量操作性能（100万条数据测试）:
+- insertBatch: 49,493 条/秒
+- deleteBatch: 36,385 条/秒
+- updateBatch: 35,365 条/秒
+- 内存占用: 恒定 12KB
+```
+
+### 测试覆盖 ✅
+
+- 新增 31 个单元测试（deleteBatch: 14个，updateBatch: 17个）
+- 性能测试通过（100万条数据）
+- 测试覆盖率 > 90%
+
+### 文档完善 📖
+
+- 新增 `docs/deleteBatch.md` - 完整 API 文档（650行）
+- 新增 `docs/updateBatch.md` - 完整 API 文档（600行）
+- 新增 `examples/batch-operations.examples.js` - 8个真实业务场景
+- 更新 `README.md` 和 `docs/INDEX.md`
+
+### 技术亮点 💡
+
+- ✅ **完全复用 find 方法** - 0行重复代码，自动获得流式查询、慢查询日志等功能
+- ✅ **架构最简** - 单一流式查询实现，数据一致性有保证
+- ✅ **内存优化** - 流式查询，无论处理多少数据，内存占用恒定 12KB
+- ✅ **错误处理完善** - 4种策略 + 自动重试，适应不同业务场景
+
+---
 
 ## 🆕 v1.0.1 变更详情（2025-12-29）
 
@@ -45,7 +165,7 @@
 
 | 版本系列 | 版本数 | 主要改进方向 |
 |---------|-------|------------|
-| v1.0.x | 2 | 稳定运行、生产就绪 |
+| v1.0.x | 3 | 稳定运行、生产就绪、批量操作优化 |
 
 ---
 

package/README.md

@@ -39,6 +39,7 @@ npm install monsqlize
   - [7. 📊 深度分页](#7--深度分页---支持千万级数据)
   - [8. 🛠️ 运维监控](#8-️-运维监控开箱即用)
   - [9. 🔐 SSH隧道](#9--ssh隧道---安全连接内网数据库v13)
+  - [10. 🎯 Model 层](#10--model-层---像-orm-一样使用v103)
 - [📊 性能测试报告](#-性能测试报告)
 - [🎨 完整功能清单](#-完整功能清单)
 - [🆚 与 MongoDB 原生驱动对比](#-与-mongodb-原生驱动对比)
@@ -549,6 +550,111 @@ await db.close();    // 自动关闭SSH隧道
 
 ---
 
+### 10. 🎯 Model 层 - 像 ORM 一样使用（v1.0.3+）
+
+monSQLize 提供了一个轻量级的 Model 层，让你可以像使用 ORM 一样定义数据模型，同时保持 MongoDB 的灵活性。
+
+```javascript
+const { Model } = require('monsqlize');
+
+// 1. 定义 Model（集成 schema-dsl 验证）
+Model.define('users', {
+    enums: {
+        role: 'admin|user|guest'
+    },
+    schema: function(dsl) {
+        return dsl({
+            username: 'string:3-32!',
+            email: 'email!',
+            role: this.enums.role.default('user'),
+            age: 'number:1-150'
+        });
+    },
+    options: {
+        timestamps: true,  // 🆕 v1.0.3: 自动管理 createdAt/updatedAt
+        softDelete: true   // 🆕 v1.0.3: 软删除（标记删除，支持恢复）
+    },
+    methods: (model) => ({
+        // 实例方法 - 注入到查询返回的文档对象
+        instance: {
+            isAdmin() {
+                return this.role === 'admin';
+            }
+        },
+        // 静态方法 - 挂载到 Model 实例
+        static: {
+            async findByEmail(email) {
+                return await model.findOne({ email });
+            }
+        }
+    }),
+    hooks: (model) => ({
+        // 生命周期钩子
+        insert: {
+            before: (ctx, docs) => {
+                // 自动添加时间戳
+                return { ...docs, createdAt: new Date() };
+            }
+        }
+    }),
+    indexes: [
+        { key: { username: 1 }, unique: true },
+        { key: { email: 1 }, unique: true }
+    ]
+});
+
+// 2. 使用 Model
+const db = new MonSQLize({ /* ... */ });
+await db.connect();
+
+const User = db.model('users');
+
+// 自动 Schema 验证
+const user = await User.insertOne({
+    username: 'john',
+    email: 'john@example.com',
+    age: 25
+}); // ✅ 验证通过
+
+// 使用实例方法
+const admin = await User.findOne({ username: 'admin' });
+console.log(admin.isAdmin()); // true
+
+// 使用静态方法
+const user = await User.findByEmail('john@example.com');
+
+// 软删除（标记删除，可恢复）
+await User.deleteOne({ _id: user._id });
+
+// 查询（自动过滤已删除）
+const users = await User.find({}); // 不包含已删除用户
+
+// 查询包含已删除
+const allUsers = await User.findWithDeleted({});
+
+// 恢复已删除
+await User.restore({ _id: user._id });
+```
+
+**特性**：
+- ✅ Schema 验证（集成 schema-dsl）
+- ✅ 自定义方法（instance + static）
+- ✅ 生命周期钩子（before/after）
+- ✅ 索引自动创建
+- ✅ 自动时间戳（v1.0.3+）
+- ✅ 软删除（v1.0.3+）
+- ✅ 乐观锁版本控制（v1.0.3+）
+- ✅ TypeScript 类型支持
+
+**注意**：需要安装 `schema-dsl` 依赖：
+```bash
+npm install schema-dsl
+```
+
+[📖 Model 层详细文档](./docs/model.md)
+
+---
+
 ## 📊 性能测试报告
 
 ### 测试环境
@@ -630,7 +736,9 @@ await db.close();    // 自动关闭SSH隧道
 - findAndCount
 
 ✅ **性能优化**
-- 批量插入优化
+- insertBatch - 批量插入优化
+- deleteBatch - 批量删除（流式+进度监控）
+- updateBatch - 批量更新（流式+进度监控）
 - 只读事务优化
 - Count 队列控制
 - 连接池管理
@@ -803,8 +911,11 @@ const coldData = await nativeClient.db('mydb').collection('logs').find({});
 **CRUD 操作**:
 - [find](./docs/find.md) | [findOne](./docs/findOne.md) | [findPage](./docs/findPage.md)
 - [insertOne](./docs/insert-one.md) | [insertMany](./docs/insert-many.md) | [insertBatch](./docs/insertBatch.md)
-- [updateOne](./docs/update-one.md) | [updateMany](./docs/update-many.md) | [replaceOne](./docs/replace-one.md)
-- [deleteOne](./docs/delete-one.md) | [deleteMany](./docs/delete-many.md)
+- [updateOne](./docs/update-one.md) | [updateMany](./docs/update-many.md) | [updateBatch](./docs/updateBatch.md) | [replaceOne](./docs/replace-one.md)
+- [deleteOne](./docs/delete-one.md) | [deleteMany](./docs/delete-many.md) | [deleteBatch](./docs/deleteBatch.md)
+
+**Model 层**:
+- [Model API 文档](./docs/model.md) - Schema 验证、自定义方法、生命周期钩子
 
 **便利方法**:
 - [findOneById](./docs/find-one-by-id.md) | [findByIds](./docs/find-by-ids.md)
@@ -842,6 +953,7 @@ const coldData = await nativeClient.db('mydb').collection('logs').find({});
 - ✅ 事务优化
 - ✅ 便利方法
 - ✅ 分布式支持
+- ✅ Model 层（v1.0.3）- Schema 验证、自定义方法、生命周期钩子
 
 ### 🚧 v1.5 (计划中)
 
@@ -849,12 +961,13 @@ const coldData = await nativeClient.db('mydb').collection('logs').find({});
 - 🔄 自动索引建议
 - 🔄 数据迁移工具
 - 🔄 GraphQL 支持
+- 🔄 Model 关系（relations）完善
 
 ### 🔮 v2.0 (未来)
 
 - 🔮 统一 API 支持 MySQL
 - 🔮 统一 API 支持 PostgreSQL
-- 🔮 ORM 功能
+- 🔮 完整 ORM 功能
 - 🔮 数据同步中间件
 
 ---