monsqlize 1.1.9 → 1.2.1

package/CHANGELOG.md

@@ -1,7 +1,7 @@
 # 变更日志 (CHANGELOG)
 
 > **说明**: 版本概览摘要，详细变更见 [changelogs/](./changelogs/) 目录  
-> **最后更新**: 2026-04-02
+> **最后更新**: 2026-04-13
 
 ---
 
@@ -9,6 +9,8 @@
 
 | 版本 | 日期 | 变更摘要 | 详细 |
 |------|------|---------|------|
+| [v1.2.1](./changelogs/v1.2.1.md) | 2026-04-13 | 🐛 **Bug 修复**：`msq.model()` 实例缓存 + 索引去重 + 死代码清理 + `types/monsqlize.ts` 补全 `model()` / `collection()` 类型 | [查看](./changelogs/v1.2.1.md) |
+| [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/index.js

@@ -678,7 +678,10 @@ module.exports = class {
   }
 
   /**
-   * 获取 Model 实例
+   * 获取 Model 实例（缓存复用）
+   *
+   * 同一 collectionName 多次调用返回同一实例。
+   * Model.redefine() / Model.undefine() 后自动失效，close() 后全部清空。
    *
    * @param {string} collectionName - 集合名称
    * @returns {ModelInstance} Model 实例
@@ -710,8 +713,19 @@ module.exports = class {
       throw err;
     }
 
-    // 检查 Model 是否已定义
     const Model = require("./model");
+
+    // 缓存命中 + redefine 失效检查
+    if (this._modelInstances && this._modelInstances.has(collectionName)) {
+      if (!Model._redefinedNames.has(collectionName)) {
+        return this._modelInstances.get(collectionName);
+      }
+      // redefine 后需要重建实例
+      this._modelInstances.delete(collectionName);
+      Model._redefinedNames.delete(collectionName);
+    }
+
+    // 检查 Model 是否已定义
     if (!Model.has(collectionName)) {
       const err = new Error(
         `Model '${collectionName}' is not defined. Call Model.define() first.`,
@@ -726,9 +740,13 @@ module.exports = class {
     // 获取 collection 实例
     const collection = this.dbInstance.collection(collectionName);
 
-    // 创建 ModelInstance
-    const ModelInstanceClass = require("./model").ModelInstance;
-    return new ModelInstanceClass(collection, modelDef.definition, this);
+    // 创建 ModelInstance 并缓存
+    const instance = new Model.ModelInstance(collection, modelDef.definition, this);
+
+    if (!this._modelInstances) this._modelInstances = new Map();
+    this._modelInstances.set(collectionName, instance);
+
+    return instance;
   }
 
   /**
@@ -1007,6 +1025,12 @@ module.exports = class {
     this.dbInstance = null;
     this._connecting = null;
 
+    // 清理 ModelInstance 缓存
+    if (this._modelInstances) {
+      this._modelInstances.clear();
+      this._modelInstances = null;
+    }
+
     return null;
   }
 };

package/lib/model/index.js

@@ -58,6 +58,14 @@ class Model {
    */
   static _registry = new Map();
 
+  /**
+   * 已被 redefine 的 collectionName 集合（用于缓存失效通知）
+   * @private
+   * @type {Set<string>}
+   * @since 1.2.1
+   */
+  static _redefinedNames = new Set();
+
   /**
    * 定义并注册 Model
    *
@@ -396,6 +404,8 @@ class Model {
    * @since 1.1.7
    */
   static undefine(collectionName) {
+    // 标记需要缓存失效（MonSQLize.model() 检查此标记）
+    this._redefinedNames.add(collectionName);
     return this._registry.delete(collectionName);
   }
 
@@ -434,6 +444,8 @@ class Model {
   static redefine(collectionName, definition) {
     this.undefine(collectionName);
     this.define(collectionName, definition);
+    // 标记需要缓存失效（MonSQLize.model() 检查此标记）
+    this._redefinedNames.add(collectionName);
   }
 
   /**
@@ -443,6 +455,7 @@ class Model {
    */
   static _clear() {
     this._registry.clear();
+    this._redefinedNames.clear();
   }
 }
 
@@ -662,38 +675,6 @@ class ModelInstance {
     }
   }
 
-  /**
-   * 创建索引
-   *
-   * @private
-   * @returns {Promise<void>}
-   */
-  async _createIndexes() {
-    if (!Array.isArray(this.indexes) || this.indexes.length === 0) {
-      return;
-    }
-
-    try {
-      // 使用 createIndexes 批量创建索引
-      await this.collection.createIndexes(this.indexes);
-
-      if (this.msq && this.msq.logger) {
-        this.msq.logger.info(
-          `[Model] Created ${this.indexes.length} index(es) for ${this.collection.collectionName}`,
-        );
-      }
-    } catch (err) {
-      // 索引创建失败仅记录警告
-      if (this.msq && this.msq.logger) {
-        this.msq.logger.warn(
-          `[Model] Failed to create indexes for ${this.collection.collectionName}:`,
-          err.message,
-        );
-      }
-      throw err;
-    }
-  }
-
   /**
    * 将实例方法注入到文档对象
    *

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.1",
   "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/monsqlize.ts

@@ -4,12 +4,13 @@
  */
 
 import type { TransactionOptions } from './options';
-import type { DbAccessor, HealthView } from './collection';
+import type { DbAccessor, HealthView, Collection } from './collection';
 import type { CacheLike } from './cache';
 import type { Transaction } from './transaction';
 import type { Lock, LockOptions } from './lock';
 import type { ExpressionFunction } from './base';
 import type { MetaInfo } from './pagination';
+import type { ModelInstance } from './model';
 
 /**
  * MonSQLize 主类
@@ -46,6 +47,29 @@ export interface MonSQLize {
      */
     health(): Promise<HealthView>;
 
+    /**
+     * 获取 Model 实例（缓存复用）
+     *
+     * 同一 collectionName 多次调用返回同一实例。
+     * Model.redefine() / Model.undefine() 后自动失效，close() 后全部清空。
+     *
+     * @param collectionName - 已注册的集合名称
+     * @returns ModelInstance 实例
+     * @throws 数据库未连接（NOT_CONNECTED）
+     * @throws Model 未定义（MODEL_NOT_DEFINED）
+     * @since 1.0.3
+     */
+    model(collectionName: string): ModelInstance;
+
+    /**
+     * 获取原始集合实例
+     *
+     * @param collectionName - 集合名称
+     * @returns Collection 实例
+     * @throws 数据库未连接（NOT_CONNECTED）
+     */
+    collection(collectionName: string): Collection;
+
 
     // ============================================================================
     // 事件系统

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 起正式支持。
+    // 排序字段会被自动保留以确保游标正确生成。
 }
 
 /**