monsqlize 1.3.1 → 2.0.0

package/lib/mongodb/queries/count.js

@@ -1,98 +0,0 @@
-/**
- * count 查询模块
- * @description 提供文档计数功能，使用 MongoDB 原生推荐的 countDocuments() 和 estimatedDocumentCount() 方法
- */
-
-const { convertObjectIdStrings } = require('../../utils/objectid-converter');
-
-/**
- * 创建 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 = {}) => {
-            // ✅ v1.3.0: 自动转换 ObjectId 字符串
-            const convertedQuery = convertObjectIdStrings(query, 'query', 0, new WeakSet(), {
-                logger: context.logger,
-                excludeFields: context.autoConvertConfig?.excludeFields,
-                customFieldPatterns: context.autoConvertConfig?.customFieldPatterns,
-                maxDepth: context.autoConvertConfig?.maxDepth
-            });
-
-            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: convertedQuery }, { $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 = !convertedQuery || Object.keys(convertedQuery).length === 0;
-
-            return run(
-                'count',
-                { query: convertedQuery, ...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(convertedQuery, countOpts);
-                    }
-                }
-            );
-        }
-    };
-}
-
-module.exports = createCountOps;

package/lib/mongodb/queries/distinct.js

@@ -1,77 +0,0 @@
-/**
- * distinct 查询模块
- * @description 提供字段去重查询功能，使用 MongoDB 原生 distinct() 方法
- */
-
-const { convertObjectIdStrings } = require('../../utils/objectid-converter');
-
-/**
- * 创建 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 = {}) => {
-            // ✅ v1.3.0: 自动转换 ObjectId 字符串
-            const convertedQuery = convertObjectIdStrings(query, 'query', 0, new WeakSet(), {
-                logger: context.logger,
-                excludeFields: context.autoConvertConfig?.excludeFields,
-                customFieldPatterns: context.autoConvertConfig?.customFieldPatterns,
-                maxDepth: context.autoConvertConfig?.maxDepth
-            });
-            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 (convertedQuery && Object.keys(convertedQuery).length > 0) {
-                    pipeline.push({ $match: convertedQuery });
-                }
-                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: convertedQuery, ...options },
-                () => collection.distinct(field, convertedQuery, driverOpts)
-            );
-        }
-    };
-}
-
-module.exports = createDistinctOps;

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

@@ -1,192 +0,0 @@
-/**
- * findAndCount 查询操作模块
- * @description 便利方法：同时返回数据和总数
- */
-
-const { createError, ErrorCodes } = require('../../errors');
-const { convertObjectIdStrings } = require('../../utils/objectid-converter');
-
-/**
- * 创建 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 = {};
-        }
-
-        // ✅ v1.3.0: 自动转换 ObjectId 字符串
-        const convertedQuery = convertObjectIdStrings(query, 'query', 0, new WeakSet(), {
-            logger: context.logger,
-            excludeFields: context.autoConvertConfig?.excludeFields,
-            customFieldPatterns: context.autoConvertConfig?.customFieldPatterns,
-            maxDepth: context.autoConvertConfig?.maxDepth
-        });
-
-        // 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: convertedQuery, 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
-                    });
-                    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(convertedQuery, findOptions).toArray(),
-                collection.countDocuments(convertedQuery, 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,
-                    db: effectiveDbName,
-                    collection: collection.collectionName,
-                    dataCount: data.length,
-                    total,
-                    query: mongoSlowLogShaper?.sanitize ? mongoSlowLogShaper.sanitize(query) : query,
-                    projection,
-                    sort,
-                    limit,
-                    skip,
-                    comment
-                };
-                logger?.warn?.('🐌 Slow query: findAndCount', meta);
-                emit?.('slow-query', meta);
-            } catch (_) {
-                // 忽略日志错误
-            }
-        }
-
-        // 10. 日志记录
-        logger?.debug?.('[findAndCount] 查询完成', {
-            ns: `${effectiveDbName}.${collection.collectionName}`,
-            duration,
-            dataCount: data.length,
-            total
-        });
-
-        return result;
-    };
-
-    return { findAndCount };
-}
-
-module.exports = { createFindAndCountOps };
-

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

@@ -1,235 +0,0 @@
-/**
- * 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,
-                    db: effectiveDbName,
-                    collection: collection.collectionName,
-                    idsCount: ids.length,
-                    uniqueCount: uniqueIds.length,
-                    resultCount: results.length,
-                    query: mongoSlowLogShaper?.sanitize ? mongoSlowLogShaper.sanitize(query) : query,
-                    projection,
-                    sort,
-                    comment
-                };
-                logger?.warn?.('🐌 Slow query: findByIds', meta);
-                emit?.('slow-query', meta);
-            } catch (_) {
-                // 忽略日志错误
-            }
-        }
-
-        // 12. 日志记录
-        logger?.debug?.('[findByIds] 查询完成', {
-            ns: `${effectiveDbName}.${collection.collectionName}`,
-            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 };
-