monsqlize 1.3.0 → 2.0.0

package/types/pagination.ts

@@ -1,154 +0,0 @@
-/**
- * 分页系统相关类型定义
- * @module types/pagination
- */
-
-import type { FindOptions, MetaOptions } from './query';
-
-/**
- * Bookmark 维护 APIs 相关接口
- */
-export interface BookmarkKeyDims {
-    sort?: Record<string, 1 | -1>;   // 排序配置（与 findPage 一致）
-    limit?: number;                  // 每页数量
-    query?: object;                  // 查询条件（用于计算 queryShape）
-    pipeline?: object[];             // 聚合管道（用于计算 pipelineShape）
-}
-
-export interface PrewarmBookmarksResult {
-    warmed: number;                  // 成功预热的 bookmark 数量
-    failed: number;                  // 预热失败的 bookmark 数量
-    keys: string[];                  // 已缓存的 bookmark 键列表
-}
-
-export interface ListBookmarksResult {
-    count: number;                   // bookmark 总数
-    pages: number[];                 // 已缓存的页码列表（排序后）
-    keys: string[];                  // 缓存键列表
-}
-
-export interface ClearBookmarksResult {
-    cleared: number;                 // 清除的 bookmark 数量
-    pattern: string;                 // 使用的匹配模式
-    keysBefore: number;              // 清除前的 bookmark 数量
-}
-
-/**
- * 跳页相关类型
- */
-export interface JumpOptions {
-    step?: number;                    // 书签密度：每隔 step 页存一个书签；默认 10
-    maxHops?: number;                 // 单次跳页允许的"连续 after 次数（累计）"上限；默认 20
-    keyDims?: object;                 // 可选；未传则自动生成去敏形状
-    getBookmark?: (params: { keyDims: any; page: number }) => Promise<string | null>;
-    saveBookmark?: (params: { keyDims: any; page: number; cursor: string; ttlMs?: number }) => Promise<void>;
-}
-
-export interface OffsetJumpOptions {
-    enable?: boolean;                 // 开启后，当 skip=(page-1)*limit ≤ maxSkip 时走 `$skip+$limit`
-    maxSkip?: number;                 // 默认 50_000；超过则回退到"书签跳转"逻辑
-}
-
-export interface TotalsOptions {
-    mode?: 'none' | 'async' | 'approx' | 'sync'; // 默认 'none'
-    maxTimeMS?: number;              // 用于 `countDocuments` 的超时（sync/async）
-    ttlMs?: number;                  // 总数缓存 TTL（async/approx），默认 10 分钟
-    hint?: any;                      // 计数 hint（可选）
-    collation?: any;                 // 计数 collation（可选，与列表一致更安全）
-}
-
-/**
- * 深度分页（统一版）选项
- */
-export interface FindPageOptions extends FindOptions {
-    /**
-     * 附加聚合管道（在 projection 之前执行，仅对当页数据生效）
-     */
-    pipeline?: object[];
-    after?: string;
-    before?: string;
-    limit: number;
-    allowDiskUse?: boolean;
-    /** Mongo-only: 透传 hint 到 aggregate */
-    hint?: any;
-    /** Mongo-only: 透传 collation 到 aggregate */
-    collation?: any;
-
-    // 新增：跳页相关参数
-    page?: number;                   // 目标页（≥1）；与 after/before 互斥
-    jump?: JumpOptions;              // 跳页（书签）配置
-    offsetJump?: OffsetJumpOptions;  // 小范围 offset 兜底
-    totals?: TotalsOptions;          // 总数/总页数配置
-    meta?: boolean | MetaOptions;    // 返回耗时元信息
-    // 注：projection 继承自 FindOptions，findPage 自 v1.2.0 起正式支持。
-    // 排序字段会被自动保留以确保游标正确生成。
-}
-
-/**
- * 元信息
- */
-export interface MetaInfo {
-    op: string;
-    ns: { iid: string; type: string; db: string; coll: string };
-    startTs: number;
-    endTs: number;
-    durationMs: number;
-    maxTimeMS?: number;
-    fromCache?: boolean;
-    cacheHit?: boolean;
-    cacheTtl?: number;
-    keyHash?: string;
-    // findPage 专用字段
-    page?: number;
-    after?: boolean;
-    before?: boolean;
-    hops?: number;
-    step?: number;
-    steps?: Array<{ phase: 'hop' | 'offset'; index?: number; durationMs: number }>; // level='sub' 时提供
-    error?: { code?: string; message: string };
-}
-
-/**
- * 总数信息
- */
-export interface TotalsInfo {
-    mode: 'async' | 'sync' | 'approx';
-    total?: number | null | undefined;   // async: null（未就绪）；approx: undefined（未知或近似）
-    totalPages?: number | null | undefined;
-    token?: string;                      // async 时返回的短标识（<keyHash>）
-    ts?: number;                         // 写入时间戳（毫秒），如果来自缓存
-    error?: string;                      // 仅 async：统计失败时可能附带的错误标识
-}
-
-/**
- * 页面信息
- */
-export interface PageInfo {
-    hasNext: boolean;
-    hasPrev: boolean;
-    startCursor: string | null;
-    endCursor: string | null;
-    currentPage?: number;                // 仅跳页/offset 模式回显目标页号（逻辑页号）
-}
-
-/**
- * 分页结果
- */
-export interface PageResult<T = any> {
-    items: T[];
-    pageInfo: PageInfo;
-    totals?: TotalsInfo;                 // 当启用 totals 时返回
-    meta?: MetaInfo;                     // 当启用 meta 时返回
-}
-
-/**
- * 带 meta 的返回类型（用于 findOne/find/count）
- */
-export interface ResultWithMeta<T = any> {
-    data: T;
-    meta: MetaInfo;
-}
-
-// 重新导出 MetaOptions，方便其他模块使用
-export { MetaOptions };
-

