monsqlize 1.0.0

package/lib/mongodb/queries/find.js

@@ -0,0 +1,161 @@
+/**
+ * find 查询模块
+ * @description 提供多条记录查询功能，支持投影、排序、分页、缓存和流式返回
+ */
+
+const { normalizeProjection, normalizeSort } = require('../../common/normalize');
+const { FindChain } = require('./chain');
+
+/**
+ * 创建 find 查询操作
+ * @param {Object} context - 上下文对象
+ * @param {Object} context.collection - MongoDB 集合实例
+ * @param {Object} context.defaults - 默认配置
+ * @param {Function} context.run - 缓存执行器
+ * @param {string} context.instanceId - 实例ID
+ * @param {string} context.effectiveDbName - 数据库名
+ * @param {Object} context.logger - 日志器
+ * @param {Function} context.emit - 事件发射器
+ * @param {Object} context.mongoSlowLogShaper - 慢查询日志格式化器
+ * @returns {Object} 包含 find 和 stream 方法的对象
+ */
+function createFindOps(context) {
+    const {
+        collection,
+        defaults,
+        run,
+        instanceId,
+        effectiveDbName,
+        logger,
+        emit,
+        mongoSlowLogShaper
+    } = context;
+
+    return {
+        /**
+         * 查询多条记录
+         * @param {Object} [query={}] - 查询条件，使用 MongoDB 查询语法
+         * @param {Object} [options={}] - 查询选项 { projection, sort, limit, skip, cache, maxTimeMS, stream, explain }
+         * @param {Object|Array} [options.projection] - 字段投影配置
+         * @param {Object} [options.sort] - 排序配置
+         * @param {number} [options.limit] - 限制返回数量
+         * @param {number} [options.skip] - 跳过记录数
+         * @param {number} [options.cache] - 缓存时间（毫秒）
+         * @param {number} [options.maxTimeMS] - 查询超时时间（毫秒）
+         * @param {boolean} [options.stream] - 是否使用流式返回
+         * @param {number} [options.batchSize] - 批处理大小
+         * @param {boolean|string} [options.explain] - 是否返回查询执行计划，可选值：true/'queryPlanner'/'executionStats'/'allPlansExecution'
+         * @param {string} [options.hint] - 索引提示
+         * @param {Object} [options.collation] - 排序规则
+         * @param {string} [options.comment] - 查询注释
+         * @returns {Promise<Array>|ReadableStream|FindChain} 记录数组或可读流（当 stream: true 时）；当 explain=true 时返回执行计划；默认返回 FindChain 实例支持链式调用
+         */
+        find: (query = {}, options = {}) => {
+            // 如果没有提供 options 或 options 为空对象，返回 FindChain 以支持完整的链式调用
+            const hasOptions = options && Object.keys(options).length > 0;
+
+            if (!hasOptions) {
+                // 返回 FindChain 实例，支持 .limit().skip().sort() 等链式调用
+                return new FindChain(context, query, {});
+            }
+
+            // 如果提供了 options，执行原有逻辑（向后兼容）
+            options.projection = normalizeProjection(options.projection);
+            const {
+                projection,
+                limit = defaults.findLimit,
+                skip,
+                maxTimeMS = defaults.maxTimeMS,
+                stream = false,
+                batchSize,
+                explain,
+                comment
+            } = options;
+            const sort = normalizeSort(options.sort);
+
+            const driverOpts = { projection, sort, skip, maxTimeMS, ...(options.hint ? { hint: options.hint } : {}), ...(options.collation ? { collation: options.collation } : {}) };
+            if (limit !== undefined) driverOpts.limit = limit;
+            if (batchSize !== undefined) driverOpts.batchSize = batchSize;
+            if (comment) driverOpts.comment = comment;
+
+            // 如果启用 explain，直接返回执行计划（不缓存）
+            if (explain) {
+                const verbosity = typeof explain === 'string' ? explain : 'queryPlanner';
+                const cursor = collection.find(query, driverOpts);
+                return cursor.explain(verbosity);
+            }
+
+            // 如果启用流式返回，直接返回 MongoDB 游标流
+            if (stream) {
+                const cursor = collection.find(query, driverOpts);
+                const readableStream = cursor.stream();
+
+                // 添加慢查询日志支持
+                const startTime = Date.now();
+                let docCount = 0;
+
+                readableStream.on('data', () => {
+                    docCount++;
+                });
+
+                readableStream.on('end', () => {
+                    const durationMs = Date.now() - startTime;
+                    const slowQueryMs = defaults?.slowQueryMs || 500;
+
+                    if (durationMs >= slowQueryMs) {
+                        try {
+                            const meta = {
+                                op: 'stream',
+                                durationMs,
+                                docCount,
+                                iid: instanceId,
+                                type: context.type,
+                                db: effectiveDbName,
+                                collection: collection.collectionName,
+                                query: mongoSlowLogShaper?.sanitize ? mongoSlowLogShaper.sanitize(query) : query,
+                                limit,
+                            };
+                            logger?.warn?.('🐌 Slow stream query', meta);
+                            emit?.('slow-query', meta);
+                        } catch (_) { }
+                    }
+                });
+
+                return readableStream;
+            }
+
+            // 执行查询的 Promise
+            const resultPromise = run(
+                'find',
+                { query, ...options },
+                async () => collection.find(query, driverOpts).toArray()
+            );
+
+            // 添加 explain 方法支持链式调用（与原生 MongoDB 一致）
+            resultPromise.explain = async (verbosity = 'queryPlanner') => {
+                const cursor = collection.find(query, driverOpts);
+                return cursor.explain(verbosity);
+            };
+
+            return resultPromise;
+        },
+
+        /**
+         * 流式查询多条记录（语法糖方法）
+         * @description 这是 find(query, {...options, stream: true}) 的便捷方法
+         * @param {Object} [query={}] - 查询条件
+         * @param {Object} [options={}] - { projection, sort, limit, skip, maxTimeMS, batchSize }
+         * @returns {ReadableStream} MongoDB 游标流
+         */
+        stream: (query = {}, options = {}) => {
+            // 注意：这里需要通过回调获取完整的 collection 方法对象
+            // 在主文件中会重写这个方法
+            return context.getCollectionMethods().find(query, {
+                ...options,
+                stream: true
+            });
+        }
+    };
+}
+
+module.exports = createFindOps;

