monsqlize 1.0.1 → 1.0.5

package/lib/mongodb/writes/insert-many.js

@@ -5,7 +5,8 @@
 
 const { createError, ErrorCodes } = require('../../errors');
 const CacheFactory = require('../../cache');
-const { isInTransaction, getTransactionFromSession } = require("../common/transaction-aware");
+const { isInTransaction, getTransactionFromSession } = require('../common/transaction-aware');
+const { convertObjectIdStrings } = require('../../utils/objectid-converter');
 
 /**
  * 创建 insertMany 操作
@@ -36,7 +37,7 @@ function createInsertManyOps(context) {
      * @param {string} [options.comment] - 操作注释（用于日志追踪）
      * @returns {Promise<Object>} 插入结果 { acknowledged, insertedCount, insertedIds }
      * @throws {Error} 当 documents 参数无效时
-     * 
+     *
      * @example
      * const result = await collection('users').insertMany([
      *     { name: 'Alice', age: 25 },
@@ -62,36 +63,44 @@ function createInsertManyOps(context) {
         if (!Array.isArray(documents)) {
             throw createError(
                 ErrorCodes.DOCUMENTS_REQUIRED,
-                "documents 必须是数组类型",
-                [{ field: "documents", type: "array.required", message: "documents 是必需参数且必须是数组" }]
+                'documents 必须是数组类型',
+                [{ field: 'documents', type: 'array.required', message: 'documents 是必需参数且必须是数组' }]
             );
         }
 
         if (documents.length === 0) {
             throw createError(
                 ErrorCodes.DOCUMENTS_REQUIRED,
-                "documents 数组不能为空",
-                [{ field: "documents", type: "array.min", message: "documents 至少需要包含一个文档" }]
+                'documents 数组不能为空',
+                [{ field: 'documents', type: 'array.min', message: 'documents 至少需要包含一个文档' }]
             );
         }
 
         // 验证每个文档都是对象
         const invalidDocs = documents.filter((doc, index) => {
-            return !doc || typeof doc !== "object" || Array.isArray(doc);
+            return !doc || typeof doc !== 'object' || Array.isArray(doc);
         });
 
         if (invalidDocs.length > 0) {
             throw createError(
                 ErrorCodes.DOCUMENTS_REQUIRED,
-                "documents 中的所有元素必须是对象类型",
+                'documents 中的所有元素必须是对象类型',
                 invalidDocs.map((doc, idx) => ({
                     field: `documents[${idx}]`,
-                    type: "object.required",
-                    message: "必须是对象类型"
+                    type: 'object.required',
+                    message: '必须是对象类型'
                 }))
             );
         }
 
+        // ✅ v1.3.0: 自动转换 ObjectId 字符串
+        const convertedDocuments = documents.map(doc => convertObjectIdStrings(doc, 'document', 0, new WeakSet(), {
+            logger: context.logger,
+            excludeFields: context.autoConvertConfig?.excludeFields,
+            customFieldPatterns: context.autoConvertConfig?.customFieldPatterns,
+            maxDepth: context.autoConvertConfig?.maxDepth
+        }));
+
         // 2. 构建操作上下文
         const operation = 'insertMany';
         const ns = `${databaseName}.${collectionName}`;
@@ -99,7 +108,7 @@ function createInsertManyOps(context) {
 
         try {
             // 3. 执行批量插入操作
-            const result = await nativeCollection.insertMany(documents, options);
+            const result = await nativeCollection.insertMany(convertedDocuments, options);
 
             // 4. 自动失效缓存
             if (cache) {
@@ -107,7 +116,7 @@ function createInsertManyOps(context) {
                     // 使用标准命名空间模式删除该集合的所有缓存
                     const nsObj = {
                         iid: instanceId,
-                        type: "mongodb",
+                        type: 'mongodb',
                         db: databaseName,
                         collection: collectionName
                     };
@@ -186,7 +195,7 @@ function createInsertManyOps(context) {
                 // MongoDB 重复键错误
                 throw createError(
                     ErrorCodes.DUPLICATE_KEY,
-                    "批量插入失败：违反唯一性约束",
+                    '批量插入失败：违反唯一性约束',
                     [{ message: error.message, writeErrors: error.writeErrors }],
                     error
                 );

package/lib/mongodb/writes/insert-one.js

@@ -5,7 +5,8 @@
 
 const { createError, ErrorCodes } = require('../../errors');
 const CacheFactory = require('../../cache');
-const { isInTransaction, getTransactionFromSession } = require("../common/transaction-aware");
+const { isInTransaction, getTransactionFromSession } = require('../common/transaction-aware');
+const { convertObjectIdStrings } = require('../../utils/objectid-converter');
 
 /**
  * 创建 insertOne 操作
@@ -35,7 +36,7 @@ function createInsertOneOps(context) {
      * @param {string} [options.comment] - 操作注释（用于日志追踪）
      * @returns {Promise<Object>} 插入结果 { acknowledged, insertedId }
      * @throws {Error} 当 document 参数无效时
-     * 
+     *
      * @example
      * const result = await collection('users').insertOne(
      *     { name: 'Alice', age: 25 }
@@ -53,21 +54,29 @@ function createInsertOneOps(context) {
         const startTime = Date.now();
 
         // 1. 参数验证
-        if (!document || typeof document !== "object" || Array.isArray(document)) {
+        if (!document || typeof document !== 'object' || Array.isArray(document)) {
             throw createError(
                 ErrorCodes.DOCUMENT_REQUIRED,
-                "document 必须是对象类型",
-                [{ field: "document", type: "object.required", message: "document 是必需参数且必须是对象" }]
+                'document 必须是对象类型',
+                [{ field: 'document', type: 'object.required', message: 'document 是必需参数且必须是对象' }]
             );
         }
 
+        // ✅ v1.3.0: 自动转换 ObjectId 字符串
+        const convertedDocument = convertObjectIdStrings(document, 'document', 0, new WeakSet(), {
+            logger: context.logger,
+            excludeFields: context.autoConvertConfig?.excludeFields,
+            customFieldPatterns: context.autoConvertConfig?.customFieldPatterns,
+            maxDepth: context.autoConvertConfig?.maxDepth
+        });
+
         // 2. 构建操作上下文
         const operation = 'insertOne';
         const ns = `${databaseName}.${collectionName}`;
 
         try {
             // 3. 执行插入操作
-            const result = await nativeCollection.insertOne(document, options);
+            const result = await nativeCollection.insertOne(convertedDocument, options);
 
             // 4. 自动失效缓存
             if (cache) {
@@ -75,7 +84,7 @@ function createInsertOneOps(context) {
                     // 使用标准命名空间模式删除该集合的所有缓存
                     const ns = {
                         iid: instanceId,
-                        type: "mongodb",
+                        type: 'mongodb',
                         db: databaseName,
                         collection: collectionName
                     };
@@ -151,8 +160,8 @@ function createInsertOneOps(context) {
                 // MongoDB 重复键错误
                 throw createError(
                     ErrorCodes.DUPLICATE_KEY,
-                    "文档插入失败：违反唯一性约束",
-                    [{ field: "_id", message: error.message }],
+                    '文档插入失败：违反唯一性约束',
+                    [{ field: '_id', message: error.message }],
                     error
                 );
             }

package/lib/mongodb/writes/replace-one.js

@@ -3,9 +3,10 @@
  * 完整替换单个匹配的文档
  */
 
