monsqlize 1.1.9 → 1.2.0

package/CHANGELOG.md

@@ -1,7 +1,7 @@
 # 变更日志 (CHANGELOG)
 
 > **说明**: 版本概览摘要，详细变更见 [changelogs/](./changelogs/) 目录  
-> **最后更新**: 2026-04-02
+> **最后更新**: 2026-04-13
 
 ---
 
@@ -9,6 +9,7 @@
 
 | 版本 | 日期 | 变更摘要 | 详细 |
 |------|------|---------|------|
+| [v1.2.0](./changelogs/v1.2.0.md) | 2026-04-13 | 🐛 **Bug 修复 + 新功能**：`findPage` 正式支持 `projection` 投影参数（修复静默忽略问题）+ 有效投影策略自动保护游标排序字段 + 8 个测试用例 | [查看](./changelogs/v1.2.0.md) |
 | [v1.1.9](./changelogs/v1.1.9.md) | 2026-04-02 | 🚨 **P1 Bug 修复**：MultiLevelCache L2→L1 回填 TTL 缺失（null 永久驻留 L1）+ 新增 `backfillLocalTTL` 配置 + Redis `getWithTTL` 方法 + 14 个回归测试 | [查看](./changelogs/v1.1.9.md) |
 | [v1.1.8](./changelogs/v1.1.8.md) | 2026-03-16 | 🆕 **新功能**：Model 热重载支持（`undefine()` + `redefine()` + `_loadModels` reload 模式）+ 22个测试 (100%通过) | [查看](./changelogs/v1.1.8.md) |
 | [v1.1.6](./changelogs/v1.1.6.md) | 2026-02-11 | 🎉 **重大功能**：精准缓存失效机制 + 🚨 upsert 缓存失效 Bug 修复 + 36个测试 (100%通过) | [查看](./changelogs/v1.1.6.md) |

package/lib/mongodb/common/agg-pipeline.js

@@ -16,15 +16,18 @@ const { reverseSort } = require('./sort');
  * @param {{a:object,s:object}|null} [params.cursor] - 解析后的游标对象
  * @param {'after'|'before'|null} [params.direction]
  * @param {object[]} [params.lookupPipeline] - 页内联表等追加管道
+ * @param {Record<string,any>} [params.projection] - 已计算的有效投影（调用方负责保护排序字段）
  * @returns {object[]} 聚合管道数组
  */
