monsqlize 1.3.0 → 2.0.0

package/lib/mongodb/writes/insert-many.js

@@ -1,223 +0,0 @@
-/**
- * insertMany 操作实现
- * 批量插入多个文档到集合
- */
-
-const { createError, ErrorCodes } = require('../../errors');
-const CacheFactory = require('../../cache');
-const { isInTransaction, getTransactionFromSession } = require('../common/transaction-aware');
-const { convertObjectIdStrings } = require('../../utils/objectid-converter');
-
-/**
- * 创建 insertMany 操作
- * @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} 包含 insertMany 方法的对象
- */
-function createInsertManyOps(context) {
-    const { db, cache, logger, defaults, collection, effectiveDbName: databaseName, instanceId } = context;
-
-    // 提取集合名称和原生 collection 对象
-    const collectionName = collection.collectionName;
-    const nativeCollection = collection;
-
-    /**
-     * 批量插入多个文档
-     * @param {Array<Object>} documents - 要插入的文档数组（必需）
-     * @param {Object} [options] - 操作选项
-     * @param {boolean} [options.ordered=true] - 是否按顺序插入（遇到错误是否继续）
-     * @param {Object} [options.writeConcern] - 写关注选项
-     * @param {boolean} [options.bypassDocumentValidation] - 是否绕过文档验证
-     * @param {string} [options.comment] - 操作注释（用于日志追踪）
-     * @returns {Promise<Object>} 插入结果 { acknowledged, insertedCount, insertedIds }
-     * @throws {Error} 当 documents 参数无效时
-     *
-     * @example
-     * const result = await collection('users').insertMany([
-     *     { name: 'Alice', age: 25 },
-     *     { name: 'Bob', age: 30 }
-     * ]);
-     * console.log('Inserted count:', result.insertedCount);
-     * console.log('Inserted IDs:', result.insertedIds);
-     *
-     * @example
-     * // 使用 options 参数
-     * const result = await collection('users').insertMany(
-     *     [
-     *         { name: 'Charlie', age: 35 },
-     *         { name: 'David', age: 40 }
-     *     ],
-     *     { ordered: false, comment: 'batch insert' }
-     * );
-     */
-    const insertMany = async function insertMany(documents, options = {}) {
-        const startTime = Date.now();
-
-        // 1. 参数验证
-        if (!Array.isArray(documents)) {
-            throw createError(
-                ErrorCodes.DOCUMENTS_REQUIRED,
-                'documents 必须是数组类型',
-                [{ field: 'documents', type: 'array.required', message: 'documents 是必需参数且必须是数组' }]
-            );
-        }
-
-        if (documents.length === 0) {
-            throw createError(
-                ErrorCodes.DOCUMENTS_REQUIRED,
-                'documents 数组不能为空',
-                [{ field: 'documents', type: 'array.min', message: 'documents 至少需要包含一个文档' }]
-            );
-        }
-
-        // 验证每个文档都是对象
-        const invalidDocs = documents.filter((doc, index) => {
-            return !doc || typeof doc !== 'object' || Array.isArray(doc);
-        });
-
-        if (invalidDocs.length > 0) {
-            throw createError(
-                ErrorCodes.DOCUMENTS_REQUIRED,
-                'documents 中的所有元素必须是对象类型',
-                invalidDocs.map((doc, idx) => ({
-                    field: `documents[${idx}]`,
-                    type: 'object.required',
-                    message: '必须是对象类型'
-                }))
-            );
-        }
-
-        // ✅ v1.3.0: 自动转换 ObjectId 字符串
-        const convertedDocuments = documents.map(doc => convertObjectIdStrings(doc, 'document', 0, new WeakSet(), {
-            logger: context.logger,
-            excludeFields: context.autoConvertConfig?.excludeFields,
-            customFieldPatterns: context.autoConvertConfig?.customFieldPatterns,
-            maxDepth: context.autoConvertConfig?.maxDepth
-        }));
-
-        // 2. 构建操作上下文
-        const operation = 'insertMany';
-        const ns = `${databaseName}.${collectionName}`;
-        const docCount = documents.length;
-
-        try {
-            // 3. 执行批量插入操作
-            const result = await nativeCollection.insertMany(convertedDocuments, options);
-
-            // 4. 自动失效缓存
-            if (cache) {
-                try {
-                    // 🆕 v1.1.6: 解析精准失效配置
-                    const instanceAuto = context.cacheAutoInvalidate || false;
-                    const queryAuto = options.autoInvalidate;
-                    const shouldAuto = queryAuto !== undefined ? queryAuto : instanceAuto;
-
-
-                    if (shouldAuto) {
-                        // 精准失效：对每个插入的文档执行失效
-                        const CacheInvalidationEngine = require('../../cache-invalidation');
-                        let totalDeleted = 0;
-
-                        for (const doc of convertedDocuments) {
-                            const deleted = await CacheInvalidationEngine.invalidatePrecise(cache, {
-                                instanceId,
-                                type: 'mongodb',
-                                db: databaseName,
-                                collection: collectionName,
-                                document: doc,
-                                operation: 'insertMany'
-                            });
-                            totalDeleted += deleted;
-                        }
-
-                        if (totalDeleted > 0) {
-                            logger.debug(`[${operation}] 精准失效缓存: ${databaseName}.${collectionName}, 删除 ${totalDeleted} 个缓存键`);
-                        }
-                    } 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,
-                    documentCount: docCount,
-                    insertedCount: result.insertedCount,
-                    ordered: options.ordered !== false,
-                    comment: options.comment
-                });
-            } else {
-                logger.debug(`[${operation}] 操作完成`, {
-                    ns,
-                    duration,
-                    documentCount: docCount,
-                    insertedCount: result.insertedCount
-                });
-            }
-
-            return result;
-
-        } catch (error) {
-            // 6. 错误处理
-            const duration = Date.now() - startTime;
-
-            logger.error(`[${operation}] 操作失败`, {
-                ns,
-                duration,
-                error: error.message,
-                code: error.code,
-                documentCount: docCount,
-                ordered: options.ordered !== false
-            });
-
-            // 识别特定错误类型
-            if (error.code === 11000) {
-                // MongoDB 重复键错误
-                throw createError(
-                    ErrorCodes.DUPLICATE_KEY,
-                    '批量插入失败：违反唯一性约束',
-                    [{ message: error.message, writeErrors: error.writeErrors }],
-                    error
-                );
-            }
-
-            // 部分成功的情况（ordered=false 时可能发生）
-            if (error.result && error.result.insertedCount > 0) {
-                logger.warn(`[${operation}] 部分成功`, {
-                    ns,
-                    insertedCount: error.result.insertedCount,
-                    totalCount: docCount,
-                    failedCount: docCount - error.result.insertedCount
-                });
-            }
-
-            // 其他错误
-            throw createError(
-                ErrorCodes.WRITE_ERROR,
-                `insertMany 操作失败: ${error.message}`,
-                error.writeErrors || null,
-                error
-            );
-        }
-    };
-
-    return { insertMany };
-}
-
-module.exports = { createInsertManyOps };
-

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

