monsqlize 1.0.0 → 1.0.2

package/lib/mongodb/connect.js

@@ -1,4 +1,6 @@
 const { MongoClient } = require('mongodb');
+const { SSHTunnelManager } = require('../infrastructure/ssh-tunnel');
+const { parseUri } = require('../infrastructure/uri-parser');
 
 // 懒加载 MongoDB Memory Server（仅在需要时加载）
 let MongoMemoryServer;
@@ -117,26 +119,65 @@ async function stopMemoryServer(logger) {
 
 /**
  * 建立 MongoDB 连接（适配器内部使用）
- * @param {{ databaseName: string, config: { uri?: string, options?: object, useMemoryServer?: boolean, readPreference?: string }, logger: any, defaults: object, type?: string }} params
- * @returns {Promise<{ client: import('mongodb').MongoClient, db: any }>} 返回已连接的 client 与默认 db 句柄（若可用）
+ * @param {{ databaseName: string, config: { uri?: string, options?: object, useMemoryServer?: boolean, readPreference?: string, ssh?: object, remoteHost?: string, remotePort?: number, mongoHost?: string, mongoPort?: number }, logger: any, defaults: object, type?: string }} params
+ * @returns {Promise<{ client: import('mongodb').MongoClient, db: any, sshTunnel?: any }>} 返回已连接的 client、默认 db 句柄（若可用）和 SSH 隧道实例（若使用）
  */
 async function connectMongo({ databaseName, config, logger, defaults, type = 'mongodb' }) {
-    let { uri, options = {}, useMemoryServer, memoryServerOptions, readPreference } = config || {};
+    let { uri, options = {}, useMemoryServer, memoryServerOptions, readPreference, ssh } = config || {};
+
+    let sshTunnel = null;
+    let effectiveUri = uri;
+
+    // ===== SSH 隧道逻辑 =====
+    if (ssh) {
+        logger?.info?.('🔐 Establishing SSH tunnel for MongoDB...');
+
+        // 解析MongoDB目标地址（优先级：显式配置 > URI解析）
+        let remoteHost = config.remoteHost || config.mongoHost;
+        let remotePort = config.remotePort || config.mongoPort;
+
+        if (!remoteHost || !remotePort) {
+            try {
+                const parsed = parseUri(uri);
+                remoteHost = parsed.host;
+                remotePort = parsed.port;
+            } catch (err) {
+                throw new Error('SSH tunnel requires remoteHost and remotePort, or a valid MongoDB URI');
+            }
+        }
 
-    // 🔑 根据 config.useMemoryServer 决定是否使用内存数据库
-    if (useMemoryServer === true) {
+        // 使用SSH隧道管理器工厂
+        sshTunnel = SSHTunnelManager.create(ssh, remoteHost, remotePort, {
+            logger,
+            name: 'MongoDB'
+        });
+
+        try {
+            await sshTunnel.connect();
+
+            // 使用隧道URI
+            effectiveUri = sshTunnel.getTunnelUri('mongodb', uri);
+
+            logger?.info?.(`✅ MongoDB will connect via SSH tunnel: ${sshTunnel.getLocalAddress()}`);
+        } catch (err) {
+            logger?.error?.('❌ SSH tunnel connection failed', err);
+            throw err;
+        }
+    }
+    // ===== Memory Server 逻辑 =====
+    else if (useMemoryServer === true) {
         try {
-            uri = await startMemoryServer(logger, memoryServerOptions);
+            effectiveUri = await startMemoryServer(logger, memoryServerOptions);
         } catch (err) {
             // 如果启动内存服务器失败，且没有提供 uri，抛出错误
-            if (!uri) {
+            if (!effectiveUri) {
                 throw new Error('Failed to start Memory Server and no URI provided');
             }
-            try { logger && logger.warn && logger.warn('Failed to start Memory Server, using provided URI', { uri }); } catch (_) { }
+            logger?.warn?.('Failed to start Memory Server, using provided URI', { uri: effectiveUri });
         }
     }
 
-    if (!uri) throw new Error('MongoDB connect requires config.uri or config.useMemoryServer');
+    if (!effectiveUri) throw new Error('MongoDB connect requires config.uri or config.useMemoryServer');
 
     // 🔑 合并 readPreference 到 MongoClient options
     const clientOptions = { ...options };
@@ -144,17 +185,21 @@ async function connectMongo({ databaseName, config, logger, defaults, type = 'mo
         clientOptions.readPreference = readPreference;
     }
 
-    const client = new MongoClient(uri, clientOptions);
+    const client = new MongoClient(effectiveUri, clientOptions);
     try {
         await client.connect();
         let db = null;
         try { db = client.db(databaseName); } catch (_) { db = null; }
         const ctx = buildLogContext({ type, databaseName, defaults, config });
         // try { logger && logger.info && logger.info('✅ MongoDB connected', ctx); } catch (_) {}
-        return { client, db };
+        return { client, db, sshTunnel };
     } catch (err) {
+        // 连接失败，清理SSH隧道
+        if (sshTunnel) {
+            await sshTunnel.close();
+        }
         const ctx = buildLogContext({ type, databaseName, defaults, config });
-        try { logger && logger.error && logger.error('❌ MongoDB connection failed', ctx, err); } catch (_) { }
+        logger?.error?.('❌ MongoDB connection failed', ctx, err);
         throw err;
     }
 }
@@ -164,11 +209,21 @@ async function connectMongo({ databaseName, config, logger, defaults, type = 'mo
  * @param {import('mongodb').MongoClient} client
  * @param {any} logger
  * @param {boolean} [stopMemory=false] - 是否同时停止内存服务器
+ * @param {any} [sshTunnel=null] - SSH隧道实例（如果使用）
  */
-async function closeMongo(client, logger, stopMemory = false) {
+async function closeMongo(client, logger, stopMemory = false, sshTunnel = null) {
     if (!client) return;
     try { await client.close(); } catch (e) { try { logger && logger.warn && logger.warn('MongoDB close error', e && (e.stack || e)); } catch (_) { } }
 
+    // 关闭SSH隧道
+    if (sshTunnel) {
+        try {
+            await sshTunnel.close();
+        } catch (e) {
+            logger?.warn?.('SSH tunnel close error', e);
+        }
+    }
+
     // 如果指定停止内存服务器
     if (stopMemory) {
         await stopMemoryServer(logger);

package/lib/mongodb/index.js

@@ -17,7 +17,8 @@ const {
     createCountOps,
     createAggregateOps,
     createDistinctOps,
-    createFindPageOps  // 分页查询工厂函数
+    createFindPageOps,     // 分页查询工厂函数
+    createWatchOps         // 🆕 watch 方法
 } = require('./queries');
 
 const {
@@ -45,7 +46,7 @@ const {
     createDeleteOneOps,
     createDeleteManyOps,
     createFindOneAndDeleteOps
-} = require("./writes");
+} = require('./writes');
 
 const { EventEmitter } = require('events');
 module.exports = class {
@@ -95,7 +96,7 @@ module.exports = class {
 
         try {
             this._connecting = (async () => {
-                const { client, db } = await connectMongo({
+                const { client, db, sshTunnel } = await connectMongo({
                     databaseName: this.databaseName,
                     config: this.config,
                     logger: this.logger,
@@ -104,6 +105,12 @@ module.exports = class {
                 });
                 this.client = client;
                 this.db = db;
+                this._sshTunnel = sshTunnel;  // 🔴 保存SSH隧道实例
+
+                // 🔴 初始化慢查询日志存储
+                this._initializeSlowQueryLog();
+                
+
                 try { this.emit && this.emit('connected', { type: this.type, db: this.databaseName, scope: this.defaults?.namespace?.scope }); } catch (_) { }
                 return this.client;
             })();
@@ -150,7 +157,8 @@ module.exports = class {
             { db: ns.db, coll: ns.coll, iid, type: this.type },
             options,
             fn,
-            mongoSlowLogShaper
+            mongoSlowLogShaper,
+            this.onSlowQueryEmit  // 🔴 传递慢查询回调
         );
     }
 
@@ -198,7 +206,12 @@ module.exports = class {
         }, this.logger, this.defaults, {
             keyBuilder: mongoKeyBuilder,
             slowLogShaper: mongoSlowLogShaper,
-            onSlowQueryEmit: (meta) => { try { this.emit && this.emit('slow-query', meta); } catch (_) { } },
+            onSlowQueryEmit: (meta) => {
+                try {
+                    // 触发slow-query事件，由事件监听器处理保存
+                    this.emit && this.emit('slow-query', meta);
+                } catch (_) { }
+            },
             onQueryEmit: (meta) => { try { this.emit && this.emit('query', meta); } catch (_) { } }
         });
 
@@ -218,7 +231,8 @@ module.exports = class {
             mongoSlowLogShaper,
             type: this.type,
             cache: this.cache,
-            getCache: () => this.cache  // 动态获取 cache（支持测试时的临时替换）
+            getCache: () => this.cache,  // 动态获取 cache（支持测试时的临时替换）
+            autoConvertConfig: this.autoConvertConfig  // ✅ v1.3.0: 传递 ObjectId 自动转换配置
         };
 
         // ========================================
@@ -248,6 +262,8 @@ module.exports = class {
             // explain 功能已集成到 find() 的链式调用和 options 参数中
             // 分页查询
             ...createFindPageOps(moduleContext),
+            // 🆕 watch 方法 - Change Streams (v1.1.0)
+            ...createWatchOps(moduleContext),
             // 写操作方法 - Insert
             ...createInsertOneOps(moduleContext),
             ...createInsertManyOps(moduleContext),
@@ -302,6 +318,19 @@ module.exports = class {
  * 关闭连接并释放资源
  */
     async close() {
+        // 🔴 关闭慢查询日志管理器
+        if (this.slowQueryLogManager) {
+            try {
+                await this.slowQueryLogManager.close();
+                this.slowQueryLogManager = null;
+                this.onSlowQueryEmit = null;
+            } catch (err) {
+                if (this.logger.error) {
+                    this.logger.error('[SlowQueryLog] Failed to close manager:', err);
+                }
+            }
+        }
+
         if (this.client) {
             await closeMongo(this.client, this.logger);
         }
@@ -455,4 +484,108 @@ module.exports = class {
         return collectionOps.runCommand(command, options);
     }
 
-}
+    /**
+     * 🔴 初始化慢查询日志存储
+     * @private
+     */
+    _initializeSlowQueryLog() {
+        const slowQueryLogConfig = this.defaults?.slowQueryLog;
+
+        // 支持 boolean 快捷配置
+        if (!slowQueryLogConfig) {
+            return;
+        }
+
+        try {
+            const { SlowQueryLogManager, SlowQueryLogConfigManager } = require('../slow-query-log');
+
+            // 使用配置管理器合并配置
+            const mergedConfig = SlowQueryLogConfigManager.mergeConfig(
+                slowQueryLogConfig,
+                this.type  // 业务库类型（用于自动推断storage.type）
+            );
+
+            // 验证配置
+            SlowQueryLogConfigManager.validate(mergedConfig, this.type);
+
+            // 如果未启用，直接返回
+            if (!mergedConfig.enabled) {
+                return;
+            }
+
+            // 创建慢查询日志管理器
+            this.slowQueryLogManager = new SlowQueryLogManager(
+                mergedConfig,
+                this.client,  // 传递MongoDB客户端（复用连接）
+                this.type,    // 业务库类型
+                this.logger
+            );
+
+            // 🔴 使用事件监听器代替直接回调
+            // 监听 'slow-query' 事件，自动保存慢查询日志
+            this.on('slow-query', async (meta) => {
+                if (this.slowQueryLogManager) {
+                    try {
+                        await this.slowQueryLogManager.save(meta);
+                    } catch (err) {
+                        // 保存失败不影响主流程
+                        if (this.logger.error) {
+                            this.logger.error('[SlowQueryLog] Save failed:', err);
+                        }
+                    }
+                }
+            });
+
+            if (this.logger.info) {
+                this.logger.info('[SlowQueryLog] Manager initialized');
+            }
+        } catch (err) {
+            if (this.logger.error) {
+                this.logger.error('[SlowQueryLog] Failed to initialize:', err);
+            }
+            // 初始化失败不影响主流程
+        }
+    }
+
+    /**
+     * 🔴 获取慢查询日志（查询接口）
+     * @param {Object} filter - 查询条件
+     * @param {Object} options - 查询选项
+     * @returns {Promise<Object[]>}
+     */
+    async getSlowQueryLogs(filter, options) {
+        if (!this.slowQueryLogManager) {
+            throw new Error('Slow query log is not enabled');
+        }
+        return this.slowQueryLogManager.query(filter, options);
+    }
+
+    /**
+     * 🔴 关闭MongoDB连接和SSH隧道
+     * @param {boolean} [stopMemory=false] - 是否停止Memory Server
+     */
+    async close(stopMemory = false) {
+        if (!this.client) {
+            return;
+        }
+
+        try {
+            await closeMongo(
+                this.client,
+                this.logger,
+                stopMemory,
+                this._sshTunnel  // 传递SSH隧道实例
+            );
+
+            this.client = null;
+            this.db = null;
+            this._sshTunnel = null;
+
+            this.emit?.('closed', { type: this.type, db: this.databaseName });
+        } catch (err) {
+            this.logger?.error?.('❌ Failed to close MongoDB connection', err);
+            throw err;
+        }
+    }
+
+};

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

@@ -104,7 +104,7 @@ module.exports = function createCollectionOps(context) {
                 // 使用 MongoDB 原生命令获取集合统计
                 const result = await db.command({
                     collStats: collection.collectionName,
-                    scale: scale
+                    scale
                 });
 
                 return {
@@ -302,7 +302,7 @@ module.exports = function createCollectionOps(context) {
 
                 const command = {
                     convertToCapped: collection.collectionName,
-                    size: size
+                    size
                 };
 
                 if (options.max) {
@@ -314,7 +314,7 @@ module.exports = function createCollectionOps(context) {
                 if (logger) {
                     logger.info('Collection converted to capped', {
                         collection: collection.collectionName,
-                        size: size,
+                        size,
                         max: options.max
                     });
                 }
@@ -323,7 +323,7 @@ module.exports = function createCollectionOps(context) {
                     ok: result.ok,
                     collection: collection.collectionName,
                     capped: true,
-                    size: size
+                    size
                 };
             } catch (error) {
                 if (logger) {

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

@@ -85,7 +85,7 @@ function createIndexOps(context, databaseName, collectionName, nativeCollection)
             const normalizedOptions = normalizeIndexOptions(options);
 
             // 3. 记录开始日志
-            logger.debug(`[createIndex] 开始创建索引`, {
+            logger.debug('[createIndex] 开始创建索引', {
                 ns,
                 keys,
                 options: normalizedOptions
@@ -96,7 +96,7 @@ function createIndexOps(context, databaseName, collectionName, nativeCollection)
 
             // 5. 记录成功日志
             const duration = Date.now() - startTime;
-            logger.info(`[createIndex] 索引创建成功`, {
+            logger.info('[createIndex] 索引创建成功', {
                 ns,
                 indexName: typeof result === 'string' ? result : result.name || 'unknown',
                 keys,
@@ -111,7 +111,7 @@ function createIndexOps(context, databaseName, collectionName, nativeCollection)
             // 7. 错误处理
             const duration = Date.now() - startTime;
 
-            logger.error(`[createIndex] 索引创建失败`, {
+            logger.error('[createIndex] 索引创建失败', {
                 ns,
                 keys,
                 options,
@@ -207,7 +207,7 @@ function createIndexOps(context, databaseName, collectionName, nativeCollection)
             }));
 
             // 3. 记录开始日志
-            logger.debug(`[createIndexes] 开始批量创建索引`, {
+            logger.debug('[createIndexes] 开始批量创建索引', {
                 ns,
                 count: normalizedSpecs.length,
                 specs: normalizedSpecs
@@ -218,7 +218,7 @@ function createIndexOps(context, databaseName, collectionName, nativeCollection)
 
             // 5. 记录成功日志
             const duration = Date.now() - startTime;
-            logger.info(`[createIndexes] 批量创建索引成功`, {
+            logger.info('[createIndexes] 批量创建索引成功', {
                 ns,
                 count: normalizedSpecs.length,
                 indexNames: result,
@@ -232,7 +232,7 @@ function createIndexOps(context, databaseName, collectionName, nativeCollection)
             // 7. 错误处理
             const duration = Date.now() - startTime;
 
-            logger.error(`[createIndexes] 批量创建索引失败`, {
+            logger.error('[createIndexes] 批量创建索引失败', {
                 ns,
                 count: indexSpecs?.length || 0,
                 error: error.message,
@@ -269,7 +269,7 @@ function createIndexOps(context, databaseName, collectionName, nativeCollection)
 
         try {
             // 1. 记录开始日志
-            logger.debug(`[listIndexes] 开始列出索引`, { ns });
+            logger.debug('[listIndexes] 开始列出索引', { ns });
 
             // 2. 执行查询
             const cursor = nativeCollection.listIndexes();
@@ -277,7 +277,7 @@ function createIndexOps(context, databaseName, collectionName, nativeCollection)
 
             // 3. 记录成功日志
             const duration = Date.now() - startTime;
-            logger.debug(`[listIndexes] 列出索引成功`, {
+            logger.debug('[listIndexes] 列出索引成功', {
                 ns,
                 count: indexes.length,
                 indexNames: indexes.map(idx => idx.name),
@@ -291,7 +291,7 @@ function createIndexOps(context, databaseName, collectionName, nativeCollection)
             // 5. 错误处理
             const duration = Date.now() - startTime;
 
-            logger.error(`[listIndexes] 列出索引失败`, {
+            logger.error('[listIndexes] 列出索引失败', {
                 ns,
                 error: error.message,
                 code: error.code,
@@ -301,7 +301,7 @@ function createIndexOps(context, databaseName, collectionName, nativeCollection)
             // MongoDB 命名空间不存在错误（集合不存在）
             if (error.code === 26) {
                 // 返回空数组（集合不存在时没有索引）
-                logger.debug(`[listIndexes] 集合不存在，返回空数组`, { ns });
+                logger.debug('[listIndexes] 集合不存在，返回空数组', { ns });
                 return [];
             }
 
@@ -347,14 +347,14 @@ function createIndexOps(context, databaseName, collectionName, nativeCollection)
             }
 
             // 2. 记录开始日志
-            logger.debug(`[dropIndex] 开始删除索引`, { ns, indexName });
+            logger.debug('[dropIndex] 开始删除索引', { ns, indexName });
 
             // 3. 执行删除
             const result = await nativeCollection.dropIndex(indexName);
 
             // 4. 记录成功日志
             const duration = Date.now() - startTime;
-            logger.info(`[dropIndex] 删除索引成功`, {
+            logger.info('[dropIndex] 删除索引成功', {
                 ns,
                 indexName,
                 result,
@@ -368,7 +368,7 @@ function createIndexOps(context, databaseName, collectionName, nativeCollection)
             // 6. 错误处理
             const duration = Date.now() - startTime;
 
-            logger.error(`[dropIndex] 删除索引失败`, {
+            logger.error('[dropIndex] 删除索引失败', {
                 ns,
                 indexName,
                 error: error.message,
@@ -381,7 +381,7 @@ function createIndexOps(context, databaseName, collectionName, nativeCollection)
             if (errorMsg.includes('_id_') || errorMsg.includes('cannot drop _id index')) {
                 throw createError(
                     'INVALID_ARGUMENT',
-                    `不允许删除 _id 索引`,
+                    '不允许删除 _id 索引',
                     { ns, indexName, cause: error }
                 );
             }
@@ -418,14 +418,14 @@ function createIndexOps(context, databaseName, collectionName, nativeCollection)
 
         try {
             // 1. 记录开始日志
-            logger.debug(`[dropIndexes] 开始删除所有索引`, { ns });
+            logger.debug('[dropIndexes] 开始删除所有索引', { ns });
 
             // 2. 执行删除（MongoDB 会自动保留 _id 索引）
             const result = await nativeCollection.dropIndexes();
 
             // 3. 记录成功日志
             const duration = Date.now() - startTime;
-            logger.info(`[dropIndexes] 删除所有索引成功`, {
+            logger.info('[dropIndexes] 删除所有索引成功', {
                 ns,
                 result,
                 duration
@@ -438,7 +438,7 @@ function createIndexOps(context, databaseName, collectionName, nativeCollection)
             // 5. 错误处理
             const duration = Date.now() - startTime;
 
-            logger.error(`[dropIndexes] 删除所有索引失败`, {
+            logger.error('[dropIndexes] 删除所有索引失败', {
                 ns,
                 error: error.message,
                 code: error.code,
@@ -447,7 +447,7 @@ function createIndexOps(context, databaseName, collectionName, nativeCollection)
 
             // 命名空间不存在（集合不存在）
             if (error.code === 26) {
-                logger.debug(`[dropIndexes] 集合不存在，无需删除索引`, { ns });
+                logger.debug('[dropIndexes] 集合不存在，无需删除索引', { ns });
                 return { ok: 1, msg: '集合不存在，无索引可删除', nIndexesWas: 0 };
             }
 

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

@@ -79,7 +79,7 @@ function createValidationOps(context) {
 
                 const command = {
                     collMod: collection.collectionName,
-                    validator: validator
+                    validator
                 };
 
                 if (options.validationLevel) {
@@ -150,7 +150,7 @@ function createValidationOps(context) {
 
                 logger.info('Validation level set', {
                     collection: collection.collectionName,
-                    level: level
+                    level
                 });
 
                 return {
@@ -201,7 +201,7 @@ function createValidationOps(context) {
 
                 logger.info('Validation action set', {
                     collection: collection.collectionName,
-                    action: action
+                    action
                 });
 
                 return {

package/lib/mongodb/queries/aggregate.js

@@ -4,6 +4,7 @@
  */
 
 const { AggregateChain } = require('./chain');
+const { convertAggregationPipeline } = require('../../utils/objectid-converter');
 
 /**
  * 创建 aggregate 查询操作
@@ -40,12 +41,20 @@ function createAggregateOps(context) {
          * @returns {Promise<Array>|ReadableStream|AggregateChain} 聚合结果数组或可读流（当 stream: true 时）；当 explain=true 时返回执行计划；默认返回 AggregateChain 实例支持链式调用
          */
         aggregate: (pipeline = [], options = {}) => {
+            // ✅ v1.3.0: 自动转换聚合管道中的 ObjectId 字符串
+            const convertedPipeline = convertAggregationPipeline(pipeline, 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, pipeline, {});
+                return new AggregateChain(context, convertedPipeline, {});
             }
 
             // 如果提供了 options，执行原有逻辑（向后兼容）
@@ -70,13 +79,13 @@ function createAggregateOps(context) {
             // 如果启用 explain，直接返回执行计划（不缓存）
             if (explain) {
                 const verbosity = typeof explain === 'string' ? explain : 'queryPlanner';
-                const cursor = collection.aggregate(pipeline, aggOptions);
+                const cursor = collection.aggregate(convertedPipeline, aggOptions);
                 return cursor.explain(verbosity);
             }
 
             // 如果启用流式返回，直接返回 MongoDB 游标流
             if (stream) {
-                const cursor = collection.aggregate(pipeline, aggOptions);
+                const cursor = collection.aggregate(convertedPipeline, aggOptions);
                 const readableStream = cursor.stream();
 
                 // 添加慢查询日志支持
@@ -116,12 +125,12 @@ function createAggregateOps(context) {
             const resultPromise = run(
                 'aggregate',
                 options,
-                async () => collection.aggregate(pipeline, aggOptions).toArray()
+                async () => collection.aggregate(convertedPipeline, aggOptions).toArray()
             );
 
             // 添加 explain 方法支持链式调用（与原生 MongoDB 一致）
             resultPromise.explain = async (verbosity = 'queryPlanner') => {
-                const cursor = collection.aggregate(pipeline, aggOptions);
+                const cursor = collection.aggregate(convertedPipeline, aggOptions);
                 return cursor.explain(verbosity);
             };