monsqlize 1.3.0 → 2.0.0

package/types/model/relations.ts

@@ -1,121 +0,0 @@
-/**
- * Model 关系定义相关类型
- * @module types/model/relations
- * @since v1.2.0
- */
-
-/**
- * 关系配置（MongoDB 原生风格）
- * @since v1.2.0
- */
-export interface RelationConfig {
-    /**
-     * 关联的集合名称（MongoDB 原生集合名）
-     * @example 'posts'
-     */
-    from: string;
-
-    /**
-     * 本地字段名（用于匹配的字段）
-     * @example '_id'
-     */
-    localField: string;
-
-    /**
-     * 外部字段名（关联集合中的字段）
-     * @example 'authorId'
-     */
-    foreignField: string;
-
-    /**
-     * 返回类型
-     * - true: 返回单个文档或 null（one-to-one）
-     * - false: 返回数组（one-to-many）
-     * @default false
-     */
-    single?: boolean;
-}
-
-/**
- * Populate 配置
- * @since v1.2.0
- */
-export interface PopulateConfig {
-    /**
-     * 关系路径（relations 中定义的名称）
-     * @example 'posts'
-     */
-    path: string;
-
-    /**
-     * 字段选择（空格分隔）
-     * @example 'title content createdAt'
-     */
-    select?: string;
-
-    /**
-     * 排序规则
-     * @example { createdAt: -1 }
-     */
-    sort?: Record<string, 1 | -1>;
-
-    /**
-     * 限制返回数量
-     * @example 10
-     */
-    limit?: number;
-
-    /**
-     * 跳过数量
-     * @example 20
-     */
-    skip?: number;
-
-    /**
-     * 额外过滤条件
-     * @example { status: 'published' }
-     */
-    match?: any;
-
-    /**
-     * 嵌套 populate（支持多层关联）
-     * @example
-     * // 字符串形式
-     * populate: 'comments'
-     *
-     * // 对象形式
-     * populate: { path: 'comments', select: 'content' }
-     *
-     * // 数组形式
-     * populate: ['comments', 'likes']
-     */
-    populate?: string | PopulateConfig | (string | PopulateConfig)[];
-}
-
-/**
- * PopulateProxy - 支持链式 populate 调用
- * @since v1.2.0
- */
-export interface PopulateProxy<T = any> extends Promise<T> {
-    /**
-     * 添加 populate 路径（链式调用）
-     *
-     * @param path - 关系路径或配置对象
-     * @returns PopulateProxy 实例，支持继续链式调用
-     *
-     * @example
-     * // 字符串形式
-     * User.findOne({ _id }).populate('posts')
-     *
-     * // 对象形式
-     * User.findOne({ _id }).populate({ path: 'posts', select: 'title' })
-     *
-     * // 链式调用
-     * User.findOne({ _id })
-     *     .populate('profile')
-     *     .populate({ path: 'posts', limit: 10 })
-     */
-    populate(path: string): PopulateProxy<T>;
-    populate(config: PopulateConfig): PopulateProxy<T>;
-}
-

package/types/model/virtuals.ts

@@ -1,32 +0,0 @@
-/**
- * Model 虚拟字段相关类型
- * @module types/model/virtuals
- * @since v1.0.6
- */
-
-/**
- * 虚拟字段配置
- * @since v1.0.6
- */
-export interface VirtualConfig {
-    /**
-     * getter 函数（必需）
-     * @example
-     * get: function() {
-     *     return `${this.firstName} ${this.lastName}`;
-     * }
-     */
-    get: (this: any) => any;
-
-    /**
-     * setter 函数（可选）
-     * @example
-     * set: function(value) {
-     *     const parts = value.split(' ');
-     *     this.firstName = parts[0];
-     *     this.lastName = parts[1];
-     * }
-     */
-    set?: (this: any, value: any) => void;
-}
-

package/types/monsqlize.ts

