monsqlize 1.3.0 → 2.0.0

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

@@ -1,323 +0,0 @@
-/**
- * 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/delete-many.js

@@ -1,181 +0,0 @@
-/**
- * deleteMany 操作实现
- * 删除所有匹配的文档
- */
-
-const { createError, ErrorCodes } = require('../../errors');
-const CacheFactory = require('../../cache');
-const { isInTransaction, getTransactionFromSession } = require('../common/transaction-aware');
-const { convertObjectIdStrings } = require('../../utils/objectid-converter');
-
-/**
- * 创建 deleteMany 操作
- * @param {Object} context - 模块上下文
- * @param {Object} context.db - MongoDB 数据库实例
- * @param {Object} context.cache - 缓存实例
- * @param {Object} context.logger - 日志实例
- * @param {Object} context.defaults - 默认配置
- * @param {string} context.collection - 集合名称
- * @param {string} context.effectiveDbName - 数据库名称
- * @param {string} context.instanceId - 实例ID
- * @returns {Object} 包含 deleteMany 方法的对象
- */
-function createDeleteManyOps(context) {
-    const { db, cache, logger, defaults, collection, effectiveDbName: databaseName, instanceId } = context;
-
-    // 提取集合名称和原生 collection 对象
-    const collectionName = collection.collectionName;
-    const nativeCollection = collection;
-
-    /**
-     * 删除所有匹配的文档
-     * @param {Object} filter - 筛选条件（必需）
-     * @param {Object} [options] - 操作选项
-     * @param {Object} [options.collation] - 排序规则
-     * @param {Object} [options.hint] - 索引提示
-     * @param {number} [options.maxTimeMS] - 最大执行时间（毫秒）
-     * @param {Object} [options.writeConcern] - 写关注选项
-     * @param {string} [options.comment] - 操作注释（用于日志追踪）
-     * @returns {Promise<Object>} 返回删除结果 { deletedCount, acknowledged }
-     * @throws {Error} 当参数无效时
-     *
-     * @example
-     * // 删除所有匹配的文档
-     * const result = await collection("logs").deleteMany({
-     *     createdAt: { $lt: new Date("2024-01-01") }
-     * });
-     * console.log("已删除:", result.deletedCount);
-     *
-     * @example
-     * // 删除所有文档（危险操作！）
-     * const result = await collection("temp_data").deleteMany({});
-     * console.log("已清空集合，删除:", result.deletedCount);
-     *
-     * @example
-     * // 使用索引提示优化删除性能
-     * const result = await collection("events").deleteMany(
-     *     { status: "archived", createdAt: { $lt: someDate } },
-     *     { hint: { status: 1, createdAt: 1 } }
-     * );
-     */
-    const deleteMany = async function deleteMany(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 是必需参数且必须是对象' }]
-            );
-        }
-
-        // ✅ v1.3.0: 自动转换 ObjectId 字符串
-        const convertedFilter = convertObjectIdStrings(filter, 'filter', 0, new WeakSet(), {
-            logger: context.logger,
-            excludeFields: context.autoConvertConfig?.excludeFields,
-            customFieldPatterns: context.autoConvertConfig?.customFieldPatterns,
-            maxDepth: context.autoConvertConfig?.maxDepth
-        });
-
-        // 2. 警告：空 filter 会删除所有文档
-        if (Object.keys(convertedFilter).length === 0) {
-            logger.warn('[deleteMany] 警告: 空 filter 将删除集合中的所有文档', {
-                ns: `${databaseName}.${collectionName}`,
-                comment: options.comment
-            });
-        }
-
-        // 3. 构建操作上下文
-        const operation = 'deleteMany';
-        const ns = `${databaseName}.${collectionName}`;
-
-        try {
-            // 4. 执行删除操作
-            const result = await nativeCollection.deleteMany(convertedFilter, options);
-
-            // 5. 自动失效缓存（如果有文档被删除）
-            if (cache && result.deletedCount > 0) {
-                try {
-                    // 🆕 v1.1.6: 解析精准失效配置
-                    const instanceAuto = context.cacheAutoInvalidate || false;
-                    const queryAuto = options.autoInvalidate;
-                    const shouldAuto = queryAuto !== undefined ? queryAuto : instanceAuto;
-
-                    if (shouldAuto) {
-                        // 精准失效：deleteMany 使用 filter 作为文档
-                        const CacheInvalidationEngine = require('../../cache-invalidation');
-                        const deleted = await CacheInvalidationEngine.invalidatePrecise(cache, {
-                            instanceId,
-                            type: 'mongodb',
-                            db: databaseName,
-                            collection: collectionName,
-                            document: convertedFilter,
-                            operation: 'deleteMany'
-                        });
-
-                        if (deleted > 0) {
-                            logger.debug(`[${operation}] 精准失效缓存: ${databaseName}.${collectionName}, 删除 ${deleted} 个缓存键`);
-                        }
-                    } else {
-                        logger.debug(`[${operation}] 跳过自动失效（autoInvalidate=false）`);
-                    }
-                } catch (cacheErr) {
-                    logger.warn(`[${operation}] 缓存失效失败: ${cacheErr.message}`, { ns: `${databaseName}.${collectionName}`, error: cacheErr });
-                }
-            }
-
-            // 6. 记录慢操作日志
-            const duration = Date.now() - startTime;
-            const slowQueryMs = defaults.slowQueryMs || 1000;
-            if (duration > slowQueryMs) {
-                logger.warn(`[${operation}] 慢操作警告`, {
-                    ns,
-                    duration,
-                    threshold: slowQueryMs,
-                    filterKeys: Object.keys(filter),
-                    deletedCount: result.deletedCount,
-                    comment: options.comment
-                });
-            } else {
-                logger.debug(`[${operation}] 操作完成`, {
-                    ns,
-                    duration,
-                    deletedCount: result.deletedCount
-                });
-            }
-
-            // 7. 返回结果
-            return {
-                deletedCount: result.deletedCount,
-                acknowledged: result.acknowledged
-            };
-
-        } catch (error) {
-            // 8. 错误处理
-            const duration = Date.now() - startTime;
-
-            logger.error(`[${operation}] 操作失败`, {
-                ns,
-                duration,
-                error: error.message,
-                code: error.code,
-                filterKeys: Object.keys(filter)
-            });
-
-            // 其他错误
-            throw createError(
-                ErrorCodes.WRITE_ERROR,
-                `deleteMany 操作失败: ${error.message}`,
-                null,
-                error
-            );
-        }
-    };
-
-    return { deleteMany };
-}
-
-module.exports = { createDeleteManyOps };
-
-

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

