monsqlize 1.3.0 → 2.0.0

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

@@ -1,387 +0,0 @@
-/**
- * 集合管理操作模块
- * @module management/collection-ops
- */
-
-const { createValidationError } = require('../../errors');
-
-/**
- * 创建集合管理操作方法
- * @param {Object} context - 上下文对象
- * @param {Object} context.db - MongoDB 数据库实例
- * @param {Object} context.collection - MongoDB 集合实例
- * @param {Object} context.logger - 日志记录器
- * @returns {Object} 集合管理操作方法
- */
-module.exports = function createCollectionOps(context) {
-    const { db, collection, logger } = context;
-
-    return {
-        /**
-         * 删除集合
-         * @returns {Promise<boolean>} 删除操作的结果
-         */
-        dropCollection: async () => {
-            return await collection.drop();
-        },
-
-        /**
-         * 创建集合
-         * @param {string} [name] - 集合名称；省略则使用当前绑定的集合名
-         * @param {Object} [options={}] - 创建集合的配置选项
-         * @param {boolean} [options.capped] - 是否创建固定大小集合
-         * @param {number} [options.size] - 固定大小集合的字节数
-         * @param {number} [options.max] - 固定大小集合的最大文档数
-         * @param {Object} [options.timeseries] - 时间序列集合配置
-         * @param {Object} [options.validator] - 文档验证规则
-         * @returns {Promise<boolean>} 创建成功返回true
-         * @example
-         * // 创建普通集合
-         * await db.createCollection('users');
-         *
-         * // 创建固定大小集合
-         * await db.createCollection('logs', {
-         *   capped: true,
-         *   size: 10485760, // 10MB
-         *   max: 5000
-         * });
-         *
-         * // 创建时间序列集合
-         * await db.createCollection('measurements', {
-         *   timeseries: {
-         *     timeField: 'timestamp',
-         *     metaField: 'sensor',
-         *     granularity: 'seconds'
-         *   }
-         * });
-         */
-        createCollection: async (name, options = {}) => {
-            const collName = name || collection.collectionName;
-            await db.createCollection(collName, options);
-            return true;
-        },
-
-        /**
-         * 创建视图集合
-         * @param {string} name - 视图名称
-         * @param {string} source - 源集合名称
-         * @param {Array} [pipeline=[]] - 聚合管道数组
-         * @returns {Promise<boolean>} 创建成功返回true
-         */
-        createView: async (name, source, pipeline = []) => {
-            await db.createCollection(name, {
-                viewOn: source,
-                pipeline: pipeline || []
-            });
-            return true;
-        },
-
-        /**
-         * 获取集合统计信息
-         * @param {Object} [options] - 选项
-         * @param {number} [options.scale=1] - 缩放因子（1=字节, 1024=KB, 1048576=MB）
-         * @returns {Promise<Object>} 集合统计对象
-         * @property {string} ns - 命名空间（数据库.集合）
-         * @property {number} count - 文档数量
-         * @property {number} size - 数据大小
-         * @property {number} storageSize - 存储大小
-         * @property {number} totalIndexSize - 索引总大小
-         * @property {number} avgObjSize - 平均文档大小
-         * @property {Object} indexSizes - 各索引大小
-         * @example
-         * const stats = await collection.stats();
-         * console.log('Documents:', stats.count);
-         * console.log('Data size:', stats.size, 'bytes');
-         * console.log('Index size:', stats.totalIndexSize, 'bytes');
-         *
-         * // 使用 MB 为单位
-         * const statsMB = await collection.stats({ scale: 1048576 });
-         * console.log('Data size:', statsMB.size, 'MB');
-         */
-        stats: async (options = {}) => {
-            try {
-                const scale = options.scale || 1;
-                // 使用 MongoDB 原生命令获取集合统计
-                const result = await db.command({
-                    collStats: collection.collectionName,
-                    scale
-                });
-
-                return {
-                    ns: result.ns,
-                    count: result.count,
-                    size: result.size,
-                    storageSize: result.storageSize,
-                    totalIndexSize: result.totalIndexSize,
-                    avgObjSize: result.avgObjSize,
-                    indexSizes: result.indexSizes,
-                    nindexes: result.nindexes,
-                    scaleFactor: result.scaleFactor
-                };
-            } catch (error) {
-                if (logger) {
-                    logger.error('Collection stats failed', { error: error.message });
-                }
-                throw createValidationError(
-                    `Failed to get collection stats: ${error.message}`,
-                    { code: 'COLLECTION_STATS_ERROR' }
-                );
-            }
-        },
-
-        /**
-         * 列出数据库中的所有集合
-         * @param {Object} [options] - 选项
-         * @param {boolean} [options.nameOnly=false] - 仅返回集合名称
-         * @returns {Promise<Array<Object>|Array<string>>} 集合列表
-         * @example
-         * // 获取详细信息
-         * const collections = await db.listCollections();
-         * console.log(collections);
-         * // [
-         * //   { name: 'users', type: 'collection' },
-         * //   { name: 'orders', type: 'collection' }
-         * // ]
-         *
-         * // 仅获取名称
-         * const names = await db.listCollections({ nameOnly: true });
-         * console.log(names); // ['users', 'orders']
-         */
-        listCollections: async (options = {}) => {
-            try {
-                const collections = await db.listCollections().toArray();
-
-                if (options.nameOnly) {
-                    return collections.map(c => c.name);
-                }
-
-                return collections.map(c => ({
-                    name: c.name,
-                    type: c.type,
-                    options: c.options,
-                    info: c.info
-                }));
-            } catch (error) {
-                if (logger) {
-                    logger.error('listCollections failed', { error: error.message });
-                }
-                throw createValidationError(
-                    `Failed to list collections: ${error.message}`,
-                    'LIST_COLLECTIONS_ERROR'
-                );
-            }
-        },
-
-        /**
-         * 重命名集合
-         * @param {string} newName - 新集合名称
-         * @param {Object} [options] - 选项
-         * @param {boolean} [options.dropTarget=false] - 如果目标集合存在，是否删除
-         * @returns {Promise<Object>} 重命名结果
-         * @example
-         * await collection.rename('users_new');
-         *
-         * // 如果目标已存在，删除并替换
-         * await collection.rename('users_backup', { dropTarget: true });
-         */
-        renameCollection: async (newName, options = {}) => {
-            try {
-                if (!newName || typeof newName !== 'string') {
-                    throw createValidationError(
-                        'New collection name is required and must be a string',
-                        'INVALID_COLLECTION_NAME'
-                    );
-                }
-
-                const result = await collection.rename(newName, {
-                    dropTarget: options.dropTarget || false
-                });
-
-                if (logger) {
-                    logger.info('Collection renamed', {
-                        from: collection.collectionName,
-                        to: newName
-                    });
-                }
-
-                return {
-                    renamed: true,
-                    from: collection.collectionName,
-                    to: newName
-                };
-            } catch (error) {
-                if (logger) {
-                    logger.error('renameCollection failed', { error: error.message });
-                }
-                throw createValidationError(
-                    `Failed to rename collection: ${error.message}`,
-                    'RENAME_COLLECTION_ERROR'
-                );
-            }
-        },
-
-        /**
-         * 修改集合属性
-         * @param {Object} modifications - 修改选项
-         * @param {Object} [modifications.validator] - 新的验证规则
-         * @param {string} [modifications.validationLevel] - 验证级别
-         * @param {string} [modifications.validationAction] - 验证行为
-         * @param {Object} [modifications.index] - 索引修改
-         * @returns {Promise<Object>} 修改结果
-         * @example
-         * // 修改验证级别
-         * await collection.collMod({
-         *   validationLevel: 'moderate'
-         * });
-         *
-         * // 修改 TTL 索引过期时间
-         * await collection.collMod({
-         *   index: {
-         *     keyPattern: { createdAt: 1 },
-         *     expireAfterSeconds: 7200
-         *   }
-         * });
-         */
-        collMod: async (modifications) => {
-            try {
-                if (!modifications || typeof modifications !== 'object') {
-                    throw createValidationError(
-                        'Modifications object is required',
-                        'INVALID_MODIFICATIONS'
-                    );
-                }
-
-                const result = await db.command({
-                    collMod: collection.collectionName,
-                    ...modifications
-                });
-
-                if (logger) {
-                    logger.info('Collection modified', {
-                        collection: collection.collectionName,
-                        modifications: Object.keys(modifications)
-                    });
-                }
-
-                return {
-                    ok: result.ok,
-                    collection: collection.collectionName
-                };
-            } catch (error) {
-                if (logger) {
-                    logger.error('collMod failed', { error: error.message });
-                }
-                throw createValidationError(
-                    `Failed to modify collection: ${error.message}`,
-                    'COLLMOD_ERROR'
-                );
-            }
-        },
-
-        /**
-         * 转换为固定大小集合
-         * @param {number} size - 集合大小（字节）
-         * @param {Object} [options] - 选项
-         * @param {number} [options.max] - 最大文档数
-         * @returns {Promise<Object>} 转换结果
-         * @example
-         * // 转换为 10MB 固定大小集合
-         * await collection.convertToCapped(10485760);
-         *
-         * // 限制最大文档数
-         * await collection.convertToCapped(10485760, { max: 5000 });
-         */
-        convertToCapped: async (size, options = {}) => {
-            try {
-                if (!size || typeof size !== 'number' || size <= 0) {
-                    throw createValidationError(
-                        'Size must be a positive number',
-                        'INVALID_SIZE'
-                    );
-                }
-
-                const command = {
-                    convertToCapped: collection.collectionName,
-                    size
-                };
-
-                if (options.max) {
-                    command.max = options.max;
-                }
-
-                const result = await db.command(command);
-
-                if (logger) {
-                    logger.info('Collection converted to capped', {
-                        collection: collection.collectionName,
-                        size,
-                        max: options.max
-                    });
-                }
-
-                return {
-                    ok: result.ok,
-                    collection: collection.collectionName,
-                    capped: true,
-                    size
-                };
-            } catch (error) {
-                if (logger) {
-                    logger.error('convertToCapped failed', { error: error.message });
-                }
-                throw createValidationError(
-                    `Failed to convert to capped collection: ${error.message}`,
-                    'CONVERT_CAPPED_ERROR'
-                );
-            }
-        },
-
-        /**
-         * 执行任意 MongoDB 命令
-         * @param {Object} command - MongoDB 命令对象
-         * @param {Object} [options] - 选项
-         * @returns {Promise<Object>} 命令执行结果
-         * @example
-         * // 执行 collStats 命令
-         * const result = await db.runCommand({
-         *   collStats: 'users',
-         *   scale: 1024
-         * });
-         *
-         * // 执行 ping 命令
-         * const ping = await db.runCommand({ ping: 1 });
-         */
-        runCommand: async (command, options = {}) => {
-            try {
-                if (!command || typeof command !== 'object') {
-                    throw createValidationError(
-                        'Command must be an object',
-                        'INVALID_COMMAND'
-                    );
-                }
-
-                const result = await db.command(command, options);
-
-                if (logger) {
-                    logger.debug('Command executed', {
-                        command: Object.keys(command)[0]
-                    });
-                }
-
-                return result;
-            } catch (error) {
-                if (logger) {
-                    logger.error('runCommand failed', {
-                        command: Object.keys(command)[0],
-                        error: error.message
-                    });
-                }
-                throw createValidationError(
-                    `Failed to execute command: ${error.message}`,
-                    'COMMAND_ERROR'
-                );
-            }
-        }
-    };
-};
-

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