package/types/pool.ts

@@ -1,125 +0,0 @@
-/**
- * 连接池管理相关类型定义
- * @module types/pool
- * @since v1.0.8
- */
-
-import type { LoggerLike } from './base';
-
-/**
- * 连接池角色
- * @since v1.0.8
- */
-export type PoolRole = 'primary' | 'secondary' | 'analytics' | 'custom';
-
-/**
- * 连接池选择策略
- * @since v1.0.8
- */
-export type PoolStrategy = 'auto' | 'roundRobin' | 'weighted' | 'leastConnections' | 'manual';
-
-/**
- * 故障转移策略
- * @since v1.0.8
- */
-export type FallbackStrategy = 'error' | 'readonly' | 'primary';
-
-/**
- * 连接池配置
- * @since v1.0.8
- */
-export interface PoolConfig {
-    /** 连接池名称（唯一标识） */
-    name: string;
-    /** MongoDB URI */
-    uri: string;
-    /** 连接池角色 */
-    role?: PoolRole;
-    /** 权重（用于加权选择策略，默认 1） */
-    weight?: number;
-    /** 标签（用于筛选） */
-    tags?: string[];
-    /** MongoDB 连接选项 */
-    options?: {
-        maxPoolSize?: number;
-        minPoolSize?: number;
-        maxIdleTimeMS?: number;
-        waitQueueTimeoutMS?: number;
-        connectTimeoutMS?: number;
-        serverSelectionTimeoutMS?: number;
-    };
-    /** 健康检查配置 */
-    healthCheck?: {
-        enabled?: boolean;
-        interval?: number;
-        timeout?: number;
-        retries?: number;
-    };
-}
-
-/**
- * 连接池管理器选项
- * @since v1.0.8
- */
-export interface ConnectionPoolManagerOptions {
-    /** 连接池配置数组 */
-    pools?: PoolConfig[];
-    /** 最大连接池数量（默认 10） */
-    maxPoolsCount?: number;
-    /** 选择策略（默认 'auto'） */
-    poolStrategy?: PoolStrategy;
-    /** 故障转移配置 */
-    poolFallback?: {
-        enabled?: boolean;
-        fallbackStrategy?: FallbackStrategy;
-        retryDelay?: number;
-        maxRetries?: number;
-    };
-    /** 日志记录器 */
-    logger?: LoggerLike;
-}
-
-/**
- * 连接池健康状态
- * @since v1.0.8
- */
-export interface PoolHealthStatus {
-    status: 'up' | 'down' | 'degraded';
-    consecutiveFailures: number;
-    lastCheckTime: Date | null;
-    lastError: Error | null;
-    uptime: number;
-}
-
-/**
- * 连接池统计信息
- * @since v1.0.8
- */
-export interface PoolStats {
-    name: string;
-    totalRequests: number;
-    successCount: number;
-    errorCount: number;
-    avgResponseTime: number;
-    minResponseTime: number;
-    maxResponseTime: number;
-    errorRate: number;
-    lastRequestTime: Date | null;
-}
-
-/**
- * 连接池管理器类
- * @since v1.0.8
- */
-export interface ConnectionPoolManager {
-    addPool(config: PoolConfig): Promise<void>;
-    removePool(name: string): Promise<void>;
-    getPool(name: string): any;
-    selectPool(operation: string, options?: { tags?: string[] }): any;
-    startHealthCheck(): void;
-    stopHealthCheck(): void;
-    getHealthStatus(): Record<string, PoolHealthStatus>;
-    getPoolStats(): Record<string, PoolStats>;
-    close(): Promise<void>;
-}
-

