monsqlize 1.0.0 → 1.0.2

package/lib/mongodb/writes/delete-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');
 
 /**
  * 创建 deleteOne 操作
@@ -61,28 +62,36 @@ function createDeleteOneOps(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 是必需参数且必须是对象' }]
             );
         }
 
+        // ✅ 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
+        });
+
         // 2. 构建操作上下文
-        const operation = "deleteOne";
+        const operation = 'deleteOne';
         const ns = `${databaseName}.${collectionName}`;
 
         try {
             // 3. 执行删除操作
-            const result = await nativeCollection.deleteOne(filter, options);
+            const result = await nativeCollection.deleteOne(convertedFilter, options);
 
             // 4. 自动失效缓存（如果有文档被删除）
             if (cache && result.deletedCount > 0) {
                 try {
                     const ns = {
                         iid: instanceId,
-                        type: "mongodb",
+                        type: 'mongodb',
                         db: databaseName,
                         collection: collectionName
                     };

package/lib/mongodb/writes/find-one-and-delete.js

@@ -3,10 +3,11 @@
  * 原子地查找并删除单个文档
  */
 
-const { createError, ErrorCodes } = require("../../errors");
-const CacheFactory = require("../../cache");
-const { handleFindOneAndResult, wasDocumentModified } = require("./result-handler");
-const { isInTransaction, getTransactionFromSession } = require("../common/transaction-aware");
+const { createError, ErrorCodes } = require('../../errors');
+const CacheFactory = require('../../cache');
+const { handleFindOneAndResult, wasDocumentModified } = require('./result-handler');
+const { isInTransaction, getTransactionFromSession } = require('../common/transaction-aware');
+const { convertObjectIdStrings } = require('../../utils/objectid-converter');
 
 /**
  * 创建 findOneAndDelete 操作
@@ -78,23 +79,31 @@ function createFindOneAndDeleteOps(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 是必需参数且必须是对象' }]
             );
         }
 
+        // ✅ 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
+        });
+
         // 2. 构建操作上下文
-        const operation = "findOneAndDelete";
+        const operation = 'findOneAndDelete';
         const ns = `${databaseName}.${collectionName}`;
 
         try {
             // 3. 执行查找并删除操作
             // MongoDB 驱动 6.x: 默认返回文档，需要 includeResultMetadata=true 获取完整元数据
             const driverOptions = { ...options, includeResultMetadata: true };
-            const result = await nativeCollection.findOneAndDelete(filter, driverOptions);
+            const result = await nativeCollection.findOneAndDelete(convertedFilter, driverOptions);
 
             // 4. 自动失效缓存（如果有文档被删除）
             // 使用安全的修改判断函数
@@ -103,7 +112,7 @@ function createFindOneAndDeleteOps(context) {
                 try {
                     const ns = {
                         iid: instanceId,
-                        type: "mongodb",
+                        type: 'mongodb',
                         db: databaseName,
                         collection: collectionName
                     };

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

@@ -3,10 +3,11 @@
  * 原子地查找并替换单个文档
  */
 
