monsqlize 1.0.0

package/lib/mongodb/queries/count.js

@@ -0,0 +1,88 @@
+/**
+ * count 查询模块
+ * @description 提供文档计数功能，使用 MongoDB 原生推荐的 countDocuments() 和 estimatedDocumentCount() 方法
+ */
+
+/**
+ * 创建 count 查询操作
+ * @param {Object} context - 上下文对象
+ * @returns {Object} 包含 count 方法的对象
+ */
+function createCountOps(context) {
+    const { collection, defaults, run, effectiveDbName } = context;
+
+    return {
+        /**
+         * 统计文档数量
+         * @description 根据查询条件统计匹配的文档数量。空查询时使用 estimatedDocumentCount（基于元数据，快速），有查询条件时使用 countDocuments（精确统计）
+         * @param {Object} [query={}] - 查询条件，使用 MongoDB 查询语法，空对象表示统计所有文档
+         * @param {Object} [options={}] - 查询选项配置对象
+         * @param {number} [options.cache=0] - 缓存时间（毫秒），0表示不缓存，>0时结果将被缓存指定时间
+         * @param {number} [options.maxTimeMS] - 查询超时时间（毫秒），防止长时间查询阻塞
+         * @param {boolean|string} [options.explain] - 是否返回查询执行计划，可选值：true/'queryPlanner'/'executionStats'/'allPlansExecution'
+         * @param {string} [options.hint] - 索引提示，指定使用的索引名称或索引规范（仅 countDocuments）
+         * @param {Object} [options.collation] - 排序规则配置（仅 countDocuments）
+         * @param {number} [options.skip] - 跳过的文档数量（仅 countDocuments）
+         * @param {number} [options.limit] - 限制统计的文档数量（仅 countDocuments）
+         * @param {string} [options.comment] - 查询注释，用于日志和性能分析
+         * @returns {Promise<number>} 匹配的文档数量；当 explain=true 时返回执行计划对象
+         */
+        count: async (query = {}, options = {}) => {
+            const { maxTimeMS = defaults.maxTimeMS, explain, comment } = options;
+
+            // 如果启用 explain，直接返回查询执行计划（不缓存）
+            if (explain) {
+                const verbosity = typeof explain === "string" ? explain : "queryPlanner";
+                const isEmptyQuery = !query || Object.keys(query).length === 0;
+
+                if (isEmptyQuery) {
+                    // estimatedDocumentCount 没有 explain，返回集合统计信息
+                    return {
+                        queryPlanner: { plannerVersion: 1, namespace: `${effectiveDbName}.${collection.collectionName}` },
+                        executionStats: { executionSuccess: true, estimatedCount: true },
+                        command: { estimatedDocumentCount: collection.collectionName }
+                    };
+                } else {
+                    // countDocuments 通过聚合管道实现，使用 aggregate 获取 explain
+                    const pipeline = [{ $match: query }, { $count: "total" }];
+                    const aggOpts = {
+                        maxTimeMS,
+                        ...(options.hint && { hint: options.hint }),
+                        ...(options.collation && { collation: options.collation })
+                    };
+                    if (comment) aggOpts.comment = comment;
+                    return await collection.aggregate(pipeline, aggOpts).explain(verbosity);
+                }
+            }
+
+            // 性能优化：判断是否为空查询
+            const isEmptyQuery = !query || Object.keys(query).length === 0;
+
+            return run(
+                "count",
+                { query, ...options },
+                () => {
+                    if (isEmptyQuery) {
+                        // 空查询使用 estimatedDocumentCount（快速，基于集合元数据）
+                        const estOpts = { maxTimeMS };
+                        if (comment) estOpts.comment = comment;
+                        return collection.estimatedDocumentCount(estOpts);
+                    } else {
+                        // 有查询条件使用 countDocuments（精确统计）
+                        const countOpts = {
+                            maxTimeMS,
+                            ...(options.hint && { hint: options.hint }),
+                            ...(options.collation && { collation: options.collation }),
+                            ...(options.skip && { skip: options.skip }),
+                            ...(options.limit && { limit: options.limit })
+                        };
+                        if (comment) countOpts.comment = comment;
+                        return collection.countDocuments(query, countOpts);
+                    }
+                }
+            );
+        }
+    };
+}
+
+module.exports = createCountOps;

package/lib/mongodb/queries/distinct.js

