monsqlize 1.3.0 → 2.0.0

package/lib/mongodb/management/validation-ops.js

@@ -1,268 +0,0 @@
-/**
- * 集合验证相关操作方法工厂函数
- * 提供 Schema 验证规则管理
- * @module mongodb/management/validation-ops
- */
-
-const { createValidationError } = require('../../errors');
-
-/**
- * 创建验证操作方法
- * @param {Object} context - 上下文对象
- * @param {Object} context.db - MongoDB 数据库实例
- * @param {Object} context.collection - MongoDB 集合实例
- * @param {Object} context.logger - 日志记录器
- * @returns {Object} 验证操作方法集合
- */
-function createValidationOps(context) {
-    const { db, collection, logger } = context;
-
-    return {
-        /**
-         * 设置集合的验证规则
-         * @param {Object} validator - 验证规则（JSON Schema 或查询表达式）
-         * @param {Object} [options] - 选项
-         * @param {string} [options.validationLevel] - 验证级别
-         * @param {string} [options.validationAction] - 验证失败时的行为
-         * @returns {Promise<Object>} 设置结果
-         *
-         * @example
-         * // 使用 JSON Schema 验证
-         * await collection.setValidator({
-         *   $jsonSchema: {
-         *     bsonType: 'object',
-         *     required: ['name', 'email'],
-         *     properties: {
-         *       name: {
-         *         bsonType: 'string',
-         *         description: 'must be a string and is required'
-         *       },
-         *       email: {
-         *         bsonType: 'string',
-         *         pattern: '^.+@.+$',
-         *         description: 'must be a valid email'
-         *       },
-         *       age: {
-         *         bsonType: 'int',
-         *         minimum: 0,
-         *         maximum: 120,
-         *         description: 'must be an integer between 0 and 120'
-         *       }
-         *     }
-         *   }
-         * });
-         *
-         * // 使用查询表达式验证
-         * await collection.setValidator({
-         *   $and: [
-         *     { name: { $type: 'string' } },
-         *     { email: { $regex: /@/ } }
-         *   ]
-         * });
-         *
-         * // 同时设置验证级别和行为
-         * await collection.setValidator({
-         *   $jsonSchema: { /* ... * / }
-         * }, {
-         *   validationLevel: 'moderate',
-         *   validationAction: 'warn'
-         * });
-         */
-        async setValidator(validator, options = {}) {
-            try {
-                if (!validator || typeof validator !== 'object') {
-                    throw createValidationError(
-                        'Validator must be an object',
-                        'INVALID_VALIDATOR'
-                    );
-                }
-
-                const command = {
-                    collMod: collection.collectionName,
-                    validator
-                };
-
-                if (options.validationLevel) {
-                    command.validationLevel = options.validationLevel;
-                }
-
-                if (options.validationAction) {
-                    command.validationAction = options.validationAction;
-                }
-
-                const result = await db.command(command);
-
-                logger.info('Validator set', {
-                    collection: collection.collectionName,
-                    validationLevel: options.validationLevel,
-                    validationAction: options.validationAction
-                });
-
-                return {
-                    ok: result.ok,
-                    collection: collection.collectionName,
-                    validator: 'set'
-                };
-            } catch (error) {
-                logger.error('setValidator failed', { error: error.message });
-                throw createValidationError(
-                    `Failed to set validator: ${error.message}`,
-                    'SET_VALIDATOR_ERROR'
-                );
-            }
-        },
-
-        /**
-         * 设置验证级别
-         *
-         * 验证级别：
-         * - 'off': 禁用验证
-         * - 'strict': 对所有插入和更新进行验证（默认）
-         * - 'moderate': 只验证有效文档的更新，不验证现有无效文档
-         *
-         * @param {string} level - 验证级别（'off'/'strict'/'moderate'）
-         * @returns {Promise<Object>} 设置结果
-         *
-         * @example
-         * // 严格验证（所有文档）
-         * await collection.setValidationLevel('strict');
-         *
-         * // 适度验证（只验证有效文档）
-         * await collection.setValidationLevel('moderate');
-         *
-         * // 禁用验证
-         * await collection.setValidationLevel('off');
-         */
-        async setValidationLevel(level) {
-            try {
-                const validLevels = ['off', 'strict', 'moderate'];
-                if (!validLevels.includes(level)) {
-                    throw createValidationError(
-                        `Invalid validation level. Must be one of: ${validLevels.join(', ')}`,
-                        'INVALID_VALIDATION_LEVEL'
-                    );
-                }
-
-                const result = await db.command({
-                    collMod: collection.collectionName,
-                    validationLevel: level
-                });
-
-                logger.info('Validation level set', {
-                    collection: collection.collectionName,
-                    level
-                });
-
-                return {
-                    ok: result.ok,
-                    collection: collection.collectionName,
-                    validationLevel: level
-                };
-            } catch (error) {
-                logger.error('setValidationLevel failed', { error: error.message });
-                throw createValidationError(
-                    `Failed to set validation level: ${error.message}`,
-                    'SET_VALIDATION_LEVEL_ERROR'
-                );
-            }
-        },
-
-        /**
-         * 设置验证失败时的行为
-         *
-         * 验证行为：
-         * - 'error': 拒绝不符合规则的文档（默认）
-         * - 'warn': 允许写入但记录警告
-         *
-         * @param {string} action - 验证行为（'error'/'warn'）
-         * @returns {Promise<Object>} 设置结果
-         *
-         * @example
-         * // 拒绝无效文档
-         * await collection.setValidationAction('error');
-         *
-         * // 允许但警告
-         * await collection.setValidationAction('warn');
-         */
-        async setValidationAction(action) {
-            try {
-                const validActions = ['error', 'warn'];
-                if (!validActions.includes(action)) {
-                    throw createValidationError(
-                        `Invalid validation action. Must be one of: ${validActions.join(', ')}`,
-                        'INVALID_VALIDATION_ACTION'
-                    );
-                }
-
-                const result = await db.command({
-                    collMod: collection.collectionName,
-                    validationAction: action
-                });
-
-                logger.info('Validation action set', {
-                    collection: collection.collectionName,
-                    action
-                });
-
-                return {
-                    ok: result.ok,
-                    collection: collection.collectionName,
-                    validationAction: action
-                };
-            } catch (error) {
-                logger.error('setValidationAction failed', { error: error.message });
-                throw createValidationError(
-                    `Failed to set validation action: ${error.message}`,
-                    'SET_VALIDATION_ACTION_ERROR'
-                );
-            }
-        },
-
-        /**
-         * 获取集合的验证规则
-         * @returns {Promise<Object>} 验证规则信息
-         * @property {Object} validator - 验证规则
-         * @property {string} validationLevel - 验证级别
-         * @property {string} validationAction - 验证行为
-         *
-         * @example
-         * const validation = await collection.getValidator();
-         * console.log('Validator:', validation.validator);
-         * console.log('Level:', validation.validationLevel);
-         * console.log('Action:', validation.validationAction);
-         */
-        async getValidator() {
-            try {
-                const collections = await db.listCollections({
-                    name: collection.collectionName
-                }).toArray();
-
-                if (collections.length === 0) {
-                    throw createValidationError(
-                        `Collection '${collection.collectionName}' not found`,
-                        'COLLECTION_NOT_FOUND'
-                    );
-                }
-
-                const collInfo = collections[0];
-                const options = collInfo.options || {};
-
-                return {
-                    validator: options.validator || null,
-                    validationLevel: options.validationLevel || 'strict',
-                    validationAction: options.validationAction || 'error'
-                };
-            } catch (error) {
-                logger.error('getValidator failed', { error: error.message });
-                throw createValidationError(
-                    `Failed to get validator: ${error.message}`,
-                    'GET_VALIDATOR_ERROR'
-                );
-            }
-        }
-    };
-}
-
-module.exports = { createValidationOps };
-
-