@@ -1,245 +0,0 @@
-/**
- * MonSQLize 主类类型定义
- * @module types/monsqlize
- */
-
-import type { TransactionOptions } from './options';
-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 主类
- */
-export interface MonSQLize {
-
-    /**
-     * 连接数据库
-     */
-    connect(): Promise<DbAccessor>;
-
-    /**
-     * 获取缓存实例
-     */
-    getCache(): CacheLike;
-
-    /**
-     * 获取默认配置
-     */
-    getDefaults(): {
-        maxTimeMS?: number;
-        findLimit?: number;
-        namespace?: { instanceId?: string; scope?: 'database' | 'connection' };
-        slowQueryMs?: number;
-    };
-
-    /**
-     * 关闭连接
-     */
-    close(): Promise<void>;
-
-    /**
-     * 健康检查
-     */
-    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;
-
-    /**
-     * 获取限定池/库的 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']>;
-    };
-
-
-    // ============================================================================
-    // 事件系统
-    // ============================================================================
-
-    /** 事件订阅 */
-    on(event: 'connected', handler: (payload: { type: string; db: string; scope?: string; iid?: string }) => void): void;
-    on(event: 'closed', handler: (payload: { type: string; db: string; iid?: string }) => void): void;
-    on(event: 'error', handler: (payload: { type: string; db: string; error: string; iid?: string }) => void): void;
-    on(event: 'slow-query', handler: (meta: MetaInfo) => void): void;
-    on(event: 'query', handler: (meta: MetaInfo) => void): void;
-    on(event: string, handler: (payload: any) => void): void;
-
-    /** 一次性事件订阅 */
-    once(event: string, handler: (payload: any) => void): void;
-
-    /** 取消事件订阅 */
-    off(event: string, handler: (payload: any) => void): void;
-
-    /** 触发事件 */
-    emit(event: string, payload: any): void;
-
-    // ============================================================================
-    // 事务管理
-    // ============================================================================
-
-    /**
-     * 创建手动事务会话
-     * @since v0.2.0
-     */
-    startSession(options?: TransactionOptions): Promise<Transaction>;
-
-    /**
-     * 自动管理事务生命周期（推荐）
-     * @since v0.2.0
-     */
-    withTransaction<T = any>(
-        callback: (transaction: Transaction) => Promise<T>,
-        options?: TransactionOptions
-    ): Promise<T>;
-
-    // ============================================================================
-    // 业务锁 API
-    // ============================================================================
-
-    /**
-     * 业务锁：自动管理锁生命周期（推荐）
-     * @since v1.4.0
-     */
-    withLock?<T = any>(
-        key: string,
-        callback: () => Promise<T>,
-        options?: LockOptions
-    ): Promise<T>;
-
-    /**
-     * 业务锁：手动获取锁（阻塞重试）
-     * @since v1.4.0
-     */
-    acquireLock?(key: string, options?: LockOptions): Promise<Lock>;
-
-    /**
-     * 业务锁：尝试获取锁（不阻塞）
-     * @since v1.4.0
-     */
-    tryAcquireLock?(key: string, options?: Omit<LockOptions, 'retryTimes'>): Promise<Lock | null>;
-
-    /**
-     * 获取慢查询日志
-     * @since v1.3.1
-     */
-    getSlowQueryLogs(
-        filter?: Record<string, any>,
-        options?: {
-            sort?: Record<string, 1 | -1>;
-            limit?: number;
-            skip?: number;
-        }
-    ): Promise<Array<{
-        queryHash: string;
-        database: string;
-        collection: string;
-        operation: string;
-        count: number;
-        totalTimeMs: number;
-        avgTimeMs: number;
-        maxTimeMs: number;
-        minTimeMs: number;
-        firstSeen: Date;
-        lastSeen: Date;
-    }>>;
-}
-
-/**
- * MonSQLize 命名空间（静态成员）
- */
-export declare namespace MonSQLize {
-    /**
-     * 统一表达式创建函数（静态方法）
-     * @since v1.0.9
-     */
-    const expr: ExpressionFunction;
-
-    /**
-     * 统一表达式创建函数（完整版别名）
-     * @since v1.0.9
-     */
-    const createExpression: ExpressionFunction;
-}
-

