monsqlize 1.0.0

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

@@ -0,0 +1,386 @@
+/**
+ * 集合管理操作模块
+ * @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: 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: 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: size,
+                        max: options.max
+                    });
+                }
+
+                return {
+                    ok: result.ok,
+                    collection: collection.collectionName,
+                    capped: true,
+                    size: 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

@@ -0,0 +1,201 @@
+/**
+ * 数据库级别操作方法工厂函数
+ * 提供数据库列表和删除等方法
+ * @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 };
+