-const { createError, ErrorCodes } = require("../../errors");
-const CacheFactory = require("../../cache");
-const { handleFindOneAndResult, wasDocumentModified } = require("./result-handler");
-const { isInTransaction, getTransactionFromSession } = require("../common/transaction-aware");
+const { createError, ErrorCodes } = require('../../errors');
+const CacheFactory = require('../../cache');
+const { handleFindOneAndResult, wasDocumentModified } = require('./result-handler');
+const { isInTransaction, getTransactionFromSession } = require('../common/transaction-aware');
+const { convertObjectIdStrings } = require('../../utils/objectid-converter');
 
 /**
  * 创建 findOneAndReplace 操作
@@ -75,41 +76,56 @@ function createFindOneAndReplaceOps(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: "findOneAndReplace 用于完整替换文档，请使用 findOneAndUpdate 进行部分更新" }]
+                'replacement 不能包含更新操作符（如 $set, $inc 等）',
+                [{ field: 'replacement', type: 'object.invalid', message: 'findOneAndReplace 用于完整替换文档，请使用 findOneAndUpdate 进行部分更新' }]
             );
         }
 
+        // ✅ 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 = "findOneAndReplace";
+        const operation = 'findOneAndReplace';
         const ns = `${databaseName}.${collectionName}`;
 
         try {
             // 3. 执行查找并替换操作
             // MongoDB 驱动 6.x: 默认返回文档，需要 includeResultMetadata=true 获取完整元数据
             const driverOptions = { ...options, includeResultMetadata: true };
-            const result = await nativeCollection.findOneAndReplace(filter, replacement, driverOptions);
+            const result = await nativeCollection.findOneAndReplace(convertedFilter, convertedReplacement, driverOptions);
 
             // 4. 自动失效缓存（如果有文档被修改）
             // 使用安全的修改判断函数
@@ -118,7 +134,7 @@ function createFindOneAndReplaceOps(context) {
                 try {
                     const ns = {
                         iid: instanceId,
-                        type: "mongodb",
+                        type: 'mongodb',
                         db: databaseName,
                         collection: collectionName
                     };
@@ -166,7 +182,7 @@ function createFindOneAndReplaceOps(context) {
                     replacementKeys: Object.keys(replacement),
                     found: result && result.value !== null,
                     upserted: result?.lastErrorObject?.upserted ? true : false,
-                    returnDocument: options.returnDocument || "before",
+                    returnDocument: options.returnDocument || 'before',
                     comment: options.comment
                 });
             } else {
@@ -175,7 +191,7 @@ function createFindOneAndReplaceOps(context) {
                     duration,
                     found: result && result.value !== null,
                     upserted: result?.lastErrorObject?.upserted ? true : false,
-                    returnDocument: options.returnDocument || "before"
+                    returnDocument: options.returnDocument || 'before'
                 });
             }
 
@@ -199,8 +215,8 @@ function createFindOneAndReplaceOps(context) {
             if (error.code === 11000) {
                 throw createError(
                     ErrorCodes.DUPLICATE_KEY,
-                    "查找并替换失败：违反唯一性约束",
-                    [{ field: "_id", message: error.message }],
+                    '查找并替换失败：违反唯一性约束',
+                    [{ field: '_id', message: error.message }],
                     error
                 );
             }

package/lib/mongodb/writes/find-one-and-update.js

@@ -3,10 +3,11 @@
  * 原子地查找并更新单个文档
  */
 