-const { createError, ErrorCodes } = require("../../errors");
-const CacheFactory = require("../../cache");
-const { isInTransaction, getTransactionFromSession } = require("../common/transaction-aware");
+const { createError, ErrorCodes } = require('../../errors');
+const CacheFactory = require('../../cache');
+const { isInTransaction, getTransactionFromSession } = require('../common/transaction-aware');
+const { convertObjectIdStrings } = require('../../utils/objectid-converter');
 
 /**
  * 创建 replaceOne 操作
@@ -59,39 +60,54 @@ function createReplaceOneOps(context) {
         const startTime = Date.now();
 
         // 1. 参数验证
-        if (!filter || typeof filter !== "object" || Array.isArray(filter)) {
+        if (!filter || typeof filter !== 'object' || Array.isArray(filter)) {
             throw createError(
                 ErrorCodes.INVALID_ARGUMENT,
-                "filter 必须是对象类型",
-                [{ field: "filter", type: "object.required", message: "filter 是必需参数且必须是对象" }]
+                'filter 必须是对象类型',
+                [{ field: 'filter', type: 'object.required', message: 'filter 是必需参数且必须是对象' }]
             );
         }
 
-        if (!replacement || typeof replacement !== "object" || Array.isArray(replacement)) {
+        if (!replacement || typeof replacement !== 'object' || Array.isArray(replacement)) {
             throw createError(
                 ErrorCodes.INVALID_ARGUMENT,
-                "replacement 必须是对象类型",
-                [{ field: "replacement", type: "object.required", message: "replacement 是必需参数且必须是对象" }]
+                'replacement 必须是对象类型',
+                [{ field: 'replacement', type: 'object.required', message: 'replacement 是必需参数且必须是对象' }]
             );
         }
 
         // 验证 replacement 不包含更新操作符（防止误用）
         const replacementKeys = Object.keys(replacement);
-        if (replacementKeys.some(key => key.startsWith("$"))) {
+        if (replacementKeys.some(key => key.startsWith('$'))) {
             throw createError(
                 ErrorCodes.INVALID_ARGUMENT,
-                "replacement 不能包含更新操作符（如 $set, $inc 等）",
-                [{ field: "replacement", type: "object.invalid", message: "replaceOne 用于完整替换文档，请使用 updateOne 进行部分更新" }]
+                'replacement 不能包含更新操作符（如 $set, $inc 等）',
+                [{ field: 'replacement', type: 'object.invalid', message: 'replaceOne 用于完整替换文档，请使用 updateOne 进行部分更新' }]
             );
         }
 
+        // ✅ v1.3.0: 自动转换 ObjectId 字符串
+        const convertedFilter = convertObjectIdStrings(filter, 'filter', 0, new WeakSet(), {
+            logger: context.logger,
+            excludeFields: context.autoConvertConfig?.excludeFields,
+            customFieldPatterns: context.autoConvertConfig?.customFieldPatterns,
+            maxDepth: context.autoConvertConfig?.maxDepth
+        });
+
+        const convertedReplacement = convertObjectIdStrings(replacement, 'document', 0, new WeakSet(), {
+            logger: context.logger,
+            excludeFields: context.autoConvertConfig?.excludeFields,
+            customFieldPatterns: context.autoConvertConfig?.customFieldPatterns,
+            maxDepth: context.autoConvertConfig?.maxDepth
+        });
+
         // 2. 构建操作上下文
-        const operation = "replaceOne";
+        const operation = 'replaceOne';
         const ns = `${databaseName}.${collectionName}`;
 
         try {
             // 3. 执行替换操作
-            const result = await nativeCollection.replaceOne(filter, replacement, options);
+            const result = await nativeCollection.replaceOne(convertedFilter, convertedReplacement, options);
 
             // 4. 自动失效缓存
             if (cache && result.modifiedCount > 0) {
@@ -99,7 +115,7 @@ function createReplaceOneOps(context) {
                     // 使用标准命名空间模式删除该集合的所有缓存
                     const ns = {
                         iid: instanceId,
-                        type: "mongodb",
+                        type: 'mongodb',
                         db: databaseName,
                         collection: collectionName
                     };
@@ -176,8 +192,8 @@ function createReplaceOneOps(context) {
                 // MongoDB 重复键错误（可能在 upsert 时发生）
                 throw createError(
                     ErrorCodes.DUPLICATE_KEY,
-                    "替换失败：违反唯一性约束",
-                    [{ field: "_id", message: error.message }],
+                    '替换失败：违反唯一性约束',
+                    [{ field: '_id', message: error.message }],
                     error
                 );
             }

package/lib/mongodb/writes/result-handler.js

@@ -44,8 +44,8 @@ function detectDriverVersion() {
     _driverVersionChecked = true;
 
     try {
-        const mongodb = require("mongodb");
-        const versionString = mongodb.version || require("mongodb/package.json").version;
+        const mongodb = require('mongodb');
+        const versionString = mongodb.version || require('mongodb/package.json').version;
         const match = versionString.match(/^(\d+)\./);
         if (match) {
             _detectedDriverMajorVersion = parseInt(match[1], 10);
@@ -74,21 +74,21 @@ function warnUnsupportedDriverVersion(logger) {
     if (version < 6) {
         // 驱动版本小于 6.x，可能不兼容
         if (logger && logger.warn) {
-            logger.warn("[result-handler] ⚠️ 检测到 MongoDB 驱动版本过旧", {
+            logger.warn('[result-handler] ⚠️ 检测到 MongoDB 驱动版本过旧', {
                 detectedVersion: version,
-                supportedVersion: "6.x",
-                message: "monSQLize 专为 MongoDB 驱动 6.x 设计，旧版本可能存在兼容性问题",
-                recommendation: "建议升级到 MongoDB Node.js 驱动 ^6.0.0"
+                supportedVersion: '6.x',
+                message: 'monSQLize 专为 MongoDB 驱动 6.x 设计，旧版本可能存在兼容性问题',
+                recommendation: '建议升级到 MongoDB Node.js 驱动 ^6.0.0'
             });
         }
     } else if (version > 6) {
         // 驱动版本大于 6.x，未经测试
         if (logger && logger.warn) {
-            logger.warn("[result-handler] ⚠️ 检测到 MongoDB 驱动版本未经测试", {
+            logger.warn('[result-handler] ⚠️ 检测到 MongoDB 驱动版本未经测试', {
                 detectedVersion: version,
-                testedVersion: "6.x",
-                message: "monSQLize 已针对 MongoDB 驱动 6.x 测试，新版本可能存在未知问题",
-                recommendation: "如遇问题，请查看技术分析报告或回退到驱动 6.x"
+                testedVersion: '6.x',
+                message: 'monSQLize 已针对 MongoDB 驱动 6.x 测试，新版本可能存在未知问题',
+                recommendation: '如遇问题，请查看技术分析报告或回退到驱动 6.x'
             });
         }
     }
@@ -133,7 +133,7 @@ function handleFindOneAndResult(result, options = {}, logger = null) {
     // 情况 1：result 为 null 或 undefined（驱动在某些边界情况下可能返回 null）
     if (!result || result === null) {
         if (logger && logger.debug) {
-            logger.debug("[result-handler] Result is null/undefined, returning empty result", {
+            logger.debug('[result-handler] Result is null/undefined, returning empty result', {
                 includeMetadata: options.includeResultMetadata
             });
         }
@@ -152,14 +152,14 @@ function handleFindOneAndResult(result, options = {}, logger = null) {
     }
 
     // 情况 2：result 是对象但缺少 lastErrorObject（驱动版本差异或异常情况）
-    if (typeof result === "object" && !result.lastErrorObject) {
+    if (typeof result === 'object' && !result.lastErrorObject) {
         if (logger && logger.warn) {
-            logger.warn("[result-handler] ⚠️ Result missing lastErrorObject, possible driver version issue", {
+            logger.warn('[result-handler] ⚠️ Result missing lastErrorObject, possible driver version issue', {
                 hasValue: result.value !== undefined,
                 hasOk: result.ok !== undefined,
                 resultKeys: Object.keys(result),
                 driverVersion: detectDriverVersion(),
-                recommendation: "这可能表明 MongoDB 驱动返回了非预期的格式，请检查驱动版本"
+                recommendation: '这可能表明 MongoDB 驱动返回了非预期的格式，请检查驱动版本'
             });
         }