monsqlize 1.2.2 → 1.3.0

package/CHANGELOG.md

@@ -1,7 +1,7 @@
 # 变更日志 (CHANGELOG)
 
 > **说明**: 版本概览摘要，详细变更见 [changelogs/](./changelogs/) 目录  
-> **最后更新**: 2026-04-24
+> **最后更新**: 2026-04-27
 
 ---
 
@@ -9,6 +9,8 @@
 
 | 版本 | 日期 | 变更摘要 | 详细 |
 |------|------|---------|------|
+| [v1.3.0](./changelogs/v1.3.0.md) | 2026-04-27 | 🆕 **新功能**：链式池访问 API — `pool(name)` / `use(dbName)` / `scopedCollection()` / `scopedModel()` 四个公开方法，支持多连接池多数据库路由，connection 合并语义，TypeScript 类型签名完整覆盖 | [查看](./changelogs/v1.3.0.md) |
+| [v1.2.3](./changelogs/v1.2.3.md) | 2026-04-26 | 🐛 **Bug Fix**：`model()` 方法修复注册 key 直接作为 MongoDB 集合名的问题，优先读 `definition.collection > definition.name`，注册 key 仅作 fallback，向后兼容 | [查看](./changelogs/v1.2.3.md) |
 | [v1.2.2](./changelogs/v1.2.2.md) | 2026-04-24 | 🆕 **新功能**：Model 数据源绑定 — `connection: { pool?, database? }` 支持 Model 绑定指定连接池和/或数据库，四种组合路由，向后兼容；🐛 **Bug Fix**：修复 `Model._clear()` 导致 `msq.model()` 实例缓存失效失效，populate 关系丢失问题 | [查看](./changelogs/v1.2.2.md) |
 | [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) |

package/README.md

@@ -1465,27 +1465,27 @@ import type { Collection, MonSQLizeConfig } from 'monsqlize';
 ### 📦 MongoDB 原生功能
 
 ✅ **CRUD 操作**
-- find / findOne
-- insertOne / insertMany
-- updateOne / updateMany ⭐ (支持聚合管道 v1.0.8+)
-- deleteOne / deleteMany
-- replaceOne
-- findOneAndUpdate
-- findOneAndReplace
-- findOneAndDelete
+- [find](./docs/find.md) / [findOne](./docs/findOne.md)
+- [insertOne](./docs/insert-one.md) / [insertMany](./docs/insert-many.md)
+- [updateOne](./docs/update-one.md) / [updateMany](./docs/update-many.md) ⭐ (支持聚合管道 v1.0.8+)
+- [deleteOne](./docs/delete-one.md) / [deleteMany](./docs/delete-many.md)
+- [replaceOne](./docs/replace-one.md)
+- [findOneAndUpdate](./docs/find-one-and-update.md)
+- [findOneAndReplace](./docs/find-one-and-replace.md)
+- [findOneAndDelete](./docs/find-one-and-delete.md)
 
 ✅ **聚合 & 查询**
-- aggregate
-- count / distinct
-- watch (Change Streams)
-- explain
+- [aggregate](./docs/aggregate.md)
+- [count](./docs/count.md) / [distinct](./docs/distinct.md)
+- [watch (Change Streams)](./docs/watch.md)
+- [explain](./docs/explain.md)
 
 ✅ **索引管理**
 - createIndex / createIndexes
 - listIndexes
 - dropIndex / dropIndexes
 
-✅ **事务支持**
+✅ **[事务支持](./docs/transaction.md)**
 - withTransaction
 - startTransaction
 
@@ -1494,44 +1494,44 @@ import type { Collection, MonSQLizeConfig } from 'monsqlize';
 
 ### 🚀 增强功能
 
-✅ **企业级多连接池** (v1.0.8+)
+✅ **[企业级多连接池](./docs/multi-pool.md)** (v1.0.8+)
 - ConnectionPoolManager
 - 5种智能选择策略
 - 实时健康检查
 - 自动故障转移
 - 完整统计收集
 
-✅ **Saga 分布式事务** (v1.1.0 计划)
+✅ **[Saga 分布式事务](./docs/saga-transaction.md)** (v1.1.0 计划)
 - 跨服务事务（设计完成）
 - 自动补偿机制（设计完成）
 - 状态跟踪（设计完成）
 - 超时和重试（设计完成）
 
