monsqlize 1.3.0 → 2.0.0

package/lib/mongodb/writes/result-handler.js

@@ -1,237 +0,0 @@
-/**
- * findOneAnd* 操作返回值处理工具
- * 统一处理 MongoDB 驱动返回值的各种边界情况
- *
- * **重要说明 - MongoDB 驱动版本兼容性**
- *
- * 本模块专门处理 MongoDB Node.js 驱动在不同版本间的 API 差异：
- *
- * - **MongoDB 驱动 6.x** (当前支持):
- *   - `findOneAnd*` 方法默认直接返回文档对象
- *   - 需要显式传递 `includeResultMetadata: true` 才返回完整元数据
- *
- * - **MongoDB 驱动 5.x 及更早版本**:
- *   - `findOneAnd*` 方法默认返回 `{ value, ok, lastErrorObject }` 格式
- *
- * **兼容性保证**:
- * - 本模块会自动检测和处理驱动返回值格式的差异
- * - monSQLize 的公共 API 行为保持一致，用户无需关心驱动版本
- * - 如果未来驱动版本再次变更，仅需修改本模块即可
- *
- * **维护建议**:
- * - 升级 MongoDB 驱动前，务必运行完整测试套件
- * - 关注 MongoDB 驱动的 CHANGELOG，特别是 `findOneAnd*` 方法的变更
- * - 如有疑问，参考技术分析报告：`analysis-reports/2025-11-17-mongodb-driver-6x-compatibility-FINAL.md`
- *
- * @module result-handler
- * @since 2025-11-17
- */
-
-// MongoDB 驱动版本检测（用于诊断和警告）
-let _driverVersionChecked = false;
-let _detectedDriverMajorVersion = null;
-
-/**
- * 检测 MongoDB 驱动版本（仅在第一次调用时执行）
- * @private
- * @returns {number|null} 驱动主版本号，如果无法检测则返回 null
- */
-function detectDriverVersion() {
-    if (_driverVersionChecked) {
-        return _detectedDriverMajorVersion;
-    }
-
-    _driverVersionChecked = true;
-
-    try {
-        const mongodb = require('mongodb');
-        const versionString = mongodb.version || require('mongodb/package.json').version;
-        const match = versionString.match(/^(\d+)\./);
-        if (match) {
-            _detectedDriverMajorVersion = parseInt(match[1], 10);
-            return _detectedDriverMajorVersion;
-        }
-    } catch (error) {
-        // 无法检测版本，静默失败
-    }
-
-    return null;
-}
-
-/**
- * 记录驱动版本警告（仅在检测到不支持的版本时）
- * @private
- * @param {Object} logger - 日志实例
- */
-function warnUnsupportedDriverVersion(logger) {
-    const version = detectDriverVersion();
-
-    if (version === null) {
-        // 无法检测版本，不输出警告（避免误报）
-        return;
-    }
-
-    if (version < 6) {
-        // 驱动版本小于 6.x，可能不兼容
-        if (logger && logger.warn) {
-            logger.warn('[result-handler] ⚠️ 检测到 MongoDB 驱动版本过旧', {
-                detectedVersion: version,
-                supportedVersion: '6.x',
-                message: 'monSQLize 专为 MongoDB 驱动 6.x 设计，旧版本可能存在兼容性问题',
-                recommendation: '建议升级到 MongoDB Node.js 驱动 ^6.0.0'
-            });
-        }
-    } else if (version > 6) {
-        // 驱动版本大于 6.x，未经测试
-        if (logger && logger.warn) {
-            logger.warn('[result-handler] ⚠️ 检测到 MongoDB 驱动版本未经测试', {
-                detectedVersion: version,
-                testedVersion: '6.x',
-                message: 'monSQLize 已针对 MongoDB 驱动 6.x 测试，新版本可能存在未知问题',
-                recommendation: '如遇问题，请查看技术分析报告或回退到驱动 6.x'
-            });
-        }
-    }
-    // 版本 === 6，无需警告
-}
-
-/**
- * 处理 findOneAnd* 操作的返回值
- * 统一处理各种边界情况，确保返回值格式的一致性
- *
- * @param {Object|null} result - MongoDB 驱动返回的结果
- * @param {Object} options - 操作选项
- * @param {boolean} [options.includeResultMetadata=false] - 是否返回完整元数据
- * @param {Object} [logger] - 日志实例（可选，用于诊断）
- * @returns {Object|null} 处理后的结果
- *
- * @example
- * // 正常情况（找到文档）
- * const result = { value: { name: "Alice" }, ok: 1, lastErrorObject: { n: 1, updatedExisting: true } };
- * handleFindOneAndResult(result, {});  // 返回: { name: "Alice" }
- *
- * @example
- * // 未找到文档
- * const result = { value: null, ok: 1, lastErrorObject: { n: 0 } };
- * handleFindOneAndResult(result, {});  // 返回: null
- *
- * @example
- * // result 为 null（驱动异常情况）
- * handleFindOneAndResult(null, {});  // 返回: null
- *
- * @example
- * // 返回完整元数据
- * handleFindOneAndResult(null, { includeResultMetadata: true });
- * // 返回: { value: null, ok: 1, lastErrorObject: { n: 0 } }
- */
-function handleFindOneAndResult(result, options = {}, logger = null) {
-    // 首次调用时检测驱动版本并输出警告（如果需要）
-    if (!_driverVersionChecked && logger) {
-        warnUnsupportedDriverVersion(logger);
-    }
-
-    // 情况 1：result 为 null 或 undefined（驱动在某些边界情况下可能返回 null）
-    if (!result || result === null) {
-        if (logger && logger.debug) {
-            logger.debug('[result-handler] Result is null/undefined, returning empty result', {
-                includeMetadata: options.includeResultMetadata
-            });
-        }
-
-        if (options.includeResultMetadata) {
-            // 返回标准的空结果元数据
-            return {
-                value: null,
-                ok: 1,
-                lastErrorObject: { n: 0 }
-            };
-        } else {
-            // 仅返回 null
-            return null;
-        }
-    }
-
-    // 情况 2：result 是对象但缺少 lastErrorObject（驱动版本差异或异常情况）
-    if (typeof result === 'object' && !result.lastErrorObject) {
-        if (logger && logger.warn) {
-            logger.warn('[result-handler] ⚠️ Result missing lastErrorObject, possible driver version issue', {
-                hasValue: result.value !== undefined,
-                hasOk: result.ok !== undefined,
-                resultKeys: Object.keys(result),
-                driverVersion: detectDriverVersion(),
-                recommendation: '这可能表明 MongoDB 驱动返回了非预期的格式，请检查驱动版本'
-            });
-        }
-
-        const hasValue = result.value !== null && result.value !== undefined;
-        // 补充缺失的 lastErrorObject
-        result.lastErrorObject = {
-            n: hasValue ? 1 : 0
-        };
-        // 如果有值，假设是更新/替换操作成功
-        if (hasValue) {
-            result.lastErrorObject.updatedExisting = true;
-        }
-    }
-
-    // 情况 3：result 是对象且包含 lastErrorObject（正常情况）
-    if (options.includeResultMetadata) {
-        // 返回完整元数据：{ value, ok, lastErrorObject }
-        return result;
-    } else {
-        // 仅返回文档（可能为 null）
-        return result.value !== undefined ? result.value : null;
-    }
-}
-
-/**
- * 判断操作是否修改了文档（用于缓存失效逻辑）
- * 安全地检查 MongoDB 操作是否成功修改了文档
- *
- * @param {Object|null} result - MongoDB 驱动返回的结果
- * @returns {boolean} 是否修改/删除了文档
- *
- * @example
- * // 更新成功
- * const result = { value: {...}, lastErrorObject: { updatedExisting: true } };
- * wasDocumentModified(result);  // 返回: true
- *
- * @example
- * // Upsert 插入
- * const result = { value: {...}, lastErrorObject: { upserted: ObjectId(...) } };
- * wasDocumentModified(result);  // 返回: true
- *
- * @example
- * // 未找到文档
- * const result = { value: null, lastErrorObject: { n: 0 } };
- * wasDocumentModified(result);  // 返回: false
- *
- * @example
- * // 删除成功（有返回值）
- * const result = { value: {...}, lastErrorObject: { n: 1 } };
- * wasDocumentModified(result);  // 返回: true
- */
-function wasDocumentModified(result) {
-    // 安全检查：result 或 lastErrorObject 不存在
-    if (!result || !result.lastErrorObject) {
-        return false;
-    }
-
-    // 检查修改标志
-    return !!(
-        // 更新/替换操作：文档已存在并被修改
-        result.lastErrorObject.updatedExisting ||
-        // Upsert 操作：插入了新文档
-        result.lastErrorObject.upserted ||
-        // 删除操作：有文档被删除（通过 n > 0 或 value 不为 null 判断）
-        (result.lastErrorObject.n > 0) ||
-        (result.value !== null && result.value !== undefined)
-    );
-}
-
-module.exports = {
-    handleFindOneAndResult,
-    wasDocumentModified
-};
-
-

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

