monsqlize 1.1.8 → 1.2.0

package/CHANGELOG.md

@@ -1,7 +1,7 @@
 # 变更日志 (CHANGELOG)
 
 > **说明**: 版本概览摘要，详细变更见 [changelogs/](./changelogs/) 目录  
-> **最后更新**: 2026-03-16
+> **最后更新**: 2026-04-13
 
 ---
 
@@ -9,6 +9,8 @@
 
 | 版本 | 日期 | 变更摘要 | 详细 |
 |------|------|---------|------|
+| [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) |
 | [v1.1.4](./changelogs/v1.1.4.md) | 2026-02-09 | 🎉 重大功能：通用函数缓存 - 52个测试 (100%通过) + 多层缓存 delPattern 修复 | [查看](./changelogs/v1.1.4.md) |

package/lib/connect.js

@@ -1,99 +1,99 @@
-/**
- * 数据库连接管理器
- * 统一管理各种数据库的连接创建和实例化逻辑
- */
-const Mongo = require("./mongodb");
-
-module.exports = class ConnectionManager {
-  /**
-   * 支持的数据库类型映射
-   */
-  static get SUPPORTED_DATABASES() {
-    return {
-      mongodb: Mongo,
-    };
-  }
-
-  /**
-   * 创建数据库实例
-   * @param {string} type - 数据库类型
-   * @param {string} databaseName - 数据库名称
-   * @param {Object} cache - 缓存实例（内存缓存）
-   * @param {Object} logger - 日志记录器
-   * @param {Object} [defaults] - 统一默认配置（如 maxTimeMS、namespace）
-   * @returns {Object} 数据库实例
-   * @throws {Error} 当数据库类型不支持或未实现时抛出错误
-   */
-  static createInstance(type, databaseName, cache, logger, defaults) {
-    const SUPPORTED_DATABASES = this.SUPPORTED_DATABASES;
-    // 验证数据库类型是否支持
-    if (!(type in SUPPORTED_DATABASES)) {
-      const supportedTypes = Object.keys(SUPPORTED_DATABASES).join(", ");
-      throw new Error(
-        `Invalid database type: ${type}. Supported types are: ${supportedTypes}`,
-      );
-    }
-
-    // 检查是否已实现
-    if (SUPPORTED_DATABASES[type] === null) {
-      throw new Error(`${type} support not implemented yet`);
-    }
-
-    // 获取对应的数据库类
-    const DatabaseClass = SUPPORTED_DATABASES[type];
-
-    // 创建并返回实例
-    return new DatabaseClass(type, databaseName, cache, logger, defaults);
-  }
-
-  /**
-   * 连接数据库
-   * @param {string} type - 数据库类型
-   * @param {string} databaseName - 数据库名称
-   * @param {Object} config - 数据库连接配置
-   * @param {Object} cache - 缓存实例
-   * @param {Object} logger - 日志记录器
-   * @param {Object} [defaults] - 统一默认配置（如 maxTimeMS、namespace）
-   * @param {Object} [poolManager] - 多连接池管理器（v1.0.8+）
-   * @returns {{accessor: Function, instance: Object}} 访问器与底层适配器实例
-   * @throws {Error} 连接失败时抛出错误
-   */
-  static async connect(
-    type,
-    databaseName,
-    config,
-    cache,
-    logger,
-    defaults,
-    poolManager,
-  ) {
-    // 创建数据库实例
-    const instance = this.createInstance(
-      type,
-      databaseName,
-      cache,
-      logger,
-      defaults,
-    );
-
-    // 🆕 v1.0.8: 传递 poolManager 给实例
-    if (poolManager) {
-      instance.poolManager = poolManager;
-    }
-
-    // 建立连接
-    await instance.connect(config);
-
-    // ---------- 构建访问器 ----------
-    const collection = (collectionName) =>
-      instance.collection(databaseName, collectionName);
-    const db = (databaseName) => {
-      return {
-        collection: (collectionName) =>
-          instance.collection(databaseName, collectionName),
-      };
-    };
-
-    return { collection, db, use: db, instance };
-  }
-};
+/**
+ * 数据库连接管理器
+ * 统一管理各种数据库的连接创建和实例化逻辑
+ */
+const Mongo = require("./mongodb");
+
+module.exports = class ConnectionManager {
+  /**
+   * 支持的数据库类型映射
+   */
+  static get SUPPORTED_DATABASES() {
+    return {
+      mongodb: Mongo,
+    };
+  }
+
+  /**
+   * 创建数据库实例
+   * @param {string} type - 数据库类型
+   * @param {string} databaseName - 数据库名称
+   * @param {Object} cache - 缓存实例（内存缓存）
+   * @param {Object} logger - 日志记录器
+   * @param {Object} [defaults] - 统一默认配置（如 maxTimeMS、namespace）
+   * @returns {Object} 数据库实例
+   * @throws {Error} 当数据库类型不支持或未实现时抛出错误
+   */
+  static createInstance(type, databaseName, cache, logger, defaults) {
+    const SUPPORTED_DATABASES = this.SUPPORTED_DATABASES;
+    // 验证数据库类型是否支持
+    if (!(type in SUPPORTED_DATABASES)) {
+      const supportedTypes = Object.keys(SUPPORTED_DATABASES).join(", ");
+      throw new Error(
+        `Invalid database type: ${type}. Supported types are: ${supportedTypes}`,
+      );
+    }
+
+    // 检查是否已实现
+    if (SUPPORTED_DATABASES[type] === null) {
+      throw new Error(`${type} support not implemented yet`);
+    }
+
+    // 获取对应的数据库类
+    const DatabaseClass = SUPPORTED_DATABASES[type];
+
+    // 创建并返回实例
+    return new DatabaseClass(type, databaseName, cache, logger, defaults);
+  }
+
+  /**
+   * 连接数据库
+   * @param {string} type - 数据库类型
+   * @param {string} databaseName - 数据库名称
+   * @param {Object} config - 数据库连接配置
+   * @param {Object} cache - 缓存实例
+   * @param {Object} logger - 日志记录器
+   * @param {Object} [defaults] - 统一默认配置（如 maxTimeMS、namespace）
+   * @param {Object} [poolManager] - 多连接池管理器（v1.0.8+）
+   * @returns {{accessor: Function, instance: Object}} 访问器与底层适配器实例
+   * @throws {Error} 连接失败时抛出错误
+   */
+  static async connect(
+    type,
+    databaseName,
+    config,
+    cache,
+    logger,
+    defaults,
+    poolManager,
+  ) {
+    // 创建数据库实例
+    const instance = this.createInstance(
+      type,
+      databaseName,
+      cache,
+      logger,
+      defaults,
+    );
+
+    // 🆕 v1.0.8: 传递 poolManager 给实例
+    if (poolManager) {
+      instance.poolManager = poolManager;
+    }
+
+    // 建立连接
+    await instance.connect(config);
+
+    // ---------- 构建访问器 ----------
+    const collection = (collectionName) =>
+      instance.collection(databaseName, collectionName);
+    const db = (databaseName) => {
+      return {
+        collection: (collectionName) =>
+          instance.collection(databaseName, collectionName),
+      };
+    };
+
+    return { collection, db, use: db, instance };
+  }
+};

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/lib/multi-level-cache.js