-✅ **智能缓存**
+✅ **[智能缓存](./docs/cache.md)**
 - TTL 过期策略
 - LRU 淘汰策略
 - 自动失效机制
 - 并发去重
-- 多层缓存 (内存+Redis)
+- [多层缓存 (内存+Redis)](./docs/cache-implementation.md)
 
 ✅ **便利方法**
-- findOneById
-- findByIds
-- upsertOne
-- incrementOne
-- findAndCount
+- [findOneById](./docs/find-one-by-id.md)
+- [findByIds](./docs/find-by-ids.md)
+- [upsertOne](./docs/upsert-one.md)
+- [incrementOne](./docs/increment-one.md)
+- [findAndCount](./docs/find-and-count.md)
 
 ✅ **性能优化**
-- insertBatch - 批量插入优化
-- deleteBatch - 批量删除（流式+进度监控）
-- updateBatch - 批量更新（流式+进度监控）
+- [insertBatch](./docs/insertBatch.md) - 批量插入优化
+- [deleteBatch](./docs/deleteBatch.md) - 批量删除（流式+进度监控）
+- [updateBatch](./docs/updateBatch.md) - 批量更新（流式+进度监控）
 - 只读事务优化
-- Count 队列控制
+- [Count 队列控制](./docs/count-queue.md)
 - 连接池管理
 
-✅ **分布式支持**
+✅ **[分布式支持](./docs/distributed-deployment.md)**
 - Redis 广播缓存失效
-- 分布式锁
+- [分布式锁](./docs/business-lock.md)
 - 多实例一致性
 
 </td>
@@ -1540,28 +1540,28 @@ import type { Collection, MonSQLizeConfig } from 'monsqlize';
 ### 🛠️ 企业级特性
 
 ✅ **运维监控**
-- 慢查询日志（支持持久化存储）🆕
+- [慢查询日志](./docs/slow-query-log.md)（支持持久化存储）🆕
 - 性能指标统计
 - 健康检查
 - 缓存命中率监控
 
-✅ **深度分页**
+✅ **[深度分页](./docs/findPage.md)**
 - 游标分页
 - 异步总数统计
-- 书签管理
+- [书签管理](./docs/bookmarks.md)
 - 跳页优化
 
 ✅ **数据库管理**
 - 跨库访问
-- Schema 验证
-- 集合管理
+- [Schema 验证](./docs/model.md)
+- [集合管理](./docs/collection-management.md)
 - 数据库命令
 
 ✅ **开发体验**
 - TypeScript 支持
-- 链式调用 API ⭐
+- [链式调用 API](./docs/chaining-api.md) ⭐
 - ESM/CommonJS 双模式
-- ObjectId 自动转换 ⭐
+- [ObjectId 自动转换](./docs/objectid-auto-convert.md) ⭐
 - 77% 测试覆盖率
 
 </td>

package/lib/index.js