@@ -0,0 +1,68 @@
+/**
+ * distinct 查询模块
+ * @description 提供字段去重查询功能，使用 MongoDB 原生 distinct() 方法
+ */
+
+/**
+ * 创建 distinct 查询操作
+ * @param {Object} context - 上下文对象
+ * @returns {Object} 包含 distinct 方法的对象
+ */
+function createDistinctOps(context) {
+    const { collection, defaults, run } = context;
+
+    return {
+        /**
+         * 字段去重查询
+         * @description 对指定字段进行去重查询，返回该字段的所有唯一值数组。支持嵌套字段和数组字段（自动展开去重）
+         * @param {string} field - 要去重的字段名，支持嵌套字段（如 'user.name'、'address.city'）
+         * @param {Object} [query={}] - 查询条件，只对匹配的文档进行去重，使用 MongoDB 查询语法
+         * @param {Object} [options={}] - 查询选项配置对象
+         * @param {number} [options.maxTimeMS] - 查询超时时间（毫秒），防止长时间查询阻塞
+         * @param {Object} [options.collation] - 排序规则配置，用于字符串比较和去重（如不区分大小写）
+         * @param {string} [options.comment] - 查询注释，用于日志和性能分析
+         * @param {number} [options.cache=0] - 缓存时间（毫秒），0表示不缓存，>0时结果将被缓存指定时间
+         * @param {boolean|string} [options.explain] - 是否返回查询执行计划，可选值：true/'queryPlanner'/'executionStats'/'allPlansExecution'
+         * @returns {Promise<Array>} 返回去重后的值数组；当 explain=true 时返回执行计划对象
+         */
+        distinct: async (field, query = {}, options = {}) => {
+            const {
+                maxTimeMS = defaults.maxTimeMS,
+                collation,
+                comment,
+                explain
+            } = options;
+
+            // 构建驱动选项
+            const driverOpts = { maxTimeMS };
+            if (collation) driverOpts.collation = collation;
+            if (comment) driverOpts.comment = comment;
+
+            // 如果启用 explain，通过 aggregate 模拟 distinct 并返回执行计划
+            // 注意：MongoDB 原生 distinct 命令不支持 explain，需要通过聚合管道模拟
+            if (explain) {
+                const verbosity = typeof explain === "string" ? explain : "queryPlanner";
+                // distinct 命令通过聚合管道模拟：$match + $group
+                const pipeline = [];
+                if (query && Object.keys(query).length > 0) {
+                    pipeline.push({ $match: query });
+                }
+                pipeline.push({ $group: { _id: `$${field}` } });
+
+                const aggOpts = { maxTimeMS };
+                if (collation) aggOpts.collation = collation;
+                if (comment) aggOpts.comment = comment;
+
+                return await collection.aggregate(pipeline, aggOpts).explain(verbosity);
+            }
+
+            return run(
+                "distinct",
+                { field, query, ...options },
+                () => collection.distinct(field, query, driverOpts)
+            );
+        }
+    };
+}
+
+module.exports = createDistinctOps;

package/lib/mongodb/queries/find-and-count.js