@@ -1,416 +0,0 @@
-/**
- * updateBatch 操作实现
- * 分批更新大量匹配的文档（基于流式查询）
- */
-
-const { createError, ErrorCodes } = require('../../errors');
-const CacheFactory = require('../../cache');
-const { isInTransaction, getTransactionFromSession } = require('../common/transaction-aware');
-const { convertObjectIdStrings, convertUpdateDocument } = require('../../utils/objectid-converter');
-const { executeBatchWithRetry } = require('./common/batch-retry');
-const { validateAggregationPipeline, isAggregationPipeline } = require('../common/aggregation-validator');
-
-/**
- * 创建 updateBatch 操作
- * @param {Object} context - 模块上下文
- * @returns {Object} 包含 updateBatch 方法的对象
- */
-function createUpdateBatchOps(context) {
-    const { db, cache, logger, defaults, collection, effectiveDbName: databaseName, instanceId } = context;
-
-    const collectionName = collection.collectionName;
-    const nativeCollection = collection;
-
-    /**
-     * 分批更新大量匹配的文档
-     * @param {Object} filter - 筛选条件（必需）
-     * @param {Object} update - 更新操作（必需，使用更新操作符如 $set）
-     * @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('orders').updateBatch(
-     *     { status: 'pending', createdAt: { $lt: expiredDate } },
-     *     { $set: { status: 'expired' } },
-     *     {
-     *         batchSize: 500,
-     *         estimateProgress: true,
-     *         onProgress: (p) => console.log(`进度: ${p.percentage}%`)
-     *     }
-     * );
-     */
-    const updateBatch = async function updateBatch(filter, update, 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 是必需参数且必须是对象' }]
-            );
-        }
-
-        if (!update || (typeof update !== 'object' && !Array.isArray(update))) {
-            throw createError(
-                ErrorCodes.INVALID_ARGUMENT,
-                'update 必须是对象（更新操作符）或数组（聚合管道）',
-                [{ field: 'update', type: 'object|array.required', message: 'update 必须是更新操作符对象或聚合管道数组' }]
-            );
-        }
-
-        // 检测聚合管道模式
-        const isAggregation = isAggregationPipeline(update);
-
-        if (isAggregation) {
-            // 验证聚合管道格式
-            validateAggregationPipeline(update);
-
-            if (logger && logger.debug) {
-                logger.debug(`[updateBatch] 使用聚合管道模式`, {
-                    collection: collectionName,
-                    stagesCount: update.length,
-                    operators: update.map(stage => Object.keys(stage)[0])
-                });
-            }
-        } else {
-            // 验证 update 包含更新操作符
-            const updateKeys = Object.keys(update);
-
-            // 检查空对象
-            if (updateKeys.length === 0) {
-                throw createError(
-                    ErrorCodes.INVALID_ARGUMENT,
-                    'update 不能为空对象',
-                    [{ field: 'update', type: 'object.empty', message: 'update 必须包含至少一个更新操作符' }]
-                );
-            }
-
-            // 检查是否包含操作符
-            if (!updateKeys.some(key => key.startsWith('$'))) {
-                throw createError(
-                    ErrorCodes.INVALID_ARGUMENT,
-                    'update 必须使用更新操作符（如 $set, $inc 等）',
-                    [{ field: 'update', type: 'object.invalid', message: '请使用 $set, $inc, $push 等更新操作符' }]
-                );
-            }
-        }
-
-        // 自动转换 ObjectId 字符串
-        const convertedFilter = convertObjectIdStrings(filter, 'filter', 0, new WeakSet(), {
-            logger: context.logger,
-            excludeFields: context.autoConvertConfig?.excludeFields,
-            customFieldPatterns: context.autoConvertConfig?.customFieldPatterns,
-            maxDepth: context.autoConvertConfig?.maxDepth
-        });
-
-        // ✅ v1.0.8: 聚合管道不转换 ObjectId（保持原样）
-        const convertedUpdate = isAggregation
-            ? update  // 聚合管道保持原样
-            : convertUpdateDocument(update, {
-                  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,
-            matchedCount: 0,
-            modifiedCount: 0,
-            batchCount: 0,
-            errors: [],
-            retries: []
-        };
-
-        // 4. 🔴 关键：直接调用 context 的 find 流式方法
-        const stream = await context.find(convertedFilter, {
-            stream: true,
-            batchSize,
-            limit: 0,  // 🔴 重要：禁用默认的 limit，否则只会查询默认的 10 条
-            comment: comment ? `${comment}:updateBatch` : 'updateBatch'
-        });
-
-        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.updateMany(
-                                { _id: { $in: batch } },
-                                convertedUpdate,
-                                { writeConcern }
-                            ),
-                            { onError, retryAttempts, retryDelay, onRetry, batchIndex: result.batchCount }
-                        );
-
-                        result.matchedCount += batchResult.result.matchedCount;
-                        result.modifiedCount += batchResult.result.modifiedCount;
-                        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,
-                                matched: result.matchedCount,
-                                modified: result.modifiedCount,
-                                total: totalCount,
-                                percentage: totalCount ? Math.round((result.matchedCount / 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,
-                                `updateBatch 操作失败: ${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.updateMany(
-                                { _id: { $in: batch } },
-                                convertedUpdate,
-                                { writeConcern }
-                            ),
-                            { onError, retryAttempts, retryDelay, onRetry, batchIndex: result.batchCount }
-                        );
-
-                        result.matchedCount += batchResult.result.matchedCount;
-                        result.modifiedCount += batchResult.result.modifiedCount;
-                        result.batchCount++;
-
-                        if (batchResult.attempts > 0) {
-                            result.retries.push({
-                                batchIndex: result.batchCount - 1,
-                                attempts: batchResult.attempts,
-                                success: true
-                            });
-                        }
-
-                        // 最后一批的进度回调
-                        if (onProgress) {
-                            onProgress({
-                                currentBatch: result.batchCount,
-                                matched: result.matchedCount,
-                                modified: result.modifiedCount,
-                                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.modifiedCount > 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(`[updateBatch] 事务中失效缓存: ${ns.db}.${ns.collection}`);
-                            } else {
-                                const deleted = await cache.delPattern(pattern);
-                                if (deleted > 0) {
-                                    logger.debug(`[updateBatch] 自动失效缓存: ${ns.db}.${ns.collection}, 删除 ${deleted} 个缓存键`);
-                                }
-                            }
-                        } else {
-                            const deleted = await cache.delPattern(pattern);
-                            if (deleted > 0) {
-                                logger.debug(`[updateBatch] 自动失效缓存: ${ns.db}.${ns.collection}, 删除 ${deleted} 个缓存键`);
-                            }
-                        }
-                    } catch (cacheErr) {
-                        logger.warn(`[updateBatch] 缓存失效失败: ${cacheErr.message}`);
-                    }
-                }
-
-                // 8. 慢查询日志
-                const duration = Date.now() - startTime;
-                const slowQueryMs = defaults.slowQueryMs || 1000;
-
-                if (duration > slowQueryMs) {
-                    logger.warn(`[updateBatch] 慢操作警告`, {
-                        ns: `${databaseName}.${collectionName}`,
-                        duration,
-                        threshold: slowQueryMs,
-                        updateType: isAggregation ? 'aggregation-pipeline' : 'update-operators',
-                        pipelineStages: isAggregation ? update.length : undefined,
-                        totalCount,
-                        matchedCount: result.matchedCount,
-                        modifiedCount: result.modifiedCount,
-                        batchCount: result.batchCount,
-                        errorCount: result.errors.length,
-                        retryCount: result.retries.length,
-                        comment
-                    });
-                } else {
-                    logger.debug(`[updateBatch] 操作完成`, {
-                        ns: `${databaseName}.${collectionName}`,
-                        duration,
-                        updateType: isAggregation ? 'aggregation-pipeline' : 'update-operators',
-                        matchedCount: result.matchedCount,
-                        modifiedCount: result.modifiedCount,
-                        batchCount: result.batchCount
-                    });
-                }
-
-                resolve(result);
-            });
-
-            // 9. 监听流错误事件
-            stream.on('error', (error) => {
-                logger.error(`[updateBatch] 流式查询错误`, {
-                    ns: `${databaseName}.${collectionName}`,
-                    error: error.message,
-                    code: error.code,
-                    updateType: isAggregation ? 'aggregation-pipeline' : 'update-operators'
-                });
-
-                result.errors.push({
-                    batchIndex: result.batchCount,
-                    error: error,
-                    message: `流式查询错误: ${error.message}`
-                });
-
-                // ✨ v1.0.8: 检测聚合管道不支持的错误（MongoDB 4.2+ 才支持）
-                if (isAggregation &&
-                    (error.message.includes('pipeline') ||
-                     error.message.includes('Unrecognized pipeline stage') ||
-                     error.message.includes('The dollar ($) prefixed field') ||
-                     error.code === 40324 ||
-                     error.code === 9)) {
-                    reject(createError(
-                        ErrorCodes.UNSUPPORTED_OPERATION,
-                        'MongoDB 4.2+ 才支持聚合管道更新。请升级 MongoDB 版本或使用传统更新操作符',
-                        [{
-                            field: 'update',
-                            message: error.message,
-                            requirement: 'MongoDB 4.2+',
-                            currentError: error.code,
-                            documentation: 'https://www.mongodb.com/docs/manual/tutorial/update-documents-with-aggregation-pipeline/'
-                        }],
-                        error
-                    ));
-                    return;
-                }
-
-                reject(createError(
-                    ErrorCodes.WRITE_ERROR,
-                    `updateBatch 流式查询失败: ${error.message}`,
-                    null,
-                    error
-                ));
-            });
-        });
-    };
-
-    return { updateBatch };
-}
-
-module.exports = { createUpdateBatchOps };
-
-