@@ -737,11 +737,18 @@ module.exports = class {
     // 获取 Model 定义
     const modelDef = Model.get(collectionName);
 
+    // [v1.2.3 patch] 实际 MongoDB 集合名可能不同于注册 key
+    // 优先读 definition.collection > definition.name > key（fallback，向后兼容）
+    const actualCollectionName =
+      modelDef.definition.collection ||
+      modelDef.definition.name ||
+      collectionName;
+
     // 获取 collection 实例（v1.2.2+ 支持 connection 路由）
     const connection = modelDef.definition.connection;
     const collection = (connection && (connection.pool || connection.database))
-      ? this._resolveModelCollection(collectionName, connection)
-      : this.dbInstance.collection(collectionName);
+      ? this._resolveModelCollection(actualCollectionName, connection)
+      : this.dbInstance.collection(actualCollectionName);
 
     // 创建 ModelInstance 并缓存
     const instance = new Model.ModelInstance(collection, modelDef.definition, this);
@@ -823,6 +830,140 @@ module.exports = class {
     return this.dbInstance.collection(collectionName);
   }
 
+  // ============================================================
+  // v1.3.0 — scoped access APIs
+  // ============================================================
+
+  /**
+   * 获取限定池/库的 collection（公开底层方法）
+   *
+   * opts.pool / opts.database 均为可选；均不填时退化为默认路由。
+   *
+   * @param {string} collectionName
+   * @param {{ pool?: string, database?: string }} [opts={}]
+   * @returns {Object} Collection 实例
+   * @throws {Error} NOT_CONNECTED / NO_POOL_MANAGER / POOL_NOT_FOUND
+   * @since v1.3.0
+   */
+  scopedCollection(collectionName, opts = {}) {
+    if (!this.dbInstance) {
+      const err = new Error('Database is not connected. Call connect() first.');
+      err.code = 'NOT_CONNECTED';
+      throw err;
+    }
+    const { pool, database } = opts;
+    if (!pool && !database) {
+      return this.collection(collectionName);
+    }
+    return this._resolveModelCollection(collectionName, { pool, database });
+  }
+
+  /**
+   * 获取限定池/库的 Model 实例（公开底层方法，不走 _modelInstances 缓存）
+   *
+   * connection 合并语义：opts 字段优先，definition.connection 作 fallback。
+   * 例：billing/invoice.ts 有 connection:{database:'billing'}，
+   *   调用 scopedModel('BillingInvoice', { pool:'cn' }) →
+   *   merged = { database:'billing', pool:'cn' }，路由到 cn 池 billing 库。
+   *
+   * @param {string} key - 已注册的 Model key（或 alias）
+   * @param {{ pool?: string, database?: string }} [opts={}]
+   * @returns {ModelInstance}
+   * @throws {Error} NOT_CONNECTED / MODEL_NOT_DEFINED / NO_POOL_MANAGER / POOL_NOT_FOUND
+   * @since v1.3.0
+   */
+  scopedModel(key, opts = {}) {
+    if (!this.dbInstance) {
+      const err = new Error('Database is not connected. Call connect() first.');
+      err.code = 'NOT_CONNECTED';
+      throw err;
+    }
+    const Model = require('./model');
+    if (!Model.has(key)) {
+      const err = new Error(`Model '${key}' is not defined. Call Model.define() first.`);
+      err.code = 'MODEL_NOT_DEFINED';
+      throw err;
+    }
+    const modelDef = Model.get(key);
+    const actualCollectionName =
+      modelDef.definition.collection ||
+      modelDef.definition.name ||
+      key;
+    const merged = { ...(modelDef.definition.connection || {}), ...opts };
+    const { pool, database } = merged;
+    const collection = (pool || database)
+      ? this._resolveModelCollection(actualCollectionName, { pool, database })
+      : this.dbInstance.collection(actualCollectionName);
+    return new Model.ModelInstance(collection, modelDef.definition, this);
+  }
+
+  /**
+   * 获取指定连接池的链式访问器
+   *
+   * 前置校验（立即执行）：NOT_CONNECTED / NO_POOL_MANAGER / POOL_NOT_FOUND。
+   *
+   * @param {string} poolName - 连接池名称
+   * @returns {{ collection, model, use }} PoolAccessor 纯对象
+   * @throws {Error} NOT_CONNECTED / NO_POOL_MANAGER / POOL_NOT_FOUND
+   * @since v1.3.0
+   */
+  pool(poolName) {
+    if (!this.dbInstance) {
+      const err = new Error('Database is not connected. Call connect() first.');
+      err.code = 'NOT_CONNECTED';
+      throw err;
+    }
+    if (!this._poolManager) {
+      const err = new Error('No pool manager configured. Add pools to MonSQLize constructor options.');
+      err.code = 'NO_POOL_MANAGER';
+      throw err;
+    }
+    if (!this._poolManager._getPool(poolName)) {
+      const available = this._poolManager.getPoolNames?.() ?? [];
+      const err = new Error(`Pool '${poolName}' not found. Available pools: [${available.join(', ')}]`);
+      err.code = 'POOL_NOT_FOUND';
+      err.available = available;
+      throw err;
+    }
+    return {
+      collection: (name) =>
+        this.scopedCollection(name, { pool: poolName }),
+      model: (key) =>
+        this.scopedModel(key, { pool: poolName }),
+      use: (dbName) => ({
+        collection: (name) =>
+          this.scopedCollection(name, { pool: poolName, database: dbName }),
+        model: (key) =>
+          this.scopedModel(key, { pool: poolName, database: dbName }),
+      }),
+    };
+  }
+
+  /**
+   * 获取「默认池 + 指定库」访问器
+   *
+   * 适用于单连接多库场景（无需配置多连接池）。
+   * 只校验 NOT_CONNECTED，不涉及 poolManager。
+   *
+   * @param {string} dbName - 数据库名称
+   * @returns {{ collection, model }} ScopedAccessor 纯对象
+   * @throws {Error} NOT_CONNECTED
+   * @since v1.3.0
+   */
+  use(dbName) {
+    if (!this.dbInstance) {
+      const err = new Error('Database is not connected. Call connect() first.');
+      err.code = 'NOT_CONNECTED';
+      throw err;
+    }
+    return {
+      collection: (name) =>
+        this.scopedCollection(name, { database: dbName }),
+      model: (key) =>
+        this.scopedModel(key, { database: dbName }),
+    };
+  }
+
   /**
    * 自动加载 Model 文件
    *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "monsqlize",
-  "version": "1.2.2",
+  "version": "1.3.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/base.ts

@@ -68,6 +68,10 @@ export const enum ErrorCodes {
     JUMP_TOO_FAR = 'JUMP_TOO_FAR',
     STREAM_NO_JUMP = 'STREAM_NO_JUMP',
     STREAM_NO_TOTALS = 'STREAM_NO_TOTALS',
+    NOT_CONNECTED = 'NOT_CONNECTED',
+    NO_POOL_MANAGER = 'NO_POOL_MANAGER',
+    POOL_NOT_FOUND = 'POOL_NOT_FOUND',
+    MODEL_NOT_DEFINED = 'MODEL_NOT_DEFINED',
     CONNECTION_TIMEOUT = 'CONNECTION_TIMEOUT',
     CONNECTION_FAILED = 'CONNECTION_FAILED',
     CONNECTION_CLOSED = 'CONNECTION_CLOSED',

package/types/monsqlize.ts

@@ -70,6 +70,69 @@ export interface MonSQLize {
      */
     collection(collectionName: string): Collection;
 
+    /**
+     * 获取限定池/库的 collection（公开底层方法）
+     *
+     * opts.pool / opts.database 均为可选；均不填时退化为默认路由。
+     *
+     * @param collectionName - MongoDB 集合名
+     * @param opts.pool      - 连接池名称（可选）
+     * @param opts.database  - 数据库名称（可选）
+     * @throws NOT_CONNECTED / NO_POOL_MANAGER / POOL_NOT_FOUND
+     * @since 1.3.0
+     */
+    scopedCollection(
+      collectionName: string,
+      opts?: { pool?: string; database?: string }
+    ): ReturnType<MonSQLize['collection']>;
+
+    /**
+     * 获取限定池/库的 Model 实例（不走 _modelInstances 缓存）
+     *
+     * connection 合并语义：opts 字段优先，definition.connection 作 fallback。
+     *
+     * @param key  - 已注册的 Model key（或 alias）
+     * @param opts - 路由选项，字段优先于 definition.connection
+     * @throws NOT_CONNECTED / MODEL_NOT_DEFINED / NO_POOL_MANAGER / POOL_NOT_FOUND
+     * @since 1.3.0
+     */
+    scopedModel(
+      key: string,
+      opts?: { pool?: string; database?: string }
+    ): ReturnType<MonSQLize['model']>;
+
+    /**
+     * 获取指定连接池的链式访问器
+     *
+     * 立即校验：NOT_CONNECTED / NO_POOL_MANAGER / POOL_NOT_FOUND。
+     *
+     * @param poolName - 连接池名称
+     * @throws NOT_CONNECTED / NO_POOL_MANAGER / POOL_NOT_FOUND
+     * @since 1.3.0
+     */
+    pool(poolName: string): {
+      collection: (name: string) => ReturnType<MonSQLize['collection']>;
+      model: (key: string) => ReturnType<MonSQLize['model']>;
+      use: (dbName: string) => {
+        collection: (name: string) => ReturnType<MonSQLize['collection']>;
+        model: (key: string) => ReturnType<MonSQLize['model']>;
+      };
+    };
+
+    /**
+     * 获取「默认池 + 指定库」访问器
+     *
+     * 适用于单连接多库场景（无需配置多连接池）。
+     *
+     * @param dbName - 数据库名称
+     * @throws NOT_CONNECTED
+     * @since 1.3.0
+     */
+    use(dbName: string): {
+      collection: (name: string) => ReturnType<MonSQLize['collection']>;
+      model: (key: string) => ReturnType<MonSQLize['model']>;
+    };
+
 
     // ============================================================================
     // 事件系统