monsqlize 1.0.0 → 1.0.2

package/lib/mongodb/queries/chain.js

@@ -4,6 +4,7 @@
  */
 
 const { createErrorMessage } = require('../../common/docs-urls');
+const { convertObjectIdStrings, convertAggregationPipeline } = require('../../utils/objectid-converter');
 
 /**
  * FindChain 类 - find 查询的链式调用构建器
@@ -25,7 +26,13 @@ class FindChain {
      */
     constructor(context, query = {}, initialOptions = {}) {
         this._context = context;
-        this._query = query;
+        // ✅ v1.3.0: 自动转换 ObjectId 字符串
+        this._query = convertObjectIdStrings(query, 'filter', 0, new WeakSet(), {
+            logger: context.logger,
+            excludeFields: context.autoConvertConfig?.excludeFields,
+            customFieldPatterns: context.autoConvertConfig?.customFieldPatterns,
+            maxDepth: context.autoConvertConfig?.maxDepth
+        });
         this._options = { ...initialOptions };
         this._executed = false;
     }
@@ -38,8 +45,8 @@ class FindChain {
     limit(value) {
         if (this._executed) {
             throw new Error(createErrorMessage(
-                "Cannot call .limit() after query execution.\n" +
-                "Tip: Create a new chain for another query:\n" +
+                'Cannot call .limit() after query execution.\n' +
+                'Tip: Create a new chain for another query:\n' +
                 "  const results = await collection('products').find({}).limit(10);",
                 'chaining.limit'
             ));
@@ -47,7 +54,7 @@ class FindChain {
         if (typeof value !== 'number' || value < 0) {
             throw new Error(createErrorMessage(
                 `limit() requires a non-negative number, got: ${typeof value} (${value})\n` +
-                `Usage: .limit(10)`,
+                'Usage: .limit(10)',
                 'chaining.limit'
             ));
         }
@@ -63,15 +70,15 @@ class FindChain {
     skip(value) {
         if (this._executed) {
             throw new Error(createErrorMessage(
-                "Cannot call .skip() after query execution.\n" +
-                "Tip: Create a new chain for another query.",
+                'Cannot call .skip() after query execution.\n' +
+                'Tip: Create a new chain for another query.',
                 'chaining.skip'
             ));
         }
         if (typeof value !== 'number' || value < 0) {
             throw new Error(createErrorMessage(
                 `skip() requires a non-negative number, got: ${typeof value} (${value})\n` +
-                `Usage: .skip(10)`,
+                'Usage: .skip(10)',
                 'chaining.skip'
             ));
         }
@@ -87,15 +94,15 @@ class FindChain {
     sort(value) {
         if (this._executed) {
             throw new Error(createErrorMessage(
-                "Cannot call .sort() after query execution.",
+                'Cannot call .sort() after query execution.',
                 'chaining.sort'
             ));
         }
         if (!value || (typeof value !== 'object')) {
             throw new Error(createErrorMessage(
                 `sort() requires an object or array, got: ${typeof value}\n` +
-                `Usage: .sort({ price: -1, name: 1 })\n` +
-                `Note: Use 1 for ascending, -1 for descending`,
+                'Usage: .sort({ price: -1, name: 1 })\n' +
+                'Note: Use 1 for ascending, -1 for descending',
                 'chaining.sort'
             ));
         }
@@ -111,14 +118,14 @@ class FindChain {
     project(value) {
         if (this._executed) {
             throw new Error(createErrorMessage(
-                "Cannot call .project() after query execution.",
+                'Cannot call .project() after query execution.',
                 'chaining.project'
             ));
         }
         if (!value || typeof value !== 'object') {
             throw new Error(createErrorMessage(
                 `project() requires an object or array, got: ${typeof value}\n` +
-                `Usage: .project({ name: 1, price: 1 })`,
+                'Usage: .project({ name: 1, price: 1 })',
                 'chaining.project'
             ));
         }
@@ -134,14 +141,14 @@ class FindChain {
     hint(value) {
         if (this._executed) {
             throw new Error(createErrorMessage(
-                "Cannot call .hint() after query execution.",
+                'Cannot call .hint() after query execution.',
                 'chaining.hint'
             ));
         }
         if (!value) {
             throw new Error(createErrorMessage(
-                "hint() requires an index name or specification\n" +
-                `Usage: .hint({ category: 1, price: -1 }) or .hint('category_1_price_-1')`,
+                'hint() requires an index name or specification\n' +
+                'Usage: .hint({ category: 1, price: -1 }) or .hint(\'category_1_price_-1\')',
                 'chaining.hint'
             ));
         }
@@ -157,14 +164,14 @@ class FindChain {
     collation(value) {
         if (this._executed) {
             throw new Error(createErrorMessage(
-                "Cannot call .collation() after query execution.",
+                'Cannot call .collation() after query execution.',
                 'chaining.collation'
             ));
         }
         if (!value || typeof value !== 'object') {
             throw new Error(createErrorMessage(
                 `collation() requires an object, got: ${typeof value}\n` +
-                `Usage: .collation({ locale: 'zh', strength: 2 })`,
+                'Usage: .collation({ locale: \'zh\', strength: 2 })',
                 'chaining.collation'
             ));
         }
@@ -180,14 +187,14 @@ class FindChain {
     comment(value) {
         if (this._executed) {
             throw new Error(createErrorMessage(
-                "Cannot call .comment() after query execution.",
+                'Cannot call .comment() after query execution.',
                 'chaining.comment'
             ));
         }
         if (typeof value !== 'string') {
             throw new Error(createErrorMessage(
                 `comment() requires a string, got: ${typeof value}\n` +
-                `Usage: .comment('UserAPI:getProducts:user_123')`,
+                'Usage: .comment(\'UserAPI:getProducts:user_123\')',
                 'chaining.comment'
             ));
         }
@@ -203,14 +210,14 @@ class FindChain {
     maxTimeMS(value) {
         if (this._executed) {
             throw new Error(createErrorMessage(
-                "Cannot call .maxTimeMS() after query execution.",
+                'Cannot call .maxTimeMS() after query execution.',
                 'chaining.maxTimeMS'
             ));
         }
         if (typeof value !== 'number' || value < 0) {
             throw new Error(createErrorMessage(
                 `maxTimeMS() requires a non-negative number, got: ${typeof value} (${value})\n` +
-                `Usage: .maxTimeMS(5000) // 5 seconds`,
+                'Usage: .maxTimeMS(5000) // 5 seconds',
                 'chaining.maxTimeMS'
             ));
         }
@@ -226,14 +233,14 @@ class FindChain {
     batchSize(value) {
         if (this._executed) {
             throw new Error(createErrorMessage(
-                "Cannot call .batchSize() after query execution.",
+                'Cannot call .batchSize() after query execution.',
                 'chaining.batchSize'
             ));
         }
         if (typeof value !== 'number' || value < 0) {
             throw new Error(createErrorMessage(
                 `batchSize() requires a non-negative number, got: ${typeof value} (${value})\n` +
-                `Usage: .batchSize(1000)`,
+                'Usage: .batchSize(1000)',
                 'chaining.batchSize'
             ));
         }
@@ -301,8 +308,8 @@ class FindChain {
     async toArray() {
         if (this._executed) {
             throw new Error(createErrorMessage(
-                "Query already executed. Create a new chain for another query.\n" +
-                "Tip: Each chain can only be executed once:\n" +
+                'Query already executed. Create a new chain for another query.\n' +
+                'Tip: Each chain can only be executed once:\n' +
                 "  const results1 = await collection('products').find({}).limit(10);\n" +
                 "  const results2 = await collection('products').find({}).limit(20); // Create new chain",
                 'chaining.toArray'
@@ -319,11 +326,11 @@ class FindChain {
         const skip = this._options.skip;
         const maxTimeMS = this._options.maxTimeMS !== undefined ? this._options.maxTimeMS : defaults.maxTimeMS;
 
-        const driverOpts = { 
-            projection: this._options.projection, 
-            sort, 
-            skip, 
-            maxTimeMS 
+        const driverOpts = {
+            projection: this._options.projection,
+            sort,
+            skip,
+            maxTimeMS
         };
         if (this._options.hint) driverOpts.hint = this._options.hint;
         if (this._options.collation) driverOpts.collation = this._options.collation;
@@ -389,14 +396,14 @@ class AggregateChain {
     hint(value) {
         if (this._executed) {
             throw new Error(createErrorMessage(
-                "Cannot call .hint() after query execution.",
+                'Cannot call .hint() after query execution.',
                 'chaining.hint'
             ));
         }
         if (!value) {
             throw new Error(createErrorMessage(
-                "hint() requires an index name or specification\n" +
-                `Usage: .hint({ status: 1, createdAt: -1 })`,
+                'hint() requires an index name or specification\n' +
+                'Usage: .hint({ status: 1, createdAt: -1 })',
                 'chaining.hint'
             ));
         }
@@ -412,14 +419,14 @@ class AggregateChain {
     collation(value) {
         if (this._executed) {
             throw new Error(createErrorMessage(
-                "Cannot call .collation() after query execution.",
+                'Cannot call .collation() after query execution.',
                 'chaining.collation'
             ));
         }
         if (!value || typeof value !== 'object') {
             throw new Error(createErrorMessage(
                 `collation() requires an object, got: ${typeof value}\n` +
-                `Usage: .collation({ locale: 'zh', strength: 2 })`,
+                'Usage: .collation({ locale: \'zh\', strength: 2 })',
                 'chaining.collation'
             ));
         }
@@ -435,14 +442,14 @@ class AggregateChain {
     comment(value) {
         if (this._executed) {
             throw new Error(createErrorMessage(
-                "Cannot call .comment() after query execution.",
+                'Cannot call .comment() after query execution.',
                 'chaining.comment'
             ));
         }
         if (typeof value !== 'string') {
             throw new Error(createErrorMessage(
                 `comment() requires a string, got: ${typeof value}\n` +
-                `Usage: .comment('OrderAPI:aggregateSales')`,
+                'Usage: .comment(\'OrderAPI:aggregateSales\')',
                 'chaining.comment'
             ));
         }
@@ -458,14 +465,14 @@ class AggregateChain {
     maxTimeMS(value) {
         if (this._executed) {
             throw new Error(createErrorMessage(
-                "Cannot call .maxTimeMS() after query execution.",
+                'Cannot call .maxTimeMS() after query execution.',
                 'chaining.maxTimeMS'
             ));
         }
         if (typeof value !== 'number' || value < 0) {
             throw new Error(createErrorMessage(
                 `maxTimeMS() requires a non-negative number, got: ${typeof value} (${value})\n` +
-                `Usage: .maxTimeMS(10000) // 10 seconds`,
+                'Usage: .maxTimeMS(10000) // 10 seconds',
                 'chaining.maxTimeMS'
             ));
         }
@@ -481,14 +488,14 @@ class AggregateChain {
     allowDiskUse(value) {
         if (this._executed) {
             throw new Error(createErrorMessage(
-                "Cannot call .allowDiskUse() after query execution.",
+                'Cannot call .allowDiskUse() after query execution.',
                 'chaining.allowDiskUse'
             ));
         }
         if (typeof value !== 'boolean') {
             throw new Error(createErrorMessage(
                 `allowDiskUse() requires a boolean, got: ${typeof value}\n` +
-                `Usage: .allowDiskUse(true)`,
+                'Usage: .allowDiskUse(true)',
                 'chaining.allowDiskUse'
             ));
         }
@@ -504,14 +511,14 @@ class AggregateChain {
     batchSize(value) {
         if (this._executed) {
             throw new Error(createErrorMessage(
-                "Cannot call .batchSize() after query execution.",
+                'Cannot call .batchSize() after query execution.',
                 'chaining.batchSize'
             ));
         }
         if (typeof value !== 'number' || value < 0) {
             throw new Error(createErrorMessage(
                 `batchSize() requires a non-negative number, got: ${typeof value} (${value})\n` +
-                `Usage: .batchSize(1000)`,
+                'Usage: .batchSize(1000)',
                 'chaining.batchSize'
             ));
         }
@@ -567,8 +574,8 @@ class AggregateChain {
     async toArray() {
         if (this._executed) {
             throw new Error(createErrorMessage(
-                "Query already executed. Create a new chain for another query.\n" +
-                "Tip: Each chain can only be executed once:\n" +
+                'Query already executed. Create a new chain for another query.\n' +
+                'Tip: Each chain can only be executed once:\n' +
                 "  const results1 = await collection('orders').aggregate([...]).allowDiskUse(true);\n" +
                 "  const results2 = await collection('orders').aggregate([...]).maxTimeMS(5000); // Create new chain",
                 'chaining.toArray'

package/lib/mongodb/queries/count.js

@@ -3,6 +3,8 @@
  * @description 提供文档计数功能，使用 MongoDB 原生推荐的 countDocuments() 和 estimatedDocumentCount() 方法
  */
 
+const { convertObjectIdStrings } = require('../../utils/objectid-converter');
+
 /**
  * 创建 count 查询操作
  * @param {Object} context - 上下文对象
@@ -28,11 +30,19 @@ function createCountOps(context) {
          * @returns {Promise<number>} 匹配的文档数量；当 explain=true 时返回执行计划对象
          */
         count: async (query = {}, options = {}) => {
+            // ✅ v1.3.0: 自动转换 ObjectId 字符串
+            const convertedQuery = convertObjectIdStrings(query, 'query', 0, new WeakSet(), {
+                logger: context.logger,
+                excludeFields: context.autoConvertConfig?.excludeFields,
+                customFieldPatterns: context.autoConvertConfig?.customFieldPatterns,
+                maxDepth: context.autoConvertConfig?.maxDepth
+            });
+
             const { maxTimeMS = defaults.maxTimeMS, explain, comment } = options;
 
             // 如果启用 explain，直接返回查询执行计划（不缓存）
             if (explain) {
-                const verbosity = typeof explain === "string" ? explain : "queryPlanner";
+                const verbosity = typeof explain === 'string' ? explain : 'queryPlanner';
                 const isEmptyQuery = !query || Object.keys(query).length === 0;
 
                 if (isEmptyQuery) {
@@ -44,7 +54,7 @@ function createCountOps(context) {
                     };
                 } else {
                     // countDocuments 通过聚合管道实现，使用 aggregate 获取 explain
-                    const pipeline = [{ $match: query }, { $count: "total" }];
+                    const pipeline = [{ $match: convertedQuery }, { $count: 'total' }];
                     const aggOpts = {
                         maxTimeMS,
                         ...(options.hint && { hint: options.hint }),
@@ -56,11 +66,11 @@ function createCountOps(context) {
             }
 
             // 性能优化：判断是否为空查询
-            const isEmptyQuery = !query || Object.keys(query).length === 0;
+            const isEmptyQuery = !convertedQuery || Object.keys(convertedQuery).length === 0;
 
             return run(
-                "count",
-                { query, ...options },
+                'count',
+                { query: convertedQuery, ...options },
                 () => {
                     if (isEmptyQuery) {
                         // 空查询使用 estimatedDocumentCount（快速，基于集合元数据）
@@ -77,7 +87,7 @@ function createCountOps(context) {
                             ...(options.limit && { limit: options.limit })
                         };
                         if (comment) countOpts.comment = comment;
-                        return collection.countDocuments(query, countOpts);
+                        return collection.countDocuments(convertedQuery, countOpts);
                     }
                 }
             );

package/lib/mongodb/queries/distinct.js

@@ -3,6 +3,8 @@
  * @description 提供字段去重查询功能，使用 MongoDB 原生 distinct() 方法
  */
 
+const { convertObjectIdStrings } = require('../../utils/objectid-converter');
+
 /**
  * 创建 distinct 查询操作
  * @param {Object} context - 上下文对象
@@ -26,6 +28,13 @@ function createDistinctOps(context) {
          * @returns {Promise<Array>} 返回去重后的值数组；当 explain=true 时返回执行计划对象
          */
         distinct: async (field, query = {}, options = {}) => {
+            // ✅ v1.3.0: 自动转换 ObjectId 字符串
+            const convertedQuery = convertObjectIdStrings(query, 'query', 0, new WeakSet(), {
+                logger: context.logger,
+                excludeFields: context.autoConvertConfig?.excludeFields,
+                customFieldPatterns: context.autoConvertConfig?.customFieldPatterns,
+                maxDepth: context.autoConvertConfig?.maxDepth
+            });
             const {
                 maxTimeMS = defaults.maxTimeMS,
                 collation,
@@ -41,11 +50,11 @@ function createDistinctOps(context) {
             // 如果启用 explain，通过 aggregate 模拟 distinct 并返回执行计划
             // 注意：MongoDB 原生 distinct 命令不支持 explain，需要通过聚合管道模拟
             if (explain) {
-                const verbosity = typeof explain === "string" ? explain : "queryPlanner";
+                const verbosity = typeof explain === 'string' ? explain : 'queryPlanner';
                 // distinct 命令通过聚合管道模拟：$match + $group
                 const pipeline = [];
-                if (query && Object.keys(query).length > 0) {
-                    pipeline.push({ $match: query });
+                if (convertedQuery && Object.keys(convertedQuery).length > 0) {
+                    pipeline.push({ $match: convertedQuery });
                 }
                 pipeline.push({ $group: { _id: `$${field}` } });
 
@@ -57,9 +66,9 @@ function createDistinctOps(context) {
             }
 
             return run(
-                "distinct",
-                { field, query, ...options },
-                () => collection.distinct(field, query, driverOpts)
+                'distinct',
+                { field, query: convertedQuery, ...options },
+                () => collection.distinct(field, convertedQuery, driverOpts)
             );
         }
     };

package/lib/mongodb/queries/find-and-count.js

@@ -4,6 +4,7 @@
  */
 
 const { createError, ErrorCodes } = require('../../errors');
+const { convertObjectIdStrings } = require('../../utils/objectid-converter');
 
 /**
  * 创建 findAndCount 操作
@@ -70,6 +71,14 @@ function createFindAndCountOps(context) {
             query = {};
         }
 
+        // ✅ v1.3.0: 自动转换 ObjectId 字符串
+        const convertedQuery = convertObjectIdStrings(query, 'query', 0, new WeakSet(), {
+            logger: context.logger,
+            excludeFields: context.autoConvertConfig?.excludeFields,
+            customFieldPatterns: context.autoConvertConfig?.customFieldPatterns,
+            maxDepth: context.autoConvertConfig?.maxDepth
+        });
+
         // 2. 提取选项
         const projection = options.projection;
         const sort = options.sort;
@@ -80,7 +89,7 @@ function createFindAndCountOps(context) {
         const comment = options.comment;
 
         // 3. 缓存键（包含 query, projection, sort, limit, skip）
-        const cacheKey = cache ? `${instanceId}:${type}:${effectiveDbName}:${collection.collectionName}:findAndCount:${JSON.stringify({ query, projection, sort, limit, skip })}` : null;
+        const cacheKey = cache ? `${instanceId}:${type}:${effectiveDbName}:${collection.collectionName}:findAndCount:${JSON.stringify({ query: convertedQuery, projection, sort, limit, skip })}` : null;
 
         // 4. 检查缓存
         if (cache && cacheTime > 0) {
@@ -90,7 +99,7 @@ function createFindAndCountOps(context) {
                 if (cached !== null && cached !== undefined) {
                     logger?.debug?.('[findAndCount] 缓存命中', {
                         ns: `${effectiveDbName}.${collection.collectionName}`,
-                        query: query
+                        query
                     });
                     return cached;
                 }
@@ -117,8 +126,8 @@ function createFindAndCountOps(context) {
         let data, total;
         try {
             [data, total] = await Promise.all([
-                collection.find(query, findOptions).toArray(),
-                collection.countDocuments(query, countOptions)
+                collection.find(convertedQuery, findOptions).toArray(),
+                collection.countDocuments(convertedQuery, countOptions)
             ]);
         } catch (error) {
             throw error;
@@ -146,17 +155,17 @@ function createFindAndCountOps(context) {
                     operation: 'findAndCount',
                     durationMs: duration,
                     iid: instanceId,
-                    type: type,
+                    type,
                     db: effectiveDbName,
                     collection: collection.collectionName,
                     dataCount: data.length,
-                    total: total,
+                    total,
                     query: mongoSlowLogShaper?.sanitize ? mongoSlowLogShaper.sanitize(query) : query,
-                    projection: projection,
-                    sort: sort,
-                    limit: limit,
-                    skip: skip,
-                    comment: comment
+                    projection,
+                    sort,
+                    limit,
+                    skip,
+                    comment
                 };
                 logger?.warn?.('🐌 Slow query: findAndCount', meta);
                 emit?.('slow-query', meta);
@@ -168,9 +177,9 @@ function createFindAndCountOps(context) {
         // 10. 日志记录
         logger?.debug?.('[findAndCount] 查询完成', {
             ns: `${effectiveDbName}.${collection.collectionName}`,
-            duration: duration,
+            duration,
             dataCount: data.length,
-            total: total
+            total
         });
 
         return result;

package/lib/mongodb/queries/find-by-ids.js

@@ -178,16 +178,16 @@ function createFindByIdsOps(context) {
                     operation: 'findByIds',
                     durationMs: duration,
                     iid: instanceId,
-                    type: type,
+                    type,
                     db: effectiveDbName,
                     collection: collection.collectionName,
                     idsCount: ids.length,
                     uniqueCount: uniqueIds.length,
                     resultCount: results.length,
                     query: mongoSlowLogShaper?.sanitize ? mongoSlowLogShaper.sanitize(query) : query,
-                    projection: projection,
-                    sort: sort,
-                    comment: comment
+                    projection,
+                    sort,
+                    comment
                 };
                 logger?.warn?.('🐌 Slow query: findByIds', meta);
                 emit?.('slow-query', meta);
@@ -199,7 +199,7 @@ function createFindByIdsOps(context) {
         // 12. 日志记录
         logger?.debug?.('[findByIds] 查询完成', {
             ns: `${effectiveDbName}.${collection.collectionName}`,
-            duration: duration,
+            duration,
             idsCount: ids.length,
             uniqueCount: uniqueIds.length,
             resultCount: results.length

package/lib/mongodb/queries/find-one-by-id.js

@@ -96,7 +96,7 @@ function createFindOneByIdOps(context) {
                 // 拒绝其他类型（包括数字、对象等）
                 throw createError(
                     ErrorCodes.INVALID_ARGUMENT,
-                    `id 必须是字符串或 ObjectId 实例`,
+                    'id 必须是字符串或 ObjectId 实例',
                     [{
                         field: 'id',
                         type: 'type',

package/lib/mongodb/queries/find-one.js

@@ -4,6 +4,7 @@
  */
 
 const { normalizeProjection, normalizeSort } = require('../../common/normalize');
+const { convertObjectIdStrings } = require('../../utils/objectid-converter');
 
 /**
  * 创建 findOne 查询操作
@@ -30,6 +31,14 @@ function createFindOneOps(context) {
          * @returns {Promise<Object|null>} 返回匹配的第一条记录对象，未找到时返回null；当 explain=true 时返回执行计划
          */
         findOne: async (query = {}, options = {}) => {
+            // ✅ v1.3.0: 自动转换 ObjectId 字符串
+            const convertedQuery = convertObjectIdStrings(query, 'query', 0, new WeakSet(), {
+                logger: context.logger,
+                excludeFields: context.autoConvertConfig?.excludeFields,
+                customFieldPatterns: context.autoConvertConfig?.customFieldPatterns,
+                maxDepth: context.autoConvertConfig?.maxDepth
+            });
+
             options.projection = normalizeProjection(options.projection);
             const {
                 projection,
@@ -45,14 +54,14 @@ function createFindOneOps(context) {
             // 如果启用 explain，直接返回执行计划（不缓存）
             if (explain) {
                 const verbosity = typeof explain === 'string' ? explain : 'queryPlanner';
-                const cursor = collection.find(query, driverOpts).limit(1);
+                const cursor = collection.find(convertedQuery, driverOpts).limit(1);
                 return await cursor.explain(verbosity);
             }
 
             return run(
                 'findOne',
-                { query, ...options },
-                () => collection.findOne(query, driverOpts)
+                { query: convertedQuery, ...options },
+                () => collection.findOne(convertedQuery, driverOpts)
             );
         }
     };

package/lib/mongodb/queries/find-page.js

@@ -11,6 +11,7 @@ const { decodeCursor } = require('../../common/cursor');
 const { validateLimitAfterBefore, assertCursorSortCompatible } = require('../../common/validation');
 const { makePageResult } = require('../../common/page-result');
 const { normalizeSort } = require('../../common/normalize');
+const { convertObjectIdStrings } = require('../../utils/objectid-converter');
 
 // —— Count 队列支持（高并发控制）——
 let countQueue = null;
@@ -213,6 +214,17 @@ function createFindPage(ctx) {
 
     return async function findPage(options = {}) {
         const startTime = Date.now(); // 记录开始时间
+
+        // ✅ v1.3.0: 自动转换 ObjectId 字符串
+        if (options.query) {
+            options.query = convertObjectIdStrings(options.query, 'filter', 0, new WeakSet(), {
+                logger: ctx.logger,
+                excludeFields: ctx.autoConvertConfig?.excludeFields,
+                customFieldPatterns: ctx.autoConvertConfig?.customFieldPatterns,
+                maxDepth: ctx.autoConvertConfig?.maxDepth
+            });
+        }
+
         const MAX_LIMIT = defaults?.findPageMaxLimit ?? 500;
         // 基础校验：limit + after/before 互斥
         validateLimitAfterBefore(options, { maxLimit: MAX_LIMIT });