-const { createError, ErrorCodes } = require("../../errors");
-const CacheFactory = require("../../cache");
-const { handleFindOneAndResult, wasDocumentModified } = require("./result-handler");
-const { isInTransaction, getTransactionFromSession } = require("../common/transaction-aware");
+const { createError, ErrorCodes } = require('../../errors');
+const CacheFactory = require('../../cache');
+const { handleFindOneAndResult, wasDocumentModified } = require('./result-handler');
+const { isInTransaction, getTransactionFromSession } = require('../common/transaction-aware');
+const { convertObjectIdStrings, convertUpdateDocument } = require('../../utils/objectid-converter');
 
 /**
  * 创建 findOneAndUpdate 操作
@@ -76,41 +77,56 @@ function createFindOneAndUpdateOps(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 (!update || typeof update !== "object" || Array.isArray(update)) {
+        if (!update || typeof update !== 'object' || Array.isArray(update)) {
             throw createError(
                 ErrorCodes.INVALID_ARGUMENT,
-                "update 必须是对象类型",
-                [{ field: "update", type: "object.required", message: "update 是必需参数且必须是对象" }]
+                'update 必须是对象类型',
+                [{ field: 'update', type: 'object.required', message: 'update 是必需参数且必须是对象' }]
             );
         }
 
         // 验证 update 包含更新操作符
         const updateKeys = Object.keys(update);
-        if (updateKeys.length > 0 && !updateKeys.some(key => key.startsWith("$"))) {
+        if (updateKeys.length > 0 && !updateKeys.some(key => key.startsWith('$'))) {
             throw createError(
                 ErrorCodes.INVALID_ARGUMENT,
-                "update 必须使用更新操作符（如 $set, $inc 等）",
-                [{ field: "update", type: "object.invalid", message: "请使用 $set, $inc, $push 等更新操作符，或使用 findOneAndReplace 进行整体替换" }]
+                'update 必须使用更新操作符（如 $set, $inc 等）',
+                [{ field: 'update', type: 'object.invalid', message: '请使用 $set, $inc, $push 等更新操作符，或使用 findOneAndReplace 进行整体替换' }]
             );
         }
 
+        // ✅ 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 convertedUpdate = convertUpdateDocument(update, {
+            logger: context.logger,
+            excludeFields: context.autoConvertConfig?.excludeFields,
+            customFieldPatterns: context.autoConvertConfig?.customFieldPatterns,
+            maxDepth: context.autoConvertConfig?.maxDepth
+        });
+
         // 2. 构建操作上下文
-        const operation = "findOneAndUpdate";
+        const operation = 'findOneAndUpdate';
         const ns = `${databaseName}.${collectionName}`;
 
         try {
             // 3. 执行查找并更新操作
             // MongoDB 驱动 6.x: 默认返回文档，需要 includeResultMetadata=true 获取完整元数据
             const driverOptions = { ...options, includeResultMetadata: true };
-            const result = await nativeCollection.findOneAndUpdate(filter, update, driverOptions);
+            const result = await nativeCollection.findOneAndUpdate(convertedFilter, convertedUpdate, driverOptions);
 
             // 4. 自动失效缓存（如果有文档被修改）
             // 使用安全的修改判断函数
@@ -119,7 +135,7 @@ function createFindOneAndUpdateOps(context) {
                 try {
                     const ns = {
                         iid: instanceId,
-                        type: "mongodb",
+                        type: 'mongodb',
                         db: databaseName,
                         collection: collectionName
                     };
@@ -167,7 +183,7 @@ function createFindOneAndUpdateOps(context) {
                     updateKeys: Object.keys(update),
                     found: result && result.value !== null,
                     upserted: result?.lastErrorObject?.upserted ? true : false,
-                    returnDocument: options.returnDocument || "before",
+                    returnDocument: options.returnDocument || 'before',
                     comment: options.comment
                 });
             } else {
@@ -176,7 +192,7 @@ function createFindOneAndUpdateOps(context) {
                     duration,
                     found: result && result.value !== null,
                     upserted: result?.lastErrorObject?.upserted ? true : false,
-                    returnDocument: options.returnDocument || "before"
+                    returnDocument: options.returnDocument || 'before'
                 });
             }
 
@@ -200,8 +216,8 @@ function createFindOneAndUpdateOps(context) {
             if (error.code === 11000) {
                 throw createError(
                     ErrorCodes.DUPLICATE_KEY,
-                    "查找并更新失败：违反唯一性约束",
-                    [{ field: "_id", message: error.message }],
+                    '查找并更新失败：违反唯一性约束',
+                    [{ field: '_id', message: error.message }],
                     error
                 );
             }

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

@@ -5,8 +5,9 @@
 
 const { ObjectId } = require('mongodb');
 const { createError, ErrorCodes } = require('../../errors');
-const { isInTransaction, getTransactionFromSession } = require("../common/transaction-aware");
-const { handleFindOneAndResult, wasDocumentModified } = require("./result-handler");
+const { isInTransaction, getTransactionFromSession } = require('../common/transaction-aware');
+const { handleFindOneAndResult, wasDocumentModified } = require('./result-handler');
+const { convertObjectIdStrings } = require('../../utils/objectid-converter');
 
 /**
  * 创建 incrementOne 操作
@@ -91,6 +92,14 @@ function createIncrementOneOps(context) {
             );
         }
 
+        // ✅ 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
+        });
+
         // 2. 构建 $inc 更新对象
         let incUpdate;
 
@@ -138,7 +147,7 @@ function createIncrementOneOps(context) {
         const projection = actualOptions.projection;
 
         const updateOptions = {
-            returnDocument: returnDocument,
+            returnDocument,
             includeResultMetadata: true,
             maxTimeMS
         };
@@ -148,7 +157,7 @@ function createIncrementOneOps(context) {
         // 4. 执行 findOneAndUpdate 操作
         let result;
         try {
-            result = await collection.findOneAndUpdate(filter, incUpdate, updateOptions);
+            result = await collection.findOneAndUpdate(convertedFilter, incUpdate, updateOptions);
         } catch (error) {
             throw error;
         }
@@ -201,13 +210,13 @@ function createIncrementOneOps(context) {
                     operation: 'incrementOne',
                     durationMs: duration,
                     iid: instanceId,
-                    type: type,
+                    type,
                     db: effectiveDbName,
                     collection: collection.collectionName,
                     found: result.value !== null,
                     filter: mongoSlowLogShaper?.sanitize ? mongoSlowLogShaper.sanitize(filter) : filter,
                     update: mongoSlowLogShaper?.sanitize ? mongoSlowLogShaper.sanitize(incUpdate) : incUpdate,
-                    comment: comment
+                    comment
                 };
                 logger?.warn?.('🐌 Slow query: incrementOne', meta);
                 emit?.('slow-query', meta);
@@ -219,7 +228,7 @@ function createIncrementOneOps(context) {
         // 7. 日志记录
         logger?.debug?.('[incrementOne] 操作完成', {
             ns: `${effectiveDbName}.${collection.collectionName}`,
-            duration: duration,
+            duration,
             found: result && result.value !== null,
             modified: wasDocumentModified(result)
         });

package/lib/mongodb/writes/index.js

@@ -3,19 +3,19 @@
  * 统一导出所有写操作的工厂函数
  */
 
