monsqlize 1.2.3 → 1.3.0

package/CHANGELOG.md

@@ -1,7 +1,7 @@
 # 变更日志 (CHANGELOG)
 
 > **说明**: 版本概览摘要，详细变更见 [changelogs/](./changelogs/) 目录  
-> **最后更新**: 2026-04-26
+> **最后更新**: 2026-04-27
 
 ---
 
@@ -9,6 +9,7 @@
 
 | 版本 | 日期 | 变更摘要 | 详细 |
 |------|------|---------|------|
+| [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) |

package/lib/index.js

@@ -830,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.3",
+  "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']>;
+    };
+
 
     // ============================================================================
     // 事件系统