@@ -1,169 +0,0 @@
-/**
- * insertOne 操作实现
- * 插入单个文档到集合
- */
-
-const { createError, ErrorCodes } = require('../../errors');
-const CacheFactory = require('../../cache');
-const { isInTransaction, getTransactionFromSession } = require('../common/transaction-aware');
-const { convertObjectIdStrings } = require('../../utils/objectid-converter');
-
-/**
- * 创建 insertOne 操作
- * @param {Object} context - 模块上下文
- * @param {Object} context.db - MongoDB 数据库实例
- * @param {Object} context.cache - 缓存实例
- * @param {Object} context.logger - 日志实例
- * @param {Object} context.defaults - 默认配置
- * @param {string} context.collectionName - 集合名称
- * @param {string} context.databaseName - 数据库名称
- * @param {string} context.instanceId - 实例ID
- * @returns {Object} 包含 insertOne 方法的对象
- */
-function createInsertOneOps(context) {
-    const { db, cache, logger, defaults, collection, effectiveDbName: databaseName, instanceId } = context;
-
-    // 提取集合名称和原生 collection 对象
-    const collectionName = collection.collectionName;
-    const nativeCollection = collection;
-
-    /**
-     * 插入单个文档
-     * @param {Object} document - 要插入的文档（必需）
-     * @param {Object} [options] - 操作选项
-     * @param {Object} [options.writeConcern] - 写关注选项
-     * @param {boolean} [options.bypassDocumentValidation] - 是否绕过文档验证
-     * @param {string} [options.comment] - 操作注释（用于日志追踪）
-     * @returns {Promise<Object>} 插入结果 { acknowledged, insertedId }
-     * @throws {Error} 当 document 参数无效时
-     *
-     * @example
-     * const result = await collection('users').insertOne(
-     *     { name: 'Alice', age: 25 }
-     * );
-     * console.log('Inserted ID:', result.insertedId);
-     *
-     * @example
-     * // 使用 options 参数
-     * const result = await collection('users').insertOne(
-     *     { name: 'Bob', age: 30 },
-     *     { bypassDocumentValidation: true, comment: 'test insert' }
-     * );
-     */
-    const insertOne = async function insertOne(document, options = {}) {
-        const startTime = Date.now();
-
-        // 1. 参数验证
-        if (!document || typeof document !== 'object' || Array.isArray(document)) {
-            throw createError(
-                ErrorCodes.DOCUMENT_REQUIRED,
-                'document 必须是对象类型',
-                [{ field: 'document', type: 'object.required', message: 'document 是必需参数且必须是对象' }]
-            );
-        }
-
-        // ✅ v1.3.0: 自动转换 ObjectId 字符串
-        const convertedDocument = convertObjectIdStrings(document, 'document', 0, new WeakSet(), {
-            logger: context.logger,
-            excludeFields: context.autoConvertConfig?.excludeFields,
-            customFieldPatterns: context.autoConvertConfig?.customFieldPatterns,
-            maxDepth: context.autoConvertConfig?.maxDepth
-        });
-
-        // 2. 构建操作上下文
-        const operation = 'insertOne';
-        const ns = `${databaseName}.${collectionName}`;
-
-        try {
-            // 3. 执行插入操作
-            const result = await nativeCollection.insertOne(convertedDocument, options);
-
-            // 4. 自动失效缓存
-            if (cache) {
-                try {
-                    // 🆕 v1.1.6: 解析精准失效配置
-                    const instanceAuto = context.cacheAutoInvalidate || false;
-                    const queryAuto = options.autoInvalidate;
-                    const shouldAuto = queryAuto !== undefined ? queryAuto : instanceAuto;
-
-                    if (shouldAuto) {
-                        // 精准失效
-                        const CacheInvalidationEngine = require('../../cache-invalidation');
-                        const deleted = await CacheInvalidationEngine.invalidatePrecise(cache, {
-                            instanceId,
-                            type: 'mongodb',
-                            db: databaseName,
-                            collection: collectionName,
-                            document: convertedDocument,
-                            operation: 'insertOne'
-                        });
-                        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,
-                    documentKeys: Object.keys(document),
-                    insertedId: result.insertedId,
-                    comment: options.comment
-                });
-            } else {
-                logger.debug(`[${operation}] 操作完成`, {
-                    ns,
-                    duration,
-                    insertedId: result.insertedId
-                });
-            }
-
-            return result;
-
-        } catch (error) {
-            // 6. 错误处理
-            const duration = Date.now() - startTime;
-
-            logger.error(`[${operation}] 操作失败`, {
-                ns,
-                duration,
-                error: error.message,
-                code: error.code,
-                documentKeys: Object.keys(document)
-            });
-
-            // 识别特定错误类型
-            if (error.code === 11000) {
-                // MongoDB 重复键错误
-                throw createError(
-                    ErrorCodes.DUPLICATE_KEY,
-                    '文档插入失败：违反唯一性约束',
-                    [{ field: '_id', message: error.message }],
-                    error
-                );
-            }
-
-            // 其他错误
-            throw createError(
-                ErrorCodes.WRITE_ERROR,
-                `insertOne 操作失败: ${error.message}`,
-                null,
-                error
-            );
-        }
-    };
-
-    return { insertOne };
-} module.exports = { createInsertOneOps };
-

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