package/types/query.ts

@@ -1,71 +0,0 @@
-/**
- * 查询选项类型定义
- * @module types/query
- */
-
-/**
- * 元信息选项
- */
-export interface MetaOptions {
-    level?: 'op' | 'sub';            // sub: 返回子步骤耗时（仅 findPage）
-    includeCache?: boolean;          // 包含缓存相关信息
-}
-
-/**
- * find 查询选项
- */
-export interface FindOptions {
-    projection?: Record<string, any> | string[];
-    sort?: Record<string, 1 | -1>;
-    limit?: number;
-    skip?: number;
-    cache?: number;
-    maxTimeMS?: number;
-    /** Mongo-only: 透传 hint 到驱动 */
-    hint?: any;
-    /** Mongo-only: 透传 collation 到驱动 */
-    collation?: any;
-    /** 查询注释（用于生产环境日志跟踪）*/
-    comment?: string;
-    meta?: boolean | MetaOptions;    // 返回耗时元信息
-}
-
-/**
- * count 查询选项
- */
-export interface CountOptions {
-    cache?: number;
-    maxTimeMS?: number;
-    /** Mongo-only: 透传 hint 到 countDocuments */
-    hint?: any;
-    /** Mongo-only: 透传 collation 到 countDocuments */
-    collation?: any;
-    /** 查询注释（用于生产环境日志跟踪）*/
-    comment?: string;
-    meta?: boolean | MetaOptions;
-}
-
-/**
- * aggregate 聚合查询选项
- */
-export interface AggregateOptions {
-    cache?: number;                  // 缓存时间（毫秒），默认 0（不缓存）
-    maxTimeMS?: number;              // 查询超时时间（毫秒）
-    allowDiskUse?: boolean;          // 是否允许使用磁盘（默认 false）
-    collation?: any;                 // 排序规则（可选）
-    hint?: string | object;          // 索引提示（可选）
-    comment?: string;                // 查询注释（可选）
-    meta?: boolean | MetaOptions;    // 返回耗时元信息
-}
-
-/**
- * distinct 查询选项
- */
-export interface DistinctOptions {
-    cache?: number;                  // 缓存时间（毫秒），默认继承实例缓存配置
-    maxTimeMS?: number;              // 查询超时时间（毫秒）
-    collation?: any;                 // 排序规则（可选）
-    hint?: string | object;          // 索引提示（可选）
-    meta?: boolean | MetaOptions;    // 返回耗时元信息
-}
-

package/types/saga.ts

