monsqlize 1.0.2 → 1.0.5

package/lib/mongodb/index.js

@@ -38,6 +38,7 @@ const {
     createInsertBatchOps,
     createUpdateOneOps,
     createUpdateManyOps,
+    createUpdateBatchOps,  // 🆕 批量更新
     createReplaceOneOps,
     createUpsertOneOps,  // upsertOne 便利方法
     createIncrementOneOps,  // 新增：incrementOne 便利方法
@@ -45,6 +46,7 @@ const {
     createFindOneAndReplaceOps,
     createDeleteOneOps,
     createDeleteManyOps,
+    createDeleteBatchOps,  // 🆕 批量删除
     createFindOneAndDeleteOps
 } = require('./writes');
 
@@ -222,6 +224,7 @@ module.exports = class {
         const moduleContext = {
             collection,
             db,
+            collectionName: collection.collectionName,  // 🔴 修复：添加 collectionName
             defaults: this.defaults,
             run,
             instanceId,
@@ -289,6 +292,20 @@ module.exports = class {
         });
         Object.assign(accessor, insertBatchOps);
 
+        // 🔑 关键：deleteBatch 依赖 find（流式查询），所以在 accessor 创建后添加
+        const deleteBatchOps = createDeleteBatchOps({
+            ...moduleContext,
+            find: accessor.find  // 传入 find 方法（用于流式查询）
+        });
+        Object.assign(accessor, deleteBatchOps);
+
+        // 🔑 关键：updateBatch 依赖 find（流式查询），所以在 accessor 创建后添加
+        const updateBatchOps = createUpdateBatchOps({
+            ...moduleContext,
+            find: accessor.find  // 传入 find 方法（用于流式查询）
+        });
+        Object.assign(accessor, updateBatchOps);
+
         // 🔑 关键：现在 accessor 已完整创建（包含 findPage），再创建依赖它的 bookmarkOps
         moduleContext.getCollectionMethods = () => accessor;
         const bookmarkOps = createBookmarkOps(moduleContext);

package/lib/mongodb/writes/common/batch-retry.js

@@ -0,0 +1,64 @@
+/**
+ * 批量操作重试机制
+ * 供 insertBatch、deleteBatch、updateBatch 复用
+ */
+
+/**
+ * 执行批次操作（带重试）
+ * @param {Function} fn - 要执行的批次操作函数
+ * @param {Object} retryContext - 重试上下文
+ * @param {string} retryContext.onError - 错误策略: 'stop'/'skip'/'collect'/'retry'
+ * @param {number} retryContext.retryAttempts - 最大重试次数
+ * @param {number} retryContext.retryDelay - 重试延迟（毫秒）
+ * @param {Function} retryContext.onRetry - 重试回调
+ * @param {number} retryContext.batchIndex - 当前批次索引
+ * @returns {Promise<Object>} { success, result, attempts }
+ */
+async function executeBatchWithRetry(fn, retryContext) {
+    const {
+        onError = 'stop',
+        retryAttempts = 3,
+        retryDelay = 1000,
+        onRetry,
+        batchIndex = 0
+    } = retryContext;
+
+    let lastError = null;
+    let attempts = 0;
+    const maxAttempts = onError === 'retry' ? retryAttempts + 1 : 1;
+
+    while (attempts < maxAttempts) {
+        try {
+            const result = await fn();
+            return { success: true, result, attempts };
+        } catch (error) {
+            lastError = error;
+            attempts++;
+
+            // 还有重试机会
+            if (attempts < maxAttempts) {
+                // 触发重试回调
+                if (onRetry) {
+                    onRetry({
+                        batchIndex,
+                        attempt: attempts,
+                        maxAttempts: retryAttempts,
+                        error,
+                        nextRetryDelay: retryDelay
+                    });
+                }
+
+                // 延迟后重试
+                if (retryDelay > 0) {
+                    await new Promise(resolve => setTimeout(resolve, retryDelay));
+                }
+            }
+        }
+    }
+
+    // 所有重试都失败
+    throw lastError;
+}
+
+module.exports = { executeBatchWithRetry };
+

package/lib/mongodb/writes/delete-batch.js

@@ -0,0 +1,322 @@
+/**
+ * deleteBatch 操作实现
+ * 分批删除大量匹配的文档（基于流式查询）
+ */
+
+const { createError, ErrorCodes } = require('../../errors');
+const CacheFactory = require('../../cache');
+const { isInTransaction, getTransactionFromSession } = require('../common/transaction-aware');
+const { convertObjectIdStrings } = require('../../utils/objectid-converter');
+const { executeBatchWithRetry } = require('./common/batch-retry');
+
+/**
+ * 创建 deleteBatch 操作
+ * @param {Object} context - 模块上下文
+ * @returns {Object} 包含 deleteBatch 方法的对象
+ */
+function createDeleteBatchOps(context) {
+    const { db, cache, logger, defaults, collection, effectiveDbName: databaseName, instanceId } = context;
+
+    const collectionName = collection.collectionName;
+    const nativeCollection = collection;
+
+    /**
+     * 分批删除大量匹配的文档
+     * @param {Object} filter - 筛选条件（必需）
+     * @param {Object} [options] - 操作选项
+     * @param {number} [options.batchSize=1000] - 每批删除的文档数量
+     * @param {boolean} [options.estimateProgress=true] - 是否预先 count 获取总数
+     * @param {Function} [options.onProgress] - 进度回调函数 (progress) => {}
+     * @param {string} [options.onError='stop'] - 错误处理策略: 'stop'/'skip'/'collect'/'retry'
+     * @param {number} [options.retryAttempts=3] - 失败批次最大重试次数
+     * @param {number} [options.retryDelay=1000] - 重试延迟时间（毫秒）
+     * @param {Function} [options.onRetry] - 重试回调函数 (retryInfo) => {}
+     * @param {Object} [options.writeConcern] - 写关注选项
+     * @param {string} [options.comment] - 操作注释（用于日志追踪）
+     * @returns {Promise<Object>} 删除结果
+     *
+     * @example
+     * const result = await collection('logs').deleteBatch(
+     *     { createdAt: { $lt: new Date('2024-01-01') } },
+     *     {
+     *         batchSize: 1000,
+     *         estimateProgress: true,
+     *         onProgress: (p) => console.log(`进度: ${p.percentage}%`)
+     *     }
+     * );
+     */
+    const deleteBatch = async function deleteBatch(filter, options = {}) {
+        const startTime = Date.now();
+
+        // 1. 参数验证
+        if (!filter || typeof filter !== 'object' || Array.isArray(filter)) {
+            throw createError(
+                ErrorCodes.INVALID_ARGUMENT,
+                'filter 必须是对象类型',
+                [{ field: 'filter', type: 'object.required', message: 'filter 是必需参数且必须是对象' }]
+            );
+        }
+
+        // 自动转换 ObjectId 字符串
+        const convertedFilter = convertObjectIdStrings(filter, 'filter', 0, new WeakSet(), {
+            logger: context.logger,
+            excludeFields: context.autoConvertConfig?.excludeFields,
+            customFieldPatterns: context.autoConvertConfig?.customFieldPatterns,
+            maxDepth: context.autoConvertConfig?.maxDepth
+        });
+
+        // 解构选项
+        const {
+            batchSize = 1000,
+            estimateProgress = true,
+            onProgress,
+            onError = 'stop',
+            retryAttempts = 3,
+            retryDelay = 1000,
+            onRetry,
+            writeConcern,
+            comment
+        } = options;
+
+        // 2. 预先 count（可选）
+        const totalCount = estimateProgress
+            ? await nativeCollection.countDocuments(convertedFilter)
+            : null;
+
+        // 3. 初始化结果
+        const result = {
+            acknowledged: true,
+            totalCount,
+            deletedCount: 0,
+            batchCount: 0,
+            errors: [],
+            retries: []
+        };
+
+        // 4. 🔴 关键：直接调用 context 的 find 流式方法
+        const stream = await context.find(convertedFilter, {
+            stream: true,
+            batchSize,
+            limit: 0,  // 🔴 重要：禁用默认的 limit，否则只会查询默认的 10 条
+            comment: comment ? `${comment}:deleteBatch` : 'deleteBatch'
+        });
+
+        let batch = [];
+
+        return new Promise((resolve, reject) => {
+            // 5. 监听数据事件
+            stream.on('data', async (doc) => {
+                batch.push(doc._id);
+
+                // 达到批次大小，执行删除
+                if (batch.length >= batchSize) {
+                    stream.pause();
+
+                    try {
+                        // 🔴 带重试的批量删除
+                        const batchResult = await executeBatchWithRetry(
+                            () => nativeCollection.deleteMany(
+                                { _id: { $in: batch } },
+                                { writeConcern }
+                            ),
+                            { onError, retryAttempts, retryDelay, onRetry, batchIndex: result.batchCount }
+                        );
+
+                        result.deletedCount += batchResult.result.deletedCount;
+                        result.batchCount++;
+
+                        // 记录重试信息
+                        if (batchResult.attempts > 0) {
+                            result.retries.push({
+                                batchIndex: result.batchCount - 1,
+                                attempts: batchResult.attempts,
+                                success: true
+                            });
+                        }
+
+                        batch = [];
+
+                        // 🔴 进度回调
+                        if (onProgress) {
+                            onProgress({
+                                currentBatch: result.batchCount,
+                                totalBatches: totalCount ? Math.ceil(totalCount / batchSize) : null,
+                                deleted: result.deletedCount,
+                                total: totalCount,
+                                percentage: totalCount ? Math.round((result.deletedCount / totalCount) * 100) : null,
+                                errors: result.errors.length,
+                                retries: result.retries.length
+                            });
+                        }
+
+                        stream.resume();
+
+                    } catch (error) {
+                        // 🔴 错误处理
+                        result.errors.push({
+                            batchIndex: result.batchCount,
+                            batchSize: batch.length,
+                            error: error,
+                            message: error.message
+                        });
+
+                        if (onError === 'stop') {
+                            stream.destroy();
+                            reject(createError(
+                                ErrorCodes.WRITE_ERROR,
+                                `deleteBatch 操作失败: ${error.message}`,
+                                null,
+                                error
+                            ));
+                            return;
+                        }
+
+                        // skip 或 collect：清空批次，继续
+                        batch = [];
+                        result.batchCount++;
+                        stream.resume();
+                    }
+                }
+            });
+
+            // 6. 监听流结束事件
+            stream.on('end', async () => {
+                // 处理剩余的批次
+                if (batch.length > 0) {
+                    try {
+                        const batchResult = await executeBatchWithRetry(
+                            () => nativeCollection.deleteMany(
+                                { _id: { $in: batch } },
+                                { writeConcern }
+                            ),
+                            { onError, retryAttempts, retryDelay, onRetry, batchIndex: result.batchCount }
+                        );
+
+                        result.deletedCount += batchResult.result.deletedCount;
+                        result.batchCount++;
+
+                        if (batchResult.attempts > 0) {
+                            result.retries.push({
+                                batchIndex: result.batchCount - 1,
+                                attempts: batchResult.attempts,
+                                success: true
+                            });
+                        }
+
+                        // 最后一批的进度回调
+                        if (onProgress) {
+                            onProgress({
+                                currentBatch: result.batchCount,
+                                deleted: result.deletedCount,
+                                total: totalCount,
+                                percentage: totalCount ? 100 : null,
+                                errors: result.errors.length,
+                                retries: result.retries.length
+                            });
+                        }
+
+                    } catch (error) {
+                        result.errors.push({
+                            batchIndex: result.batchCount,
+                            batchSize: batch.length,
+                            error: error,
+                            message: error.message
+                        });
+                    }
+                }
+
+                // 7. 最终缓存失效
+                if (cache && result.deletedCount > 0) {
+                    try {
+                        const ns = {
+                            iid: instanceId,
+                            type: 'mongodb',
+                            db: databaseName,
+                            collection: collectionName
+                        };
+                        const pattern = CacheFactory.buildNamespacePattern(ns);
+
+                        // 检查是否在事务中
+                        if (isInTransaction(options)) {
+                            const tx = getTransactionFromSession(options.session);
+                            if (tx && typeof tx.recordInvalidation === 'function') {
+                                await tx.recordInvalidation(pattern, {
+                                    operation: 'write',
+                                    query: filter || {},
+                                    collection: collectionName
+                                });
+                                logger.debug(`[deleteBatch] 事务中失效缓存: ${ns.db}.${ns.collection}`);
+                            } else {
+                                const deleted = await cache.delPattern(pattern);
+                                if (deleted > 0) {
+                                    logger.debug(`[deleteBatch] 自动失效缓存: ${ns.db}.${ns.collection}, 删除 ${deleted} 个缓存键`);
+                                }
+                            }
+                        } else {
+                            const deleted = await cache.delPattern(pattern);
+                            if (deleted > 0) {
+                                logger.debug(`[deleteBatch] 自动失效缓存: ${ns.db}.${ns.collection}, 删除 ${deleted} 个缓存键`);
+                            }
+                        }
+                    } catch (cacheErr) {
+                        logger.warn(`[deleteBatch] 缓存失效失败: ${cacheErr.message}`);
+                    }
+                }
+
+                // 8. 慢查询日志
+                const duration = Date.now() - startTime;
+                const slowQueryMs = defaults.slowQueryMs || 1000;
+
+                if (duration > slowQueryMs) {
+                    logger.warn(`[deleteBatch] 慢操作警告`, {
+                        ns: `${databaseName}.${collectionName}`,
+                        duration,
+                        threshold: slowQueryMs,
+                        totalCount,
+                        deletedCount: result.deletedCount,
+                        batchCount: result.batchCount,
+                        errorCount: result.errors.length,
+                        retryCount: result.retries.length,
+                        comment
+                    });
+                } else {
+                    logger.debug(`[deleteBatch] 操作完成`, {
+                        ns: `${databaseName}.${collectionName}`,
+                        duration,
+                        deletedCount: result.deletedCount,
+                        batchCount: result.batchCount
+                    });
+                }
+
+                resolve(result);
+            });
+
+            // 9. 监听流错误事件
+            stream.on('error', (error) => {
+                logger.error(`[deleteBatch] 流式查询错误`, {
+                    ns: `${databaseName}.${collectionName}`,
+                    error: error.message,
+                    code: error.code
+                });
+
+                result.errors.push({
+                    batchIndex: result.batchCount,
+                    error: error,
+                    message: `流式查询错误: ${error.message}`
+                });
+
+                reject(createError(
+                    ErrorCodes.WRITE_ERROR,
+                    `deleteBatch 流式查询失败: ${error.message}`,
+                    null,
+                    error
+                ));
+            });
+        });
+    };
+
+    return { deleteBatch };
+}
+
+module.exports = { createDeleteBatchOps };
+

package/lib/mongodb/writes/increment-one.js

@@ -146,6 +146,12 @@ function createIncrementOneOps(context) {
         const returnDocument = actualOptions.returnDocument || 'after';
         const projection = actualOptions.projection;
 
+        // 🔧 Model 层 timestamps 支持：从 options.$set 读取额外的字段更新
+        if (actualOptions.$set && typeof actualOptions.$set === 'object') {
+            // 合并到 incUpdate
+            incUpdate.$set = actualOptions.$set;
+        }
+
         const updateOptions = {
             returnDocument,
             includeResultMetadata: true,

package/lib/mongodb/writes/index.js

@@ -8,6 +8,7 @@ const { createInsertManyOps } = require('./insert-many');
 const { createInsertBatchOps } = require('./insert-batch');
 const { createUpdateOneOps } = require('./update-one');
 const { createUpdateManyOps } = require('./update-many');
+const { createUpdateBatchOps } = require('./update-batch');  // 🆕 批量更新
 const { createReplaceOneOps } = require('./replace-one');
 const { createUpsertOneOps } = require('./upsert-one');  // upsertOne 便利方法
 const { createIncrementOneOps } = require('./increment-one');  // 新增：incrementOne 便利方法
@@ -15,6 +16,7 @@ const { createFindOneAndUpdateOps } = require('./find-one-and-update');
 const { createFindOneAndReplaceOps } = require('./find-one-and-replace');
 const { createDeleteOneOps } = require('./delete-one');
 const { createDeleteManyOps } = require('./delete-many');
+const { createDeleteBatchOps } = require('./delete-batch');  // 🆕 批量删除
 const { createFindOneAndDeleteOps } = require('./find-one-and-delete');
 
 module.exports = {
@@ -26,6 +28,7 @@ module.exports = {
     // Update 操作
     createUpdateOneOps,
     createUpdateManyOps,
+    createUpdateBatchOps,  // 🆕 批量更新
     createReplaceOneOps,
     createUpsertOneOps,  // upsertOne 便利方法
     createIncrementOneOps,  // 新增：incrementOne 便利方法
@@ -37,5 +40,6 @@ module.exports = {
     // Delete 操作
     createDeleteOneOps,
     createDeleteManyOps,
+    createDeleteBatchOps,  // 🆕 批量删除
     createFindOneAndDeleteOps,
 };