@@ -1,226 +0,0 @@
-/**
- * replaceOne 操作实现
- * 完整替换单个匹配的文档
- */
-
-const { createError, ErrorCodes } = require('../../errors');
-const CacheFactory = require('../../cache');
-const { isInTransaction, getTransactionFromSession } = require('../common/transaction-aware');
-const { convertObjectIdStrings } = require('../../utils/objectid-converter');
-
-/**
- * 创建 replaceOne 操作
- * @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} 包含 replaceOne 方法的对象
- */
-function createReplaceOneOps(context) {
-    const { db, cache, logger, defaults, collection, effectiveDbName: databaseName, instanceId } = context;
-
-    // 提取集合名称和原生 collection 对象
-    const collectionName = collection.collectionName;
-    const nativeCollection = collection;
-
-    /**
-     * 替换单个文档（完整替换，不使用更新操作符）
-     * @param {Object} filter - 筛选条件（必需）
-     * @param {Object} replacement - 替换文档（必需，不能包含更新操作符）
-     * @param {Object} [options] - 操作选项
-     * @param {boolean} [options.upsert=false] - 不存在时是否插入
-     * @param {Object} [options.writeConcern] - 写关注选项
-     * @param {boolean} [options.bypassDocumentValidation] - 是否绕过文档验证
-     * @param {string} [options.comment] - 操作注释（用于日志追踪）
-     * @param {Object} [options.collation] - 排序规则
-     * @param {Object} [options.hint] - 索引提示
-     * @returns {Promise<Object>} 替换结果 { acknowledged, matchedCount, modifiedCount, upsertedId?, upsertedCount? }
-     * @throws {Error} 当参数无效时
-     *
-     * @example
-     * const result = await collection("users").replaceOne(
-     *     { userId: "user123" },
-     *     { userId: "user123", name: "Alice", age: 25, status: "active" }
-     * );
-     * console.log("Modified:", result.modifiedCount);
-     *
-     * @example
-     * // 使用 upsert 选项
-     * const result = await collection("users").replaceOne(
-     *     { userId: "user456" },
-     *     { userId: "user456", name: "Bob", age: 30 },
-     *     { upsert: true }
-     * );
-     */
-    const replaceOne = async function replaceOne(filter, replacement, 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 (!replacement || typeof replacement !== 'object' || Array.isArray(replacement)) {
-            throw createError(
-                ErrorCodes.INVALID_ARGUMENT,
-                'replacement 必须是对象类型',
-                [{ field: 'replacement', type: 'object.required', message: 'replacement 是必需参数且必须是对象' }]
-            );
-        }
-
-        // 验证 replacement 不包含更新操作符（防止误用）
-        const replacementKeys = Object.keys(replacement);
-        if (replacementKeys.some(key => key.startsWith('$'))) {
-            throw createError(
-                ErrorCodes.INVALID_ARGUMENT,
-                'replacement 不能包含更新操作符（如 $set, $inc 等）',
-                [{ field: 'replacement', type: 'object.invalid', message: 'replaceOne 用于完整替换文档，请使用 updateOne 进行部分更新' }]
-            );
-        }
-
-        // ✅ 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
-        });
-
-        const convertedReplacement = convertObjectIdStrings(replacement, 'document', 0, new WeakSet(), {
-            logger: context.logger,
-            excludeFields: context.autoConvertConfig?.excludeFields,
-            customFieldPatterns: context.autoConvertConfig?.customFieldPatterns,
-            maxDepth: context.autoConvertConfig?.maxDepth
-        });
-
-        // 2. 构建操作上下文
-        const operation = 'replaceOne';
-        const ns = `${databaseName}.${collectionName}`;
-
-        try {
-            // 3. 执行替换操作
-            const result = await nativeCollection.replaceOne(convertedFilter, convertedReplacement, options);
-
-            // 4. 自动失效缓存
-            // ✅ v1.1.6: 修复 upsert 场景的缓存失效问题 - 检查 modifiedCount 或 upsertedId
-            if (cache && (result.modifiedCount > 0 || result.upsertedId)) {
-                try {
-                    // 使用标准命名空间模式删除该集合的所有缓存
-                    const ns = {
-                        iid: instanceId,
-                        type: 'mongodb',
-                        db: databaseName,
-                        collection: collectionName
-                    };
-                    const pattern = CacheFactory.buildNamespacePattern(ns);
-
-                    // 检查是否在事务中
-                    if (isInTransaction(options)) {
-                        // 事务中：调用 Transaction 的 recordInvalidation 方法
-                        const tx = getTransactionFromSession(options.session);
-                        if (tx && typeof tx.recordInvalidation === 'function') {
-                            await tx.recordInvalidation(pattern, {
-                                operation: 'write',
-                                query: filter,
-                                collection: collectionName,
-                                upserted: !!result.upsertedId
-                            });
-                            logger.debug(`[${operation}] 事务中失效缓存: ${ns.db}.${ns.collection}${result.upsertedId ? ' (upsert)' : ''}`);
-                        } else {
-                            const deleted = await cache.delPattern(pattern);
-                            if (deleted > 0) {
-                                logger.debug(`[${operation}] 自动失效缓存: ${ns.db}.${ns.collection}, 删除 ${deleted} 个缓存键${result.upsertedId ? ' (upsert)' : ''}`);
-                            }
-                        }
-                    } else {
-                        // 非事务：直接失效缓存
-                        const deleted = await cache.delPattern(pattern);
-                        if (deleted > 0) {
-                            logger.debug(`[${operation}] 自动失效缓存: ${ns.db}.${ns.collection}, 删除 ${deleted} 个缓存键${result.upsertedId ? ' (upsert)' : ''}`);
-                        }
-                    }
-                } catch (cacheErr) {
-                    // 缓存失效失败不影响写操作
-                    logger.warn(`[${operation}] 缓存失效失败: ${cacheErr.message}`, {
-                        ns: `${databaseName}.${collectionName}`,
-                        error: cacheErr,
-                        upserted: !!result.upsertedId
-                    });
-                }
-            }
-
-            // 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),
-                    replacementKeys: Object.keys(replacement),
-                    matchedCount: result.matchedCount,
-                    modifiedCount: result.modifiedCount,
-                    upserted: result.upsertedId ? true : false,
-                    comment: options.comment
-                });
-            } else {
-                logger.debug(`[${operation}] 操作完成`, {
-                    ns,
-                    duration,
-                    matchedCount: result.matchedCount,
-                    modifiedCount: result.modifiedCount,
-                    upserted: result.upsertedId ? true : false
-                });
-            }
-
-            return result;
-
-        } catch (error) {
-            // 6. 错误处理
-            const duration = Date.now() - startTime;
-
-            logger.error(`[${operation}] 操作失败`, {
-                ns,
-                duration,
-                error: error.message,
-                code: error.code,
-                filterKeys: Object.keys(filter),
-                replacementKeys: Object.keys(replacement)
-            });
-
-            // 识别特定错误类型
-            if (error.code === 11000) {
-                // MongoDB 重复键错误（可能在 upsert 时发生）
-                throw createError(
-                    ErrorCodes.DUPLICATE_KEY,
-                    '替换失败：违反唯一性约束',
-                    [{ field: '_id', message: error.message }],
-                    error
-                );
-            }
-
-            // 其他错误
-            throw createError(
-                ErrorCodes.WRITE_ERROR,
-                `replaceOne 操作失败: ${error.message}`,
-                null,
-                error
-            );
-        }
-    };
-
-    return { replaceOne };
-}
-
-module.exports = { createReplaceOneOps };
-
-