package/lib/mongodb/queries/index.js

@@ -0,0 +1,49 @@
+/**
+ * 查询模块统一导出
+ * @module queries
+ */
+
+const { createFindPage, bookmarkKey, buildKeyDimsAuto } = require('./find-page');
+
+/**
+ * 创建 findPage 操作（工厂函数包装）
+ * @param {Object} context - 上下文对象
+ * @returns {Object} 包含 findPage 方法
+ */
+function createFindPageOps(context) {
+    const { collection, getCache, instanceId, type, effectiveDbName, defaults, logger, run } = context;
+
+    // 预构建 ns 字符串，确保书签键稳定
+    const nsStr = `${instanceId}:${type}:${effectiveDbName}:${collection.collectionName}`;
+
+    const findPageImpl = createFindPage({
+        collection,
+        getCache,  // 直接传递 getCache 回调
+        getNamespace: () => ({ ns: nsStr, db: effectiveDbName, coll: collection.collectionName }),
+        defaults,
+        logger,
+        databaseName: effectiveDbName,
+        collectionName: collection.collectionName,
+        run
+    });
+
+    return {
+        findPage: async (options = {}) => findPageImpl(options)
+    };
+}
+
+module.exports = {
+    createFindOps: require('./find'),
+    createFindOneOps: require('./find-one'),
+    createFindOneByIdOps: require('./find-one-by-id').createFindOneByIdOps,  // findOneById 便利方法
+    createFindByIdsOps: require('./find-by-ids').createFindByIdsOps,  // findByIds 便利方法
+    createFindAndCountOps: require('./find-and-count').createFindAndCountOps,  // 新增：findAndCount 便利方法
+    createCountOps: require('./count'),
+    createAggregateOps: require('./aggregate'),
+    createDistinctOps: require('./distinct'),
+    createFindPageOps,  // 新增工厂函数
+    // 导出原始函数和辅助函数供 bookmark 模块使用
+    createFindPage,
+    bookmarkKey,
+    buildKeyDimsAuto
+};

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