@@ -1,173 +0,0 @@
-/**
- * deleteOne 操作实现
- * 删除单个匹配的文档
- */
-
-const { createError, ErrorCodes } = require('../../errors');
-const CacheFactory = require('../../cache');
-const { isInTransaction, getTransactionFromSession } = require('../common/transaction-aware');
-const { convertObjectIdStrings } = require('../../utils/objectid-converter');
-
-/**
- * 创建 deleteOne 操作
- * @param {Object} context - 模块上下文
- * @param {Object} context.db - MongoDB 数据库实例
- * @param {Object} context.cache - 缓存实例
- * @param {Object} context.logger - 日志实例
- * @param {Object} context.defaults - 默认配置
- * @param {string} context.collection - 集合名称
- * @param {string} context.effectiveDbName - 数据库名称
- * @param {string} context.instanceId - 实例ID
- * @returns {Object} 包含 deleteOne 方法的对象
- */
-function createDeleteOneOps(context) {
-    const { db, cache, logger, defaults, collection, effectiveDbName: databaseName, instanceId } = context;
-
-    // 提取集合名称和原生 collection 对象
-    const collectionName = collection.collectionName;
-    const nativeCollection = collection;
-
-    /**
-     * 删除单个匹配的文档
-     * @param {Object} filter - 筛选条件（必需）
-     * @param {Object} [options] - 操作选项
-     * @param {Object} [options.collation] - 排序规则
-     * @param {Object} [options.hint] - 索引提示
-     * @param {number} [options.maxTimeMS] - 最大执行时间（毫秒）
-     * @param {Object} [options.writeConcern] - 写关注选项
-     * @param {string} [options.comment] - 操作注释（用于日志追踪）
-     * @returns {Promise<Object>} 返回删除结果 { deletedCount, acknowledged }
-     * @throws {Error} 当参数无效时
-     *
-     * @example
-     * // 删除单个文档
-     * const result = await collection("users").deleteOne({ userId: "user123" });
-     * console.log("已删除:", result.deletedCount); // 0 或 1
-     *
-     * @example
-     * // 使用 collation（不区分大小写）
-     * const result = await collection("users").deleteOne(
-     *     { name: "alice" },
-     *     { collation: { locale: "en", strength: 2 } }
-     * );
-     *
-     * @example
-     * // 使用索引提示
-     * const result = await collection("orders").deleteOne(
-     *     { orderId: "order123" },
-     *     { hint: { orderId: 1 } }
-     * );
-     */
-    const deleteOne = async function deleteOne(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 是必需参数且必须是对象' }]
-            );
-        }
-
-        // ✅ v1.3.0: 自动转换 ObjectId 字符串
-        const convertedFilter = convertObjectIdStrings(filter, 'filter', 0, new WeakSet(), {
-            logger: context.logger,
-            excludeFields: context.autoConvertConfig?.excludeFields,
-            customFieldPatterns: context.autoConvertConfig?.customFieldPatterns,
-            maxDepth: context.autoConvertConfig?.maxDepth
-        });
-
-        // 2. 构建操作上下文
-        const operation = 'deleteOne';
-        const ns = `${databaseName}.${collectionName}`;
-
-        try {
-            // 3. 执行删除操作
-            const result = await nativeCollection.deleteOne(convertedFilter, options);
-
-            // 4. 自动失效缓存（如果有文档被删除）
-            if (cache && result.deletedCount > 0) {
-                try {
-                    // 🆕 v1.1.6: 解析精准失效配置
-                    const instanceAuto = context.cacheAutoInvalidate || false;
-                    const queryAuto = options.autoInvalidate;
-                    const shouldAuto = queryAuto !== undefined ? queryAuto : instanceAuto;
-
-                    if (shouldAuto) {
-                        // 精准失效：deleteOne 使用 filter 作为文档
-                        const CacheInvalidationEngine = require('../../cache-invalidation');
-                        const deleted = await CacheInvalidationEngine.invalidatePrecise(cache, {
-                            instanceId,
-                            type: 'mongodb',
-                            db: databaseName,
-                            collection: collectionName,
-                            document: convertedFilter,
-                            operation: 'deleteOne'
-                        });
-
-                        if (deleted > 0) {
-                            logger.debug(`[${operation}] 精准失效缓存: ${databaseName}.${collectionName}, 删除 ${deleted} 个缓存键`);
-                        }
-                    } else {
-                        logger.debug(`[${operation}] 跳过自动失效（autoInvalidate=false）`);
-                    }
-                } catch (cacheErr) {
-                    logger.warn(`[${operation}] 缓存失效失败: ${cacheErr.message}`, { ns: `${databaseName}.${collectionName}`, error: cacheErr });
-                }
-            }
-
-            // 5. 记录慢操作日志
-            const duration = Date.now() - startTime;
-            const slowQueryMs = defaults.slowQueryMs || 1000;
-            if (duration > slowQueryMs) {
-                logger.warn(`[${operation}] 慢操作警告`, {
-                    ns,
-                    duration,
-                    threshold: slowQueryMs,
-                    filterKeys: Object.keys(filter),
-                    deletedCount: result.deletedCount,
-                    comment: options.comment
-                });
-            } else {
-                logger.debug(`[${operation}] 操作完成`, {
-                    ns,
-                    duration,
-                    deletedCount: result.deletedCount
-                });
-            }
-
-            // 6. 返回结果
-            return {
-                deletedCount: result.deletedCount,
-                acknowledged: result.acknowledged
-            };
-
-        } catch (error) {
-            // 7. 错误处理
-            const duration = Date.now() - startTime;
-
-            logger.error(`[${operation}] 操作失败`, {
-                ns,
-                duration,
-                error: error.message,
-                code: error.code,
-                filterKeys: Object.keys(filter)
-            });
-
-            // 其他错误
-            throw createError(
-                ErrorCodes.WRITE_ERROR,
-                `deleteOne 操作失败: ${error.message}`,
-                null,
-                error
-            );
-        }
-    };
-
-    return { deleteOne };
-}
-
-module.exports = { createDeleteOneOps };
-
-