@@ -1,125 +0,0 @@
-/**
- * Saga分布式事务相关类型定义
- * @module types/saga
- * @since v1.0.8
- */
-
-import type { CacheLike } from './cache';
-import type { LoggerLike } from './base';
-
-/**
- * Saga 步骤定义
- * @since v1.0.8
- */
-export interface SagaStep {
-    /** 步骤名称 */
-    name: string;
-    /** 执行函数 */
-    execute: (context: SagaContext) => Promise<any>;
-    /** 补偿函数（失败时执行） */
-    compensate: (context: SagaContext) => Promise<void>;
-    /** 步骤超时时间（毫秒） */
-    timeout?: number;
-    /** 重试次数（默认 0） */
-    retries?: number;
-}
-
-/**
- * Saga 定义
- * @since v1.0.8
- */
-export interface SagaDefinition {
-    /** Saga 名称 */
-    name: string;
-    /** 步骤数组 */
-    steps: SagaStep[];
-    /** 超时时间（毫秒，默认 60000） */
-    timeout?: number;
-    /** 是否启用日志（默认 true） */
-    logging?: boolean;
-}
-
-/**
- * Saga 上下文
- * @since v1.0.8
- */
-export interface SagaContext {
-    /** Saga 执行 ID */
-    readonly executionId: string;
-    /** 输入数据 */
-    readonly data: any;
-
-    /**
-     * 设置上下文变量
-     * @param key 键
-     * @param value 值
-     */
-    set(key: string, value: any): void;
-
-    /**
-     * 获取上下文变量
-     * @param key 键
-     */
-    get(key: string): any;
-
-    /**
-     * 检查变量是否存在
-     * @param key 键
-     */
-    has(key: string): boolean;
-
-    /**
-     * 获取所有上下文变量
-     */
-    getAll(): Record<string, any>;
-}
-
-/**
- * Saga 执行结果
- * @since v1.0.8
- */
-export interface SagaResult {
-    /** 执行 ID */
-    executionId: string;
-    /** 是否成功 */
-    success: boolean;
-    /** 执行结果 */
-    result?: any;
-    /** 错误信息 */
-    error?: Error;
-    /** 已完成的步骤 */
-    completedSteps: string[];
-    /** 已补偿的步骤 */
-    compensatedSteps: string[];
-    /** 执行时长（毫秒） */
-    duration: number;
-}
-
-/**
- * Saga 协调器选项
- * @since v1.0.8
- */
-export interface SagaOrchestratorOptions {
-    /** 缓存实例（用于分布式状态存储） */
-    cache?: CacheLike;
-    /** 日志记录器 */
-    logger?: LoggerLike;
-}
-
-/**
- * Saga 协调器类
- * @since v1.0.8
- */
-export interface SagaOrchestrator {
-    define(definition: SagaDefinition): void;
-    execute(name: string, data: any): Promise<SagaResult>;
-    getSaga(name: string): SagaDefinition | undefined;
-    listSagas(): string[];
-    getStats(): {
-        totalExecutions: number;
-        successCount: number;
-        failureCount: number;
-        compensationCount: number;
-    };
-}
-

package/types/stream.ts

@@ -1,64 +0,0 @@
-/**
- * 流式查询和诊断相关类型定义
- * @module types/stream
- */
-
-/**
- * 流式查询选项
- */
-export interface StreamOptions {
-    projection?: Record<string, any> | string[];  // 字段投影
-    sort?: Record<string, 1 | -1>;   // 排序配置
-    limit?: number;                  // 限制返回数量
-    skip?: number;                   // 跳过数量
-    batchSize?: number;              // 每批次大小（默认 1000）
-    maxTimeMS?: number;              // 查询超时时间（毫秒）
-    hint?: any;                      // 索引提示
-    collation?: any;                 // 排序规则
-    noCursorTimeout?: boolean;       // 禁用游标超时（默认 false）
-}
-
-/**
- * Explain 选项（查询执行计划诊断）
- */
-export interface ExplainOptions {
-    projection?: object;             // 字段投影
-    sort?: Record<string, 1 | -1>;   // 排序配置
-    limit?: number;                  // 限制返回数量
-    skip?: number;                   // 跳过数量
-    maxTimeMS?: number;              // 查询超时时间（毫秒）
-    hint?: any;                      // 索引提示
-    collation?: any;                 // 排序规则
-    verbosity?: 'queryPlanner' | 'executionStats' | 'allPlansExecution'; // 详细程度（默认 'queryPlanner'）
-}
-
-/**
- * Explain 执行计划结果
- */
-export interface ExplainResult {
-    queryPlanner: {
-        plannerVersion: number;
-        namespace: string;
-        indexFilterSet: boolean;
-        parsedQuery?: any;
-        winningPlan: any;
-        rejectedPlans: any[];
-    };
-    executionStats?: {
-        executionSuccess: boolean;
-        nReturned: number;
-        executionTimeMillis: number;
-        totalKeysExamined: number;
-        totalDocsExamined: number;
-        executionStages: any;
-        allPlansExecution?: any[];
-    };
-    serverInfo?: {
-        host: string;
-        port: number;
-        version: string;
-        gitVersion: string;
-    };
-    ok: number;
-}
-