-function buildPagePipelineA({ query = {}, sort, limit, cursor, direction, lookupPipeline = [] }) {
+function buildPagePipelineA({ query = {}, sort, limit, cursor, direction, lookupPipeline = [], projection }) {
     const pipeline = [];
     if (query && Object.keys(query).length) pipeline.push({ $match: query });
     if (cursor) pipeline.push({ $match: { $expr: buildLexiExpr(sort, cursor.a) } });
     pipeline.push({ $sort: sort });
     pipeline.push({ $limit: limit + 1 });
     if (lookupPipeline && lookupPipeline.length) pipeline.push(...lookupPipeline);
+    // 🆕 v1.2.0: 在 lookup 之后、方向恢复之前注入 $project（调用方已确保排序字段存在）
+    if (projection) pipeline.push({ $project: projection });
     if (direction === 'before') pipeline.push({ $sort: reverseSort(sort) });
     return pipeline;
 }

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

@@ -10,9 +10,40 @@ const { buildPagePipelineA } = require('../common/agg-pipeline');
 const { decodeCursor } = require('../../common/cursor');
 const { validateLimitAfterBefore, assertCursorSortCompatible } = require('../../common/validation');
 const { makePageResult } = require('../../common/page-result');
-const { normalizeSort } = require('../../common/normalize');
+const { normalizeSort, normalizeProjection } = require('../../common/normalize');
 const { convertObjectIdStrings } = require('../../utils/objectid-converter');
 
+// —— 有效投影计算 ——
+/**
+ * 计算有效投影：自动保护排序字段，确保游标锚点提取（pickAnchor）不受投影影响。
+ * - 包含型投影（所有非 _id 值均为 1/true）：强制追加排序字段（值为 1）
+ * - 排除型投影（含任意非 _id 字段值为 0/false）：从排除列表中移除排序字段
+ * @param {Record<string,any>|undefined} projection - normalizeProjection 归一化后的投影
+ * @param {Record<string,1|-1>} sort - 稳定排序（含 _id）
+ * @returns {Record<string,any>|undefined}
+ */
+function buildEffectiveProjection(projection, sort) {
+    if (!projection) return undefined;
+    const sortFields = Object.keys(sort || {});
+    // 判断排除型：任意非 _id 字段值为 0 或 false
+    const isExclusion = Object.entries(projection).some(([k, v]) => k !== '_id' && (v === 0 || v === false));
+    const effective = { ...projection };
+    if (isExclusion) {
+        // 排除型：取消对排序字段的排除，确保游标可用
+        for (const k of sortFields) {
+            if (effective[k] === 0 || effective[k] === false) {
+                delete effective[k];
+            }
+        }
+    } else {
+        // 包含型：强制包含排序字段
+        for (const k of sortFields) {
+            if (!effective[k]) effective[k] = 1;
+        }
+    }
+    return effective;
+}
+
 // —— Count 队列支持（高并发控制）——
 let countQueue = null;
 
@@ -160,13 +191,17 @@ function createFindPage(ctx) {
 
     async function doFindPageOne({ options, stableSort, direction, parsedCursor }) {
         const sortForQuery = direction === 'before' ? reverseSort(stableSort) : stableSort;
+        // 🆕 v1.2.0: 计算有效投影（自动保护排序字段，确保游标锚点可提取）
+        const normalizedProjection = normalizeProjection(options.projection);
+        const effectiveProjection = buildEffectiveProjection(normalizedProjection, stableSort);
         const pipeline = buildPagePipelineA({
             query: options.query || {},
             sort: sortForQuery,
             limit: options.limit,
             cursor: parsedCursor,
             direction,
-            lookupPipeline: options.pipeline || []
+            lookupPipeline: options.pipeline || [],
+            projection: effectiveProjection
         });
         const driverOpts = {
             maxTimeMS: options.maxTimeMS ?? defaults.maxTimeMS,
@@ -185,14 +220,15 @@ function createFindPage(ctx) {
         // 如果启用流式返回
         if (options.stream) {
             if (options.batchSize !== undefined) driverOpts.batchSize = options.batchSize;
-            // 流式查询：��应该用 limit+1，直接使用 limit
+            // 流式查询：不应该用 limit+1，直接使用 limit
             const streamPipeline = buildPagePipelineA({
                 query: options.query || {},
                 sort: sortForQuery,
                 limit: options.limit, // 注意：这里不加1
                 cursor: parsedCursor,
                 direction,
-                lookupPipeline: options.pipeline || []
+                lookupPipeline: options.pipeline || [],
+                projection: normalizedProjection  // 🆕 v1.2.0: 流式无需游标保护，使用原始投影
             });
             // 手动修改最后的 $limit 阶段，不使用 limit+1
             const limitStageIndex = streamPipeline.findIndex(stage => stage.$limit !== undefined);
@@ -396,6 +432,10 @@ function createFindPage(ctx) {
                 if (query && Object.keys(query).length) p.push({ $match: query });
                 p.push({ $sort: stableSort }, { $skip: skip }, { $limit: limit + 1 });
                 if (lookupPipeline?.length) p.push(...lookupPipeline);
+                // 🆕 v1.2.0: 支持 projection（同样保护排序字段）
+                const offsetNormalizedProj = normalizeProjection(options.projection);
+                const offsetEffectiveProj = buildEffectiveProjection(offsetNormalizedProj, stableSort);
+                if (offsetEffectiveProj) p.push({ $project: offsetEffectiveProj });
                 const driverOpts = {
                     maxTimeMS: options.maxTimeMS ?? defaults.maxTimeMS,
                     allowDiskUse: options.allowDiskUse,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "monsqlize",
-  "version": "1.1.9",
+  "version": "1.2.0",
   "description": "A lightweight MongoDB ORM with multi-level caching, transaction support, distributed features, Saga distributed transactions, unified expression system with 122 operators, and universal function caching (100% MongoDB support)",
   "main": "lib/index.js",
   "module": "index.mjs",

package/types/pagination.ts

@@ -61,6 +61,9 @@ export interface TotalsOptions {
  * 深度分页（统一版）选项
  */
 export interface FindPageOptions extends FindOptions {
+    /**
+     * 附加聚合管道（在 projection 之前执行，仅对当页数据生效）
+     */
     pipeline?: object[];
     after?: string;
     before?: string;
@@ -77,6 +80,8 @@ export interface FindPageOptions extends FindOptions {
     offsetJump?: OffsetJumpOptions;  // 小范围 offset 兜底
     totals?: TotalsOptions;          // 总数/总页数配置
     meta?: boolean | MetaOptions;    // 返回耗时元信息
+    // 注：projection 继承自 FindOptions，findPage 自 v1.2.0 起正式支持。
+    // 排序字段会被自动保留以确保游标正确生成。
 }
 
 /**