package/lib/mongodb/queries/aggregate.js

@@ -1,172 +0,0 @@
-/**
- * aggregate 查询模块
- * @description 提供 MongoDB 聚合管道功能，支持流式返回和缓存
- */
-
-const { AggregateChain } = require('./chain');
-const { convertAggregationPipeline } = require('../../utils/objectid-converter');
-const { hasExpressionInPipeline } = require('../../expression/detector');
-const ExpressionCompiler = require('../../expression/compiler/ExpressionCompiler');
-
-// 创建全局编译器实例（单例）
-let globalCompiler = null;
-
-function getCompiler(expressionConfig = {}) {
-    if (!globalCompiler) {
-        globalCompiler = new ExpressionCompiler(expressionConfig);
-    }
-    return globalCompiler;
-}
-
-/**
- * 创建 aggregate 查询操作
- * @param {Object} context - 上下文对象
- * @returns {Object} 包含 aggregate 方法的对象
- */
-function createAggregateOps(context) {
-    const {
-        collection,
-        defaults,
-        run,
-        instanceId,
-        effectiveDbName,
-        logger,
-        emit,
-        mongoSlowLogShaper
-    } = context;
-
-    return {
-        /**
-         * 聚合查询（MongoDB 聚合管道透传）
-         * @param {Array} pipeline - 聚合管道数组，如 [{ $match: {...} }, { $group: {...} }]
-         * @param {Object} [options={}] - 聚合选项
-         * @param {number} [options.cache=0] - 缓存时间（毫秒），默认不缓存（聚合通常动态性强）
-         * @param {number} [options.maxTimeMS] - 查询超时时间（毫秒）
-         * @param {boolean} [options.allowDiskUse=false] - 是否允许使用磁盘（默认 false）
-         * @param {Object} [options.collation] - 排序规则（可选）
-         * @param {string|Object} [options.hint] - 索引提示（可选）
-         * @param {string} [options.comment] - 查询注释（可选）
-         * @param {boolean|Object} [options.meta] - 是否返回耗时元信息
-         * @param {boolean} [options.stream] - 是否返回流式结果
-         * @param {number} [options.batchSize] - 批处理大小
-         * @param {boolean|string} [options.explain] - 是否返回查询执行计划，可选值：true/'queryPlanner'/'executionStats'/'allPlansExecution'
-         * @returns {Promise<Array>|ReadableStream|AggregateChain} 聚合结果数组或可读流（当 stream: true 时）；当 explain=true 时返回执行计划；默认返回 AggregateChain 实例支持链式调用
-         */
-        aggregate: (pipeline = [], options = {}) => {
-            // 🆕 v1.1.0: 检测并编译统一表达式
-            let processedPipeline = pipeline;
-
-            if (hasExpressionInPipeline(pipeline)) {
-                const compiler = getCompiler(context.expressionConfig);
-                processedPipeline = compiler.compilePipeline(pipeline, {
-                    targetDB: 'mongodb'
-                });
-
-                if (context.logger && context.expressionConfig?.debug) {
-                    context.logger.debug('[Expression] Pipeline compiled', {
-                        original: pipeline,
-                        compiled: processedPipeline
-                    });
-                }
-            }
-
-            // ✅ v1.3.0: 自动转换聚合管道中的 ObjectId 字符串
-            const convertedPipeline = convertAggregationPipeline(processedPipeline, 0, {
-                logger: context.logger,
-                excludeFields: context.autoConvertConfig?.excludeFields,
-                customFieldPatterns: context.autoConvertConfig?.customFieldPatterns,
-                maxDepth: context.autoConvertConfig?.maxDepth || 5
-            });
-
-            // 如果没有提供 options 或 options 为空对象，返回 AggregateChain 以支持完整的链式调用
-            const hasOptions = options && Object.keys(options).length > 0;
-
-            if (!hasOptions) {
-                // 返回 AggregateChain 实例，支持 .hint().collation() 等链式调用
-                return new AggregateChain(context, convertedPipeline, {});
-            }
-
-            // 如果提供了 options，执行原有逻辑（向后兼容）
-            const {
-                maxTimeMS = defaults.maxTimeMS,
-                allowDiskUse = false,
-                collation,
-                hint,
-                comment,
-                stream = false,
-                batchSize,
-                explain
-            } = options;
-
-            // 构建 MongoDB 聚合选项
-            const aggOptions = { maxTimeMS, allowDiskUse };
-            if (collation) aggOptions.collation = collation;
-            if (hint) aggOptions.hint = hint;
-            if (comment) aggOptions.comment = comment;
-            if (batchSize !== undefined) aggOptions.batchSize = batchSize;
-
-            // 如果启用 explain，直接返回执行计划（不缓存）
-            if (explain) {
-                const verbosity = typeof explain === 'string' ? explain : 'queryPlanner';
-                const cursor = collection.aggregate(convertedPipeline, aggOptions);
-                return cursor.explain(verbosity);
-            }
-
-            // 如果启用流式返回，直接返回 MongoDB 游标流
-            if (stream) {
-                const cursor = collection.aggregate(convertedPipeline, aggOptions);
-                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: 'aggregate-stream',
-                                durationMs,
-                                docCount,
-                                iid: instanceId,
-                                type: context.type,
-                                db: effectiveDbName,
-                                collection: collection.collectionName,
-                                pipeline: mongoSlowLogShaper?.sanitize ? mongoSlowLogShaper.sanitize(pipeline) : pipeline,
-                            };
-                            logger?.warn?.('🐌 Slow aggregate stream', meta);
-                            emit?.('slow-query', meta);
-                        } catch (_) { }
-                    }
-                });
-
-                return readableStream;
-            }
-
-            // 执行聚合的 Promise
-            const resultPromise = run(
-                'aggregate',
-                options,
-                async () => collection.aggregate(convertedPipeline, aggOptions).toArray()
-            );
-
-            // 添加 explain 方法支持链式调用（与原生 MongoDB 一致）
-            resultPromise.explain = async (verbosity = 'queryPlanner') => {
-                const cursor = collection.aggregate(convertedPipeline, aggOptions);
-                return cursor.explain(verbosity);
-            };
-
-            return resultPromise;
-        }
-    };
-}
-
-module.exports = createAggregateOps;
-