@@ -0,0 +1,183 @@
+/**
+ * findAndCount 查询操作模块
+ * @description 便利方法：同时返回数据和总数
+ */
+
+const { createError, ErrorCodes } = require('../../errors');
+
+/**
+ * 创建 findAndCount 操作
+ * @param {Object} context - 上下文对象
+ * @returns {Function} findAndCount 方法
+ */
+function createFindAndCountOps(context) {
+    const {
+        collection,
+        defaults,
+        instanceId,
+        effectiveDbName,
+        logger,
+        emit,
+        mongoSlowLogShaper,
+        cache,
+        type
+    } = context;
+
+    /**
+     * 查询数据并返回总数（同时执行）
+     * @param {Object} [query={}] - 查询条件
+     * @param {Object} [options={}] - 查询选项
+     * @param {Object} [options.projection] - 字段投影
+     * @param {Object} [options.sort] - 排序方式
+     * @param {number} [options.limit] - 限制返回数量
+     * @param {number} [options.skip] - 跳过数量
+     * @param {number} [options.cache] - 缓存时间（毫秒）
+     * @param {number} [options.maxTimeMS] - 查询超时（毫秒）
+     * @param {string} [options.comment] - 查询注释
+     * @returns {Promise<Object>} { data, total }
+     *
+     * @example
+     * // 基础用法
+     * const { data, total } = await collection('users').findAndCount(
+     *   { status: 'active' },
+     *   { limit: 10, skip: 0 }
+     * );
+     *
+     * @example
+     * // 分页查询
+     * const page = 1;
+     * const pageSize = 20;
+     * const { data, total } = await collection('users').findAndCount(
+     *   { role: 'user' },
+     *   { limit: pageSize, skip: (page - 1) * pageSize }
+     * );
+     * const totalPages = Math.ceil(total / pageSize);
+     */
+    const findAndCount = async function findAndCount(query = {}, options = {}) {
+        const startTime = Date.now();
+
+        // 1. 参数验证和归一化
+        if (query !== null && typeof query !== 'object' || Array.isArray(query)) {
+            throw createError(
+                ErrorCodes.INVALID_ARGUMENT,
+                'query 必须是对象',
+                [{ field: 'query', type: 'type', message: 'query 必须是对象', received: typeof query }]
+            );
+        }
+
+        // 将 null 转为空对象
+        if (query === null) {
+            query = {};
+        }
+
+        // 2. 提取选项
+        const projection = options.projection;
+        const sort = options.sort;
+        const limit = options.limit; // 不使用默认值，未指定时查询所有
+        const skip = options.skip || 0;
+        const cacheTime = options.cache !== undefined ? options.cache : defaults.cache;
+        const maxTimeMS = options.maxTimeMS !== undefined ? options.maxTimeMS : defaults.maxTimeMS;
+        const comment = options.comment;
+
+        // 3. 缓存键（包含 query, projection, sort, limit, skip）
+        const cacheKey = cache ? `${instanceId}:${type}:${effectiveDbName}:${collection.collectionName}:findAndCount:${JSON.stringify({ query, projection, sort, limit, skip })}` : null;
+
+        // 4. 检查缓存
+        if (cache && cacheTime > 0) {
+            try {
+                const cached = await cache.get(cacheKey);
+                // 必须检查 !== null 和 !== undefined，因为 undefined 也会被缓存
+                if (cached !== null && cached !== undefined) {
+                    logger?.debug?.('[findAndCount] 缓存命中', {
+                        ns: `${effectiveDbName}.${collection.collectionName}`,
+                        query: query
+                    });
+                    return cached;
+                }
+            } catch (cacheError) {
+                logger?.warn?.('[findAndCount] 缓存读取失败', { error: cacheError.message });
+            }
+        }
+
+        // 5. 构建查询选项
+        const findOptions = { maxTimeMS };
+        if (projection) findOptions.projection = projection;
+        if (sort) findOptions.sort = sort;
+        // limit: undefined/null 表示不限制，0 表示返回0条，其他数字表示限制数量
+        if (limit !== undefined && limit !== null) {
+            findOptions.limit = limit;
+        }
+        if (skip) findOptions.skip = skip;
+        if (comment) findOptions.comment = comment;
+
+        const countOptions = { maxTimeMS };
+        if (comment) countOptions.comment = comment;
+
+        // 6. 并行执行查询和计数
+        let data, total;
+        try {
+            [data, total] = await Promise.all([
+                collection.find(query, findOptions).toArray(),
+                collection.countDocuments(query, countOptions)
+            ]);
+        } catch (error) {
+            throw error;
+        }
+
+        // 7. 构建结果
+        const result = { data, total };
+
+        // 8. 写入缓存
+        if (cache && cacheTime > 0) {
+            try {
+                await cache.set(cacheKey, result, cacheTime);
+            } catch (cacheError) {
+                logger?.warn?.('[findAndCount] 缓存写入失败', { error: cacheError.message });
+            }
+        }
+
+        // 9. 慢查询日志
+        const duration = Date.now() - startTime;
+        const slowQueryMs = defaults?.slowQueryMs || 1000;
+
+        if (duration >= slowQueryMs) {
+            try {
+                const meta = {
+                    operation: 'findAndCount',
+                    durationMs: duration,
+                    iid: instanceId,
+                    type: type,
+                    db: effectiveDbName,
+                    collection: collection.collectionName,
+                    dataCount: data.length,
+                    total: total,
+                    query: mongoSlowLogShaper?.sanitize ? mongoSlowLogShaper.sanitize(query) : query,
+                    projection: projection,
+                    sort: sort,
+                    limit: limit,
+                    skip: skip,
+                    comment: comment
+                };
+                logger?.warn?.('🐌 Slow query: findAndCount', meta);
+                emit?.('slow-query', meta);
+            } catch (_) {
+                // 忽略日志错误
+            }
+        }
+
+        // 10. 日志记录
+        logger?.debug?.('[findAndCount] 查询完成', {
+            ns: `${effectiveDbName}.${collection.collectionName}`,
+            duration: duration,
+            dataCount: data.length,
+            total: total
+        });
+
+        return result;
+    };
+
+    return { findAndCount };
+}
+
+module.exports = { createFindAndCountOps };
+