package/types/options.ts

@@ -1,192 +0,0 @@
-/**
- * 配置选项类型定义
- * @module types/options
- */
-
-import type { DbType, LoggerLike } from './base';
-import type { CacheLike, MemoryCacheOptions, MultiLevelCacheOptions } from './cache';
-
-/**
- * SSH 隧道配置
- * @since v1.3.0
- */
-export interface SSHConfig {
-    /** SSH 服务器地址 */
-    host: string;
-    /** SSH 服务器端口（默认 22） */
-    port?: number;
-    /** SSH 用户名 */
-    username: string;
-    /** SSH 密码（与 privateKey 二选一） */
-    password?: string;
-    /** SSH 私钥（字符串或 Buffer，与 password 二选一） */
-    privateKey?: string | Buffer;
-    /** 私钥密码（如果私钥有加密） */
-    passphrase?: string;
-    /** 连接超时时间（毫秒，默认 30000） */
-    readyTimeout?: number;
-    /** 保持连接的间隔时间（毫秒，默认 10000） */
-    keepaliveInterval?: number;
-    /** 目标数据库主机（相对于 SSH 服务器，默认 'localhost'） */
-    dstHost?: string;
-    /** 目标数据库端口（相对于 SSH 服务器） */
-    dstPort?: number;
-}
-
-/**
- * 事务选项配置
- * @since v0.2.0
- */
-export interface TransactionOptions {
-    /** 读关注级别（Read Concern） */
-    readConcern?: {
-        level: 'local' | 'majority' | 'snapshot' | 'linearizable' | 'available';
-    };
-    /** 读偏好（Read Preference） */
-    readPreference?: 'primary' | 'primaryPreferred' | 'secondary' | 'secondaryPreferred' | 'nearest';
-    /** 因果一致性（Causal Consistency） */
-    causalConsistency?: boolean;
-    /** 事务最大执行时间（毫秒） */
-    maxDuration?: number;
-    /** 是否启用自动重试 */
-    enableRetry?: boolean;
-    /** 最大重试次数 */
-    maxRetries?: number;
-    /** 重试延迟（毫秒） */
-    retryDelay?: number;
-    /** 重试退避系数 */
-    retryBackoff?: number;
-    /** 是否启用缓存锁 */
-    enableCacheLock?: boolean;
-    /** 缓存锁清理间隔（毫秒） */
-    lockCleanupInterval?: number;
-}
-
-/**
- * MonSQLize 基础配置选项
- */
-export interface BaseOptions {
-    type: DbType;
-    databaseName: string;
-    config: any;
-    /** SSH 隧道配置（v1.3.0+） */
-    ssh?: SSHConfig;
-    cache?: CacheLike | MemoryCacheOptions | MultiLevelCacheOptions | object;
-    logger?: LoggerLike;
-    maxTimeMS?: number; // 全局默认查询超时（毫秒）
-    findLimit?: number; // 全局默认 find limit（未传 limit 时使用；0 表示不限制）
-    namespace?: { instanceId?: string; scope?: 'database' | 'connection' };
-    slowQueryMs?: number; // 慢查询日志阈值（毫秒），默认 500
-    /** MongoDB 副本集读偏好（全局配置）
-     * - 'primary': 仅读主节点（默认）
-     * - 'primaryPreferred': 优先读主节点，主节点不可用时读从节点
-     * - 'secondary': 仅读从节点
-     * - 'secondaryPreferred': 优先读从节点，从节点不可用时读主节点
-     * - 'nearest': 读最近的节点（低延迟）
-     */
-    readPreference?: 'primary' | 'primaryPreferred' | 'secondary' | 'secondaryPreferred' | 'nearest';
-    /**
-     * 事务配置（MongoDB Transaction API）
-     * 需要 MongoDB 4.0+ 且部署在副本集或分片集群上
-     * @since v0.2.0
-     */
-    transaction?: TransactionOptions | false;
-    // 统一默认（新增可选项）
-    findPageMaxLimit?: number;          // 深分页页大小上限（默认 500）
-    cursorSecret?: string;              // 可选：游标签名密钥（如启用 HMAC 验签）
-    log?: {
-        slowQueryTag?: { event?: string; code?: string };
-        formatSlowQuery?: (meta: any) => any;
-    };
-    /**
-     * ObjectId 自动转换配置（v1.3.0+）
-     * 自动将字符串 _id 转换为 ObjectId
-     * @default true（MongoDB）
-     * @since v1.3.0
-     */
-    autoConvertObjectId?: boolean | {
-        /** 是否启用（默认 true） */
-        enabled?: boolean;
-        /** 排除字段列表 */
-        excludeFields?: string[];
-        /** 自定义字段模式 */
-        customFieldPatterns?: string[];
-        /** 最大转换深度（默认 10） */
-        maxDepth?: number;
-        /** 日志级别（默认 'warn'） */
-        logLevel?: 'info' | 'warn' | 'error';
-    };
-    /**
-     * Count 队列配置（高并发控制）
-     * 避免大量并发 count 查询压垮数据库
-     * @default { enabled: true, concurrency: CPU核心数 }
-     * @since v1.0.0
-     */
-    countQueue?: boolean | {
-        /** 是否启用队列（默认 true） */
-        enabled?: boolean;
-        /** 并发数（默认 CPU 核心数，最少 4，最多 16） */
-        concurrency?: number;
-        /** 最大队列长度（默认 10000） */
-        maxQueueSize?: number;
-        /** 超时时间（毫秒，默认 60000） */
-        timeout?: number;
-    };
-    /**
-     * Model 自动加载配置（v1.4.0+）
-     * 自动扫描指定目录加载 Model 定义文件
-     * @default undefined（不启用）
-     * @since v1.4.0
-     */
-    models?: string | {
-        /** Model 文件目录路径（相对或绝对路径） */
-        path: string;
-        /** 文件名模式（支持 glob 格式，默认 '*.model.{js,ts,mjs,cjs}'） */
-        pattern?: string;
-        /** 是否递归扫描子目录（默认 false） */
-        recursive?: boolean;
-    };
-    /**
-     * Change Stream 数据同步配置（v1.0.8+）
-     * 实时同步数据到备份库
-     * @requires MongoDB Replica Set
-     * @requires MongoDB 4.0+
-     * @since v1.0.8
-     */
-    sync?: {
-        /** 是否启用同步 */
-        enabled: boolean;
-        /** 备份目标数组 */
-        targets: Array<{
-            /** 目标名称 */
-            name: string;
-            /** MongoDB URI */
-            uri: string;
-            /** 要同步的集合（['*'] 表示全部） */
-            collections?: string[];
-            /** 健康检查配置 */
-            healthCheck?: {
-                enabled?: boolean;
-                interval?: number;
-                timeout?: number;
-                retries?: number;
-            };
-        }>;
-        /** 要监听的集合（可选，默认全部） */
-        collections?: string[];
-        /** Resume Token 配置 */
-        resumeToken?: {
-            /** 存储类型（'file' | 'redis'） */
-            storage?: 'file' | 'redis';
-            /** 文件路径（storage='file' 时使用） */
-            path?: string;
-            /** Redis 实例（storage='redis' 时使用） */
-            redis?: any;
-        };
-        /** 事件过滤函数 */
-        filter?: (event: any) => boolean;
-        /** 数据转换函数 */
-        transform?: (document: any) => any;
-    };
-}
-