@@ -16,8 +16,12 @@ class MultiLevelCache {
    * @param {Object} [options.policy]
    * @param {'both'|'local-first-async-remote'} [options.policy.writePolicy='both']
    * @param {boolean} [options.policy.backfillLocalOnRemoteHit=true]
+   * @param {number} [options.policy.backfillLocalTTL=0] - 回填 L1 时使用的兜底 TTL（毫秒）；
+   *   当 remote 支持 getWithTTL 时优先使用 L2 剩余 TTL，否则降级到此值；
+   *   0 = 不设 TTL（永不过期，向后兼容）。建议生产环境配置合理值（如 60000）
    * @param {number} [options.remoteTimeoutMs=50] - 远端单次操作超时
    * @param {(msg:object)=>void} [options.publish] - 可选：失效广播发布器
+   * @since 1.1.9 backfillLocalTTL 支持
    */
   constructor(options = {}) {
     const { local, remote, policy = {}, remoteTimeoutMs = 50, publish } = options;
@@ -29,6 +33,8 @@ class MultiLevelCache {
     this.policy = {
       writePolicy: policy.writePolicy || 'both',
       backfillLocalOnRemoteHit: policy.backfillLocalOnRemoteHit !== false,
+      // 🔧 v1.1.9 修复：新增回填 TTL 兜底配置，0 = 不设 TTL（向后兼容）
+      backfillLocalTTL: typeof policy.backfillLocalTTL === 'number' ? policy.backfillLocalTTL : 0,
     };
     this.remoteTimeoutMs = Number(remoteTimeoutMs) || 50;
     this.publish = typeof publish === 'function' ? publish : null;
@@ -74,13 +80,30 @@ class MultiLevelCache {
     const v = await this.local.get(key);
     if (v !== undefined) return v;
     try {
-      const r = await this._withTimeout(this.remote.get(key));
+      let r;
+      // 🔧 v1.1.9 修复：backfillTTL 优先取 L2 剩余 TTL（方案A），降级到 backfillLocalTTL（方案B）
+      let backfillTTL = this.policy.backfillLocalTTL;
+
+      if (this.remote && typeof this.remote.getWithTTL === 'function') {
+        // 方案A：remote 支持 getWithTTL，单次 RTT 同时获取值与剩余 TTL
+        const meta = await this._withTimeout(this.remote.getWithTTL(key));
+        if (meta !== undefined) {
+          r = meta.value;
+          if (meta.remainingTTL > 0) backfillTTL = meta.remainingTTL;
+        }
+      } else {
+        // 方案B：remote 不支持 getWithTTL，使用普通 get + backfillLocalTTL 兜底
+        r = await this._withTimeout(this.remote.get(key));
+      }
+
       if (r !== undefined && this.policy.backfillLocalOnRemoteHit) {
-        // 无剩余 TTL 信息，采用一个保守的回填策略：原 TTL 由上层 set 决定；这里回填一个短 TTL（例如 50ms）不合适
-        // 因为我们无法得知原始 TTL，这里直接不设置 TTL（等同于本地不持久）。但为了可用性，设置 50% 的常用短 TTL可配置。
-        // 为保持简单，我们不传 TTL（由本地实现解释，等价于无过期）。
-        // 若调用方强依赖 TTL 严格一致性，应在远端适配器中扩展 getWithTTL。
-        try { await this.local.set(key, r); } catch(_) {}
+        // 🔧 v1.1.9 补充：backfillTTL=0 时跳过 null 回填，防止无配置用户触发永久驻留 Bug
+        // - backfillTTL>0：回填所有值（含 null），TTL 保护下能正常过期
+        // - backfillTTL=0 + null：跳过——无 TTL 保护的 null 永久驻留 = Bug 本身
+        // - backfillTTL=0 + 非 null：回填（保留原有永久缓存行为，向后兼容）
+        if (backfillTTL > 0 || r !== null) {
+          try { await this.local.set(key, r, backfillTTL); } catch(_) {}
+        }
       }
       return r;
     } catch(_) {
@@ -128,8 +151,16 @@ class MultiLevelCache {
     try {
       const remoteRes = await this._withTimeout(this.remote.getMany(misses));
       if (remoteRes && typeof remoteRes === 'object') {
-        // 回填本地（异步）
-        if (this.policy.backfillLocalOnRemoteHit) this.local.setMany(remoteRes).catch(() => {});
+        // 🔧 v1.1.9 修复：传入 backfillLocalTTL，防止无 TTL 永久回填（含 null 值）
+        // 🔧 v1.1.9 补充：backfillLocalTTL=0 时过滤 null，防止无配置用户触发永久驻留 Bug
+        if (this.policy.backfillLocalOnRemoteHit) {
+          const backfillData = this.policy.backfillLocalTTL > 0
+            ? remoteRes
+            : Object.fromEntries(Object.entries(remoteRes).filter(([, v]) => v !== null));
+          if (Object.keys(backfillData).length > 0) {
+            this.local.setMany(backfillData, this.policy.backfillLocalTTL).catch(() => {});
+          }
+        }
         for (const k of misses) { if (remoteRes[k] !== undefined) out[k] = remoteRes[k]; }
       }
     } catch(_) { /* 降级 */ }

package/lib/redis-cache-adapter.js

@@ -60,6 +60,35 @@ function createRedisCacheAdapter(redisUrlOrInstance) {
             }
         },
 
+        /**
+         * 获取单个缓存值及剩余 TTL（毫秒），供 MultiLevelCache L2→L1 回填时携带正确 TTL
+         * 使用 pipeline（GET + PTTL）单次 RTT，避免额外网络开销
+         * @param {string} key
+         * @returns {Promise<{value: any, remainingTTL: number}|undefined>}
+         *   key 不存在返回 undefined；value 为 null 时表示缓存了空结果
+         * @since 1.1.9
+         */
+        async getWithTTL(key) {
+            try {
+                const [[, rawVal], [, pttl]] = await redis.pipeline().get(key).pttl(key).exec();
+                // PTTL = -2 表示 key 不存在
+                if (pttl === -2) return undefined;
+                let value;
+                try {
+                    value = JSON.parse(rawVal);
+                } catch (_) {
+                    return undefined;
+                }
+                return {
+                    value,
+                    // PTTL = -1 表示永不过期，映射为 0（与 backfillLocalTTL=0 语义一致）
+                    remainingTTL: pttl > 0 ? pttl : 0,
+                };
+            } catch (_) {
+                return undefined;
+            }
+        },
+
         /**
          * 设置单个缓存值
          * @param {string} key