package/lib/mongodb/queries/find-by-ids.js

@@ -0,0 +1,235 @@
+/**
+ * findByIds 查询操作模块
+ * @description 便利方法：批量通过 _id 数组查询多个文档
+ */
+
+const { ObjectId } = require('mongodb');
+const { createError, ErrorCodes } = require('../../errors');
+
+/**
+ * 创建 findByIds 操作
+ * @param {Object} context - 上下文对象
+ * @returns {Function} findByIds 方法
+ */
+function createFindByIdsOps(context) {
+    const {
+        collection,
+        defaults,
+        instanceId,
+        effectiveDbName,
+        logger,
+        emit,
+        mongoSlowLogShaper,
+        cache,
+        type
+    } = context;
+
+    /**
+     * 批量通过 _id 查询多个文档
+     * @param {Array<string|ObjectId>} ids - _id 数组（支持字符串和 ObjectId）
+     * @param {Object} [options={}] - 查询选项
+     * @param {Object} [options.projection] - 字段投影
+     * @param {Object} [options.sort] - 排序方式
+     * @param {number} [options.cache] - 缓存时间（毫秒）
+     * @param {number} [options.maxTimeMS] - 查询超时（毫秒）
+     * @param {string} [options.comment] - 查询注释
+     * @param {boolean} [options.preserveOrder=false] - 是否保持 ids 数组的顺序
+     * @returns {Promise<Array>} 文档数组
+     *
+     * @example
+     * // 基础用法
+     * const users = await collection('users').findByIds([
+     *   '507f1f77bcf86cd799439011',
+     *   '507f1f77bcf86cd799439012'
+     * ]);
+     *
+     * @example
+     * // 带选项
+     * const users = await collection('users').findByIds(
+     *   ['507f1f77bcf86cd799439011', '507f1f77bcf86cd799439012'],
+     *   {
+     *     projection: { name: 1, email: 1 },
+     *     preserveOrder: true
+     *   }
+     * );
+     */
+    const findByIds = async function findByIds(ids, options = {}) {
+        const startTime = Date.now();
+
+        // 1. 参数验证
+        if (!Array.isArray(ids)) {
+            throw createError(
+                ErrorCodes.INVALID_ARGUMENT,
+                'ids 必须是数组',
+                [{ field: 'ids', type: 'type', message: 'ids 必须是数组', received: typeof ids }]
+            );
+        }
+
+        if (ids.length === 0) {
+            // 空数组直接返回空结果
+            return [];
+        }
+
+        // 2. 转换所有 ID 为 ObjectId
+        const objectIds = [];
+        const invalidIds = [];
+
+        for (let i = 0; i < ids.length; i++) {
+            const id = ids[i];
+
+            if (id instanceof ObjectId) {
+                objectIds.push(id);
+            } else if (typeof id === 'string') {
+                // 验证字符串是否是有效的 ObjectId 格式（24 个十六进制字符）
+                if (!/^[0-9a-fA-F]{24}$/.test(id)) {
+                    invalidIds.push({ index: i, value: id });
+                } else {
+                    objectIds.push(new ObjectId(id));
+                }
+            } else {
+                // 拒绝其他类型（数字、对象等）
+                invalidIds.push({ index: i, value: id, type: typeof id });
+            }
+        }
+
+        // 如果有无效 ID，抛出错误
+        if (invalidIds.length > 0) {
+            throw createError(
+                ErrorCodes.INVALID_ARGUMENT,
+                `ids 数组包含 ${invalidIds.length} 个无效 ID`,
+                invalidIds.map(item => ({
+                    field: `ids[${item.index}]`,
+                    type: 'format',
+                    message: '无效的 ObjectId 格式',
+                    received: item.value
+                }))
+            );
+        }
+
+        // 3. 去重（避免重复查询）
+        const uniqueIds = [...new Set(objectIds.map(id => id.toString()))].map(id => new ObjectId(id));
+
+        // 4. 提取选项
+        const projection = options.projection;
+        const sort = options.sort;
+        const cacheTime = options.cache !== undefined ? options.cache : defaults.cache;
+        const maxTimeMS = options.maxTimeMS !== undefined ? options.maxTimeMS : defaults.maxTimeMS;
+        const comment = options.comment;
+        const preserveOrder = options.preserveOrder === true;
+
+        // 5. 构建查询
+        const query = { _id: { $in: uniqueIds } };
+
+        // 6. 缓存键
+        const cacheKey = cache ? `${instanceId}:${type}:${effectiveDbName}:${collection.collectionName}:findByIds:${JSON.stringify({ ids: uniqueIds.map(id => id.toString()), projection, sort })}` : null;
+
+        // 7. 检查缓存
+        if (cache && cacheTime > 0) {
+            try {
+                const cached = await cache.get(cacheKey);
+                if (cached != null) {
+                    logger?.debug?.('[findByIds] 缓存命中', {
+                        ns: `${effectiveDbName}.${collection.collectionName}`,
+                        idsCount: ids.length,
+                        uniqueCount: uniqueIds.length
+                    });
+
+                    // 如果需要保持顺序，重新排序结果
+                    if (preserveOrder) {
+                        return reorderResults(cached, objectIds);
+                    }
+                    return cached;
+                }
+            } catch (cacheError) {
+                logger?.warn?.('[findByIds] 缓存读取失败', { error: cacheError.message });
+            }
+        }
+
+        // 8. 构建查询选项
+        const findOptions = { maxTimeMS };
+        if (projection) findOptions.projection = projection;
+        if (sort) findOptions.sort = sort;
+        if (comment) findOptions.comment = comment;
+
+        // 9. 执行查询
+        let results;
+        try {
+            results = await collection.find(query, findOptions).toArray();
+        } catch (error) {
+            throw error;
+        }
+
+        // 10. 写入缓存
+        if (cache && cacheTime > 0 && results) {
+            try {
+                await cache.set(cacheKey, results, cacheTime);
+            } catch (cacheError) {
+                logger?.warn?.('[findByIds] 缓存写入失败', { error: cacheError.message });
+            }
+        }
+
+        // 11. 慢查询日志
+        const duration = Date.now() - startTime;
+        const slowQueryMs = defaults?.slowQueryMs || 1000;
+
+        if (duration >= slowQueryMs) {
+            try {
+                const meta = {
+                    operation: 'findByIds',
+                    durationMs: duration,
+                    iid: instanceId,
+                    type: type,
+                    db: effectiveDbName,
+                    collection: collection.collectionName,
+                    idsCount: ids.length,
+                    uniqueCount: uniqueIds.length,
+                    resultCount: results.length,
+                    query: mongoSlowLogShaper?.sanitize ? mongoSlowLogShaper.sanitize(query) : query,
+                    projection: projection,
+                    sort: sort,
+                    comment: comment
+                };
+                logger?.warn?.('🐌 Slow query: findByIds', meta);
+                emit?.('slow-query', meta);
+            } catch (_) {
+                // 忽略日志错误
+            }
+        }
+
+        // 12. 日志记录
+        logger?.debug?.('[findByIds] 查询完成', {
+            ns: `${effectiveDbName}.${collection.collectionName}`,
+            duration: duration,
+            idsCount: ids.length,
+            uniqueCount: uniqueIds.length,
+            resultCount: results.length
+        });
+
+        // 13. 如果需要保持顺序，重新排序结果
+        if (preserveOrder) {
+            return reorderResults(results, objectIds);
+        }
+
+        return results;
+    };
+
+    /**
+     * 根据原始 ID 顺序重新排序结果
+     * @param {Array} results - 查询结果
+     * @param {Array<ObjectId>} orderedIds - 原始 ID 顺序
+     * @returns {Array} 排序后的结果
+     */
+    function reorderResults(results, orderedIds) {
+        const resultMap = new Map();
+        results.forEach(doc => {
+            resultMap.set(doc._id.toString(), doc);
+        });
+
+        return orderedIds.map(id => resultMap.get(id.toString())).filter(doc => doc !== undefined);
+    }
+
+    return { findByIds };
+}
+
+module.exports = { createFindByIdsOps };
+