package/types/sync.ts

@@ -1,79 +0,0 @@
-/**
- * Change Stream数据同步相关类型定义
- * @module types/sync
- * @since v1.0.8
- */
-
-/**
- * 同步目标配置
- * @since v1.0.8
- */
-export interface SyncTarget {
-    /** 目标名称 */
-    name: string;
-    /** MongoDB URI */
-    uri: string;
-    /** 要同步的集合（['*'] 表示全部） */
-    collections?: string[];
-    /** 健康检查配置 */
-    healthCheck?: {
-        enabled?: boolean;
-        interval?: number;
-        timeout?: number;
-        retries?: number;
-    };
-}
-
-/**
- * Resume Token 配置
- * @since v1.0.8
- */
-export interface ResumeTokenConfig {
-    /** 存储类型（'file' | 'redis'） */
-    storage?: 'file' | 'redis';
-    /** 文件路径（storage='file' 时使用） */
-    path?: string;
-    /** Redis 实例（storage='redis' 时使用） */
-    redis?: any;
-}
-
-/**
- * Change Stream 同步配置
- * @since v1.0.8
- */
-export interface SyncConfig {
-    /** 是否启用同步 */
-    enabled: boolean;
-    /** 备份目标数组 */
-    targets: SyncTarget[];
-    /** 要监听的集合（可选，默认全部） */
-    collections?: string[];
-    /** Resume Token 配置 */
-    resumeToken?: ResumeTokenConfig;
-    /** 事件过滤函数 */
-    filter?: (event: any) => boolean;
-    /** 数据转换函数 */
-    transform?: (document: any) => any;
-}
-
-/**
- * Change Stream 同步统计
- * @since v1.0.8
- */
-export interface SyncStats {
-    isRunning: boolean;
-    eventCount: number;
-    syncedCount: number;
-    errorCount: number;
-    startTime: Date | null;
-    lastEventTime: Date | null;
-    targets: Array<{
-        name: string;
-        syncCount: number;
-        errorCount: number;
-        lastSyncTime: Date | null;
-        lastError: Error | null;
-        successRate: string;
-    }>;
-}
-

package/types/transaction.ts

@@ -1,79 +0,0 @@
-/**
- * 事务相关类型定义
- * @module types/transaction
- * @since v0.2.0
- */
-
-/**
- * MongoDB 事务会话（原生 ClientSession）
- * @since v0.2.0
- */
-export interface MongoSession {
-    /** 会话 ID */
-    id: any;
-    /** 是否在事务中 */
-    inTransaction(): boolean;
-    /** 事务状态 */
-    transaction?: {
-        state: string;
-    };
-    /** 结束会话 */
-    endSession(): void;
-    /** 其他 MongoDB 原生方法 */
-    [key: string]: any;
-}
-
-/**
- * Transaction 事务类
- * 封装 MongoDB 原生会话，提供事务生命周期管理
- * @since v0.2.0
- */
-export interface Transaction {
-    /** 事务唯一 ID */
-    readonly id: string;
-
-    /** MongoDB 原生会话对象（传递给查询方法） */
-    readonly session: MongoSession;
-
-    /**
-     * 启动事务
-     * @returns Promise<void>
-     */
-    start(): Promise<void>;
-
-    /**
-     * 提交事务
-     * @returns Promise<void>
-     */
-    commit(): Promise<void>;
-
-    /**
-     * 中止（回滚）事务
-     * @returns Promise<void>
-     */
-    abort(): Promise<void>;
-
-    /**
-     * 结束会话（清理资源）
-     * @returns Promise<void>
-     */
-    end(): Promise<void>;
-
-    /**
-     * 获取事务执行时长（毫秒）
-     * @returns number
-     */
-    getDuration(): number;
-
-    /**
-     * 获取事务信息
-     * @returns 事务状态信息
-     */
-    getInfo(): {
-        id: string;
-        status: 'pending' | 'started' | 'committed' | 'aborted';
-        duration: number;
-        sessionId: string;
-    };
-}
-