-const { createInsertOneOps } = require("./insert-one");
-const { createInsertManyOps } = require("./insert-many");
-const { createInsertBatchOps } = require("./insert-batch");
-const { createUpdateOneOps } = require("./update-one");
-const { createUpdateManyOps } = require("./update-many");
-const { createReplaceOneOps } = require("./replace-one");
-const { createUpsertOneOps } = require("./upsert-one");  // upsertOne 便利方法
-const { createIncrementOneOps } = require("./increment-one");  // 新增：incrementOne 便利方法
-const { createFindOneAndUpdateOps } = require("./find-one-and-update");
-const { createFindOneAndReplaceOps } = require("./find-one-and-replace");
-const { createDeleteOneOps } = require("./delete-one");
-const { createDeleteManyOps } = require("./delete-many");
-const { createFindOneAndDeleteOps } = require("./find-one-and-delete");
+const { createInsertOneOps } = require('./insert-one');
+const { createInsertManyOps } = require('./insert-many');
+const { createInsertBatchOps } = require('./insert-batch');
+const { createUpdateOneOps } = require('./update-one');
+const { createUpdateManyOps } = require('./update-many');
+const { createReplaceOneOps } = require('./replace-one');
+const { createUpsertOneOps } = require('./upsert-one');  // upsertOne 便利方法
+const { createIncrementOneOps } = require('./increment-one');  // 新增：incrementOne 便利方法
+const { createFindOneAndUpdateOps } = require('./find-one-and-update');
+const { createFindOneAndReplaceOps } = require('./find-one-and-replace');
+const { createDeleteOneOps } = require('./delete-one');
+const { createDeleteManyOps } = require('./delete-many');
+const { createFindOneAndDeleteOps } = require('./find-one-and-delete');
 
 module.exports = {
     // Insert 操作