@@ -1,202 +0,0 @@
-/**
- * 数据库级别操作方法工厂函数
- * 提供数据库列表和删除等方法
- * @module mongodb/management/database-ops
- */
-
-const { createValidationError } = require('../../errors');
-
-/**
- * 创建数据库操作方法
- * @param {Object} context - 上下文对象
- * @param {Object} context.adapter - MongoDB 适配器
- * @param {Object} context.logger - 日志记录器
- * @returns {Object} 数据库操作方法集合
- */
-function createDatabaseOps(context) {
-    const { adapter, logger } = context;
-
-    return {
-        /**
-         * 列出所有数据库
-         * @param {Object} [options] - 选项
-         * @param {boolean} [options.nameOnly=false] - 仅返回数据库名称数组
-         * @returns {Promise<Array<Object>|Array<string>>} 数据库列表
-         * @property {string} name - 数据库名称
-         * @property {number} sizeOnDisk - 磁盘占用大小（字节）
-         * @property {boolean} empty - 是否为空数据库
-         * @example
-         * // 获取详细信息
-         * const databases = await monSQLize.listDatabases();
-         * console.log(databases);
-         * // [
-         * //   { name: 'mydb', sizeOnDisk: 83886080, empty: false },
-         * //   { name: 'test', sizeOnDisk: 0, empty: true }
-         * // ]
-         *
-         * // 仅获取名称
-         * const dbNames = await monSQLize.listDatabases({ nameOnly: true });
-         * console.log(dbNames); // ['mydb', 'test', 'admin']
-         */
-        async listDatabases(options = {}) {
-            try {
-                const admin = adapter.db.admin();
-                const result = await admin.listDatabases();
-
-                if (options.nameOnly) {
-                    return result.databases.map(db => db.name);
-                }
-
-                return result.databases.map(db => ({
-                    name: db.name,
-                    sizeOnDisk: db.sizeOnDisk,
-                    empty: db.empty
-                }));
-            } catch (error) {
-                logger.error('listDatabases failed', { error: error.message });
-                throw createValidationError(
-                    `Failed to list databases: ${error.message}`,
-                    'LIST_DATABASES_ERROR'
-                );
-            }
-        },
-
-        /**
-         * 删除整个数据库（危险操作）
-         *
-         * ⚠️ 警告：此操作将永久删除数据库中的所有数据，无法恢复！
-         *
-         * 安全机制：
-         * 1. 必须显式传入 { confirm: true } 才能执行
-         * 2. 生产环境默认禁止，需要额外传入 { allowProduction: true }
-         * 3. 所有删除操作都会记录审计日志
-         *
-         * @param {string} databaseName - 数据库名称
-         * @param {Object} options - 选项
-         * @param {boolean} options.confirm - 必须为 true 才能执行
-         * @param {boolean} [options.allowProduction=false] - 是否允许在生产环境执行
-         * @param {string} [options.user] - 操作用户（用于审计日志）
-         * @returns {Promise<Object>} 删除结果
-         * @property {boolean} dropped - 是否删除成功
-         * @property {string} database - 被删除的数据库名称
-         * @throws {ValidationError} 如果未确认或在生产环境禁止执行
-         *
-         * @example
-         * // ❌ 错误：未提供确认
-         * try {
-         *   await monSQLize.dropDatabase('mydb');
-         * } catch (error) {
-         *   console.error(error.message);
-         *   // "dropDatabase requires explicit confirmation..."
-         * }
-         *
-         * // ✅ 正确：提供确认
-         * const result = await monSQLize.dropDatabase('test_db', {
-         *   confirm: true,
-         *   user: 'admin@example.com'
-         * });
-         * console.log('Database dropped:', result.database);
-         *
-         * // ⚠️ 生产环境：需要额外确认
-         * const result = await monSQLize.dropDatabase('prod_db', {
-         *   confirm: true,
-         *   allowProduction: true,
-         *   user: 'admin@example.com'
-         * });
-         */
-        async dropDatabase(databaseName, options = {}) {
-            // 1. 参数验证
-            if (!databaseName || typeof databaseName !== 'string') {
-                throw createValidationError(
-                    'Database name is required and must be a string',
-                    'INVALID_DATABASE_NAME'
-                );
-            }
-
-            // 2. 强制确认机制
-            if (!options.confirm) {
-                const error = new Error(
-                    'dropDatabase requires explicit confirmation. ' +
-                    'Pass { confirm: true } to proceed.\n\n' +
-                    '⚠️  WARNING: This will DELETE ALL DATA in the database!\n' +
-                    '⚠️  This operation CANNOT BE UNDONE!\n\n' +
-                    'Example:\n' +
-                    `  await db.dropDatabase('${databaseName}', { confirm: true })`
-                );
-                error.code = 'CONFIRMATION_REQUIRED';
-                throw error;
-            }
-
-            // 3. 生产环境保护
-            const isProduction = process.env.NODE_ENV === 'production';
-            if (isProduction && !options.allowProduction) {
-                const error = new Error(
-                    'dropDatabase is blocked in production environment.\n\n' +
-                    '⚠️  You are in PRODUCTION mode!\n\n' +
-                    'If you really want to proceed, pass { allowProduction: true }.\n' +
-                    'Make sure you have:\n' +
-                    '  1. Created a backup\n' +
-                    '  2. Verified this is the correct database\n' +
-                    '  3. Obtained necessary approvals\n\n' +
-                    'Example:\n' +
-                    `  await db.dropDatabase('${databaseName}', {\n` +
-                    '    confirm: true,\n' +
-                    '    allowProduction: true,\n' +
-                    "    user: 'your-email@example.com'\n" +
-                    '  })'
-                );
-                error.code = 'PRODUCTION_BLOCKED';
-                throw error;
-            }
-
-            // 4. 审计日志（记录所有删除尝试）
-            logger.warn('dropDatabase called', {
-                event: 'DROP_DATABASE',
-                database: databaseName,
-                user: options.user || 'unknown',
-                timestamp: new Date().toISOString(),
-                environment: process.env.NODE_ENV || 'development',
-                confirmed: true
-            });
-
-            try {
-                // 5. 执行删除 - 使用 admin 数据库执行 dropDatabase 命令
-                const client = adapter.client;
-                const targetDb = client.db(databaseName);
-                await targetDb.dropDatabase();
-
-                // 6. 成功日志
-                logger.info('dropDatabase successful', {
-                    event: 'DROP_DATABASE_SUCCESS',
-                    database: databaseName,
-                    user: options.user || 'unknown',
-                    timestamp: new Date().toISOString()
-                });
-
-                return {
-                    dropped: true,
-                    database: databaseName,
-                    timestamp: new Date()
-                };
-            } catch (error) {
-                // 7. 失败日志
-                logger.error('dropDatabase failed', {
-                    event: 'DROP_DATABASE_FAILED',
-                    database: databaseName,
-                    user: options.user || 'unknown',
-                    error: error.message,
-                    timestamp: new Date().toISOString()
-                });
-
-                throw createValidationError(
-                    `Failed to drop database '${databaseName}': ${error.message}`,
-                    'DROP_DATABASE_ERROR'
-                );
-            }
-        }
-    };
-}
-
-module.exports = { createDatabaseOps };
-
-