@@ -0,0 +1,181 @@
+/**
+ * deleteMany 操作实现
+ * 删除所有匹配的文档
+ */
+
+const { createError, ErrorCodes } = require("../../errors");
+const CacheFactory = require("../../cache");
+const { isInTransaction, getTransactionFromSession } = require("../common/transaction-aware");
+
+/**
+ * 创建 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 是必需参数且必须是对象" }]
+            );
+        }
+
+        // 2. 警告：空 filter 会删除所有文档
+        if (Object.keys(filter).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(filter, options);
+
+            // 5. 自动失效缓存（如果有文档被删除）
+            if (cache && result.deletedCount > 0) {
+                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') {
+                            // 🚀 传递 metadata 支持文档级别锁
+                            await tx.recordInvalidation(pattern, {
+                                operation: 'write',
+                                query: filter || {},
+                                collection: collectionName
+                            });
+                            logger.debug(`[${operation}] 事务中失效缓存: ${ns.db}.${ns.collection}`);
+                        } else {
+                            const deleted = await cache.delPattern(pattern);
+                            if (deleted > 0) {
+                                logger.debug(`[${operation}] 自动失效缓存: ${ns.db}.${ns.collection}, 删除 ${deleted} 个缓存键`);
+                            }
+                        }
+                    } else {
+                        // 非事务：直接失效缓存
+                        const deleted = await cache.delPattern(pattern);
+                        if (deleted > 0) {
+                            logger.debug(`[${operation}] 自动失效缓存: ${ns.db}.${ns.collection}, 删除 ${deleted} 个缓存键`);
+                        }
+                    }
+                } 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

@@ -0,0 +1,173 @@
+/**
+ * deleteOne 操作实现
+ * 删除单个匹配的文档
+ */
+
+const { createError, ErrorCodes } = require("../../errors");
+const CacheFactory = require("../../cache");
+const { isInTransaction, getTransactionFromSession } = require("../common/transaction-aware");
+
+/**
+ * 创建 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 是必需参数且必须是对象" }]
+            );
+        }
+
+        // 2. 构建操作上下文
+        const operation = "deleteOne";
+        const ns = `${databaseName}.${collectionName}`;
+
+        try {
+            // 3. 执行删除操作
+            const result = await nativeCollection.deleteOne(filter, options);
+
+            // 4. 自动失效缓存（如果有文档被删除）
+            if (cache && result.deletedCount > 0) {
+                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') {
+                            // 🚀 传递 metadata 支持文档级别锁
+                            await tx.recordInvalidation(pattern, {
+                                operation: 'write',
+                                query: filter || {},
+                                collection: collectionName
+                            });
+                            logger.debug(`[${operation}] 事务中失效缓存: ${ns.db}.${ns.collection}`);
+                        } else {
+                            const deleted = await cache.delPattern(pattern);
+                            if (deleted > 0) {
+                                logger.debug(`[${operation}] 自动失效缓存: ${ns.db}.${ns.collection}, 删除 ${deleted} 个缓存键`);
+                            }
+                        }
+                    } else {
+                        // 非事务：直接失效缓存
+                        const deleted = await cache.delPattern(pattern);
+                        if (deleted > 0) {
+                            logger.debug(`[${operation}] 自动失效缓存: ${ns.db}.${ns.collection}, 删除 ${deleted} 个缓存键`);
+                        }
+                    }
+                } 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 };
+