monsqlize 1.3.0 → 2.0.0

package/types/README.md

@@ -1,122 +0,0 @@
-# Types 模块说明
-
-本目录包含 monSQLize 的所有 TypeScript 类型定义，已按功能模块拆分。
-
-## 📁 目录结构
-
-```
-types/
-├── base.ts              # 基础类型（ErrorCodes, LoggerLike, ExpressionObject）
-├── expression.ts        # 统一表达式操作符（67个操作符）
-├── cache.ts             # 缓存接口（CacheLike, MultiLevelCache）
-├── options.ts           # 配置选项（BaseOptions, SSH, Transaction）
-├── query.ts             # 查询选项（Find, Count, Aggregate, Distinct）
-├── write.ts             # 写操作（InsertOne, InsertMany, WriteConcern）
-├── batch.ts             # 批量操作（InsertBatch, UpdateBatch, DeleteBatch）
-├── pagination.ts        # 分页系统（FindPage, PageResult, Bookmark）
-├── stream.ts            # 流式查询（Stream, Explain）
-├── transaction.ts       # 事务（Transaction, MongoSession）
-├── lock.ts              # 业务锁（Lock, LockOptions）
-├── chain.ts             # 链式调用（FindChain, AggregateChain）
-├── pool.ts              # 连接池（ConnectionPoolManager, PoolConfig）
-├── saga.ts              # Saga事务（SagaOrchestrator, SagaDefinition）
-├── sync.ts              # 数据同步（Change Stream, SyncConfig）
-├── collection.ts        # Collection API（CollectionAccessor, 所有查询方法）
-├── monsqlize.ts         # MonSQLize主类
-└── model/               # Model 层
-    ├── definition.ts    # Model定义（ModelDefinition, Schema）
-    ├── relations.ts     # 关系定义（Populate, RelationConfig）
-    ├── virtuals.ts      # 虚拟字段（VirtualConfig）
-    ├── instance.ts      # Model实例和静态方法
-    └── index.ts         # Model 类型汇总
-```
-
-## 🔍 模块依赖关系
-
-```
-base.ts (基础)
-  ↓
-options.ts, query.ts (配置)
-  ↓
-write.ts, batch.ts, pagination.ts, stream.ts, chain.ts (操作)
-  ↓
-transaction.ts, lock.ts, pool.ts, saga.ts, sync.ts (功能)
-  ↓
-collection.ts (集合)
-  ↓
-model/* (Model层)
-  ↓
-monsqlize.ts (主类)
-  ↓
-index.d.ts (统一导出)
-```
-
-## 📖 使用指南
-
-### 导入类型
-
-所有类型统一从 `monsqlize` 模块导入：
-
-```typescript
-import type { FindOptions, CollectionAccessor, Model } from 'monsqlize';
-```
-
-### 查找类型定义
-
-1. **按功能查找**：参考上面的目录结构
-2. **使用 IDE**：使用 VS Code 的"转到定义"功能（F12）
-3. **全局搜索**：在 `types/` 目录中搜索类型名称
-
-## 🛠️ 开发指南
-
-### 修改类型定义
-
-1. 找到对应的模块文件（如 `types/query.ts`）
-2. 修改类型定义
-3. 如果是新类型，需要在 `index.d.ts` 中添加导出
-4. 运行 `npx tsc --noEmit` 验证编译通过
-5. 运行 `npm test` 验证测试通过
-
-### 添加新类型
-
-1. 选择合适的模块文件（或创建新模块）
-2. 添加类型定义
-3. 在 `index.d.ts` 中添加导出语句
-   ```typescript
-   export import NewType = ModuleName.NewType;
-   ```
-4. 验证编译和测试
-5. 更新本 README
-
-### 模块划分原则
-
-1. **单一职责**：每个文件只包含相关的类型
-2. **依赖清晰**：避免循环依赖
-3. **大小适中**：单个文件不超过 500 行
-4. **命名规范**：使用 kebab-case（如 `multi-level-cache.ts`）
-
-## 📦 版本历史
-
-- **v1.0.10** (2026-01-19): 将 index.d.ts 拆分为 21 个模块（2932 行 → 21 文件）
-- **v1.0.9**: 原始单文件结构（index.d.ts 2932 行）
-
-## 🔗 相关文档
-
-- [CHANGELOG.md](../CHANGELOG.md)
-- [CONTRIBUTING.md](../CONTRIBUTING.md)
-- [实施方案](../plans/refactoring/ref-types-modularization-v1.0.10-revised.md)
-
-## 📊 统计信息
-
-- **总文件数**: 21 个
-- **总代码行数**: ~2500 行（包含注释）
-- **模块数**: 17 个主模块 + 4 个 Model 子模块
-- **导出类型数**: 100+ 个
-
-## ✅ 质量保证
-
-- ✅ 所有模块通过 TypeScript 编译
-- ✅ 保持向后兼容（原有导入方式不变）
-- ✅ 完整的依赖关系管理
-- ✅ 清晰的模块职责划分
-

package/types/base.ts

@@ -1,94 +0,0 @@
-/**
- * 基础类型定义
- * 包含核心类型、错误码、日志接口等
- * @module types/base
- */
-
-/**
- * 数据库类型
- */
-export type DbType = 'mongodb';
-
-/**
- * 表达式对象
- * 由 expr() 函数创建，包含原始表达式字符串和编译标记
- * @since v1.0.9
- */
-export interface ExpressionObject {
-    /** 原始表达式字符串 */
-    __expr__: string;
-    /** 是否已编译（内部使用） */
-    __compiled__: boolean;
-}
-
-/**
- * 表达式编译上下文
- * @since v1.0.9
- */
-export type ExpressionContext = '$match' | '$project' | '$group' | 'unknown';
-
-/**
- * 统一表达式创建函数
- * @since v1.0.9
- */
-export type ExpressionFunction = (expr: string) => ExpressionObject;
-
-/**
- * 日志记录器接口
- * v2.0 新增：支持 traceId 和结构化日志
- */
-export interface LoggerLike {
-    debug?: (...args: any[]) => void;
-    info?: (...args: any[]) => void;
-    warn?: (...args: any[]) => void;
-    error?: (...args: any[]) => void;
-    withTraceId?: (fn: Function, traceId?: string) => any;
-    getTraceId?: () => string | null;
-}
-
-/**
- * 日志选项
- */
-export interface LoggerOptions {
-    /** 是否使用结构化日志（JSON 格式） */
-    structured?: boolean;
-    /** 是否启用 traceId（分布式追踪） */
-    enableTraceId?: boolean;
-}
-
-/**
- * 统一错误码
- */
-export const enum ErrorCodes {
-    VALIDATION_ERROR = 'VALIDATION_ERROR',
-    INVALID_COLLECTION_NAME = 'INVALID_COLLECTION_NAME',
-    INVALID_DATABASE_NAME = 'INVALID_DATABASE_NAME',
-    INVALID_CURSOR = 'INVALID_CURSOR',
-    CURSOR_SORT_MISMATCH = 'CURSOR_SORT_MISMATCH',
-    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',
-    DATABASE_ERROR = 'DATABASE_ERROR',
-    QUERY_TIMEOUT = 'QUERY_TIMEOUT',
-    CACHE_ERROR = 'CACHE_ERROR',
-    CACHE_TIMEOUT = 'CACHE_TIMEOUT',
-    INVALID_CONFIG = 'INVALID_CONFIG',
-    UNSUPPORTED_DATABASE = 'UNSUPPORTED_DATABASE',
-}
-
-/**
- * 标准错误接口
- */
-export interface MonSQLizeError extends Error {
-    code: string;
-    details?: any[];
-    cause?: Error;
-}
-

package/types/batch.ts

@@ -1,187 +0,0 @@
-/**
- * 批量操作相关类型定义
- * @module types/batch
- * @since v1.0.0
- */
-
-import type { WriteConcern } from './write';
-
-/**
- * 批量操作进度信息
- */
-export interface BatchProgress {
-    /** 当前批次号（从1开始） */
-    currentBatch: number;
-    /** 总批次数 */
-    totalBatches: number;
-    /** 已处理数量 */
-    inserted?: number;
-    modified?: number;
-    deleted?: number;
-    /** 总数量 */
-    total: number | null;
-    /** 完成百分比（0-100） */
-    percentage: number | null;
-    /** 错误数量 */
-    errors: number;
-    /** 重试数量 */
-    retries: number;
-}
-
-/**
- * 重试信息
- */
-export interface RetryInfo {
-    /** 批次索引（从0开始） */
-    batchIndex: number;
-    /** 当前重试次数 */
-    attempt: number;
-    /** 最大重试次数 */
-    maxAttempts: number;
-    /** 错误信息 */
-    error: Error;
-}
-
-/**
- * insertBatch 选项
- * @since v1.0.0
- */
-export interface InsertBatchOptions {
-    /** 每批插入的文档数量（默认 1000） */
-    batchSize?: number;
-    /** 并发批次数（1=串行，>1=并行，默认 1） */
-    concurrency?: number;
-    /** 批次内是否按顺序插入（默认 false） */
-    ordered?: boolean;
-    /** 进度回调函数 */
-    onProgress?: (progress: BatchProgress) => void;
-    /** 错误处理策略: 'stop'|'skip'|'collect'|'retry'（默认 'stop'） */
-    onError?: 'stop' | 'skip' | 'collect' | 'retry';
-    /** 失败批次最大重试次数（onError='retry'时有效，默认 3） */
-    retryAttempts?: number;
-    /** 重试延迟时间（毫秒，默认 1000） */
-    retryDelay?: number;
-    /** 重试回调函数 */
-    onRetry?: (retryInfo: RetryInfo) => void;
-    /** 写确认级别 */
-    writeConcern?: WriteConcern;
-    /** 是否绕过文档验证（默认 false） */
-    bypassDocumentValidation?: boolean;
-    /** 操作注释（用于日志追踪） */
-    comment?: string;
-}
-
-/**
- * updateBatch 选项
- * @since v1.0.0
- */
-export interface UpdateBatchOptions {
-    /** 每批更新的文档数量（默认 1000） */
-    batchSize?: number;
-    /** 是否预先 count 总数（用于进度百分比，默认 true） */
-    estimateProgress?: boolean;
-    /** 进度回调函数 */
-    onProgress?: (progress: BatchProgress) => void;
-    /** 错误处理策略: 'stop'|'skip'|'collect'|'retry'（默认 'stop'） */
-    onError?: 'stop' | 'skip' | 'collect' | 'retry';
-    /** 失败批次最大重试次数（onError='retry'时有效，默认 3） */
-    retryAttempts?: number;
-    /** 重试延迟时间（毫秒，默认 1000） */
-    retryDelay?: number;
-    /** 重试回调函数 */
-    onRetry?: (retryInfo: RetryInfo) => void;
-    /** 写确认级别 */
-    writeConcern?: WriteConcern;
-    /** 未匹配时是否插入（默认 false） */
-    upsert?: boolean;
-    /** 数组过滤器 */
-    arrayFilters?: any[];
-    /** 操作注释（用于日志追踪） */
-    comment?: string;
-}
-
-/**
- * deleteBatch 选项
- * @since v1.0.0
- */
-export interface DeleteBatchOptions {
-    /** 每批删除的文档数量（默认 1000） */
-    batchSize?: number;
-    /** 是否预先 count 总数（用于进度百分比，默认 true） */
-    estimateProgress?: boolean;
-    /** 进度回调函数 */
-    onProgress?: (progress: BatchProgress) => void;
-    /** 错误处理策略: 'stop'|'skip'|'collect'|'retry'（默认 'stop'） */
-    onError?: 'stop' | 'skip' | 'collect' | 'retry';
-    /** 失败批次最大重试次数（onError='retry'时有效，默认 3） */
-    retryAttempts?: number;
-    /** 重试延迟时间（毫秒，默认 1000） */
-    retryDelay?: number;
-    /** 重试回调函数 */
-    onRetry?: (retryInfo: RetryInfo) => void;
-    /** 写确认级别 */
-    writeConcern?: WriteConcern;
-    /** 操作注释（用于日志追踪） */
-    comment?: string;
-}
-
-/**
- * insertBatch 返回结果
- */
-export interface InsertBatchResult {
-    /** 是否被确认 */
-    acknowledged: boolean;
-    /** 总文档数 */
-    totalCount: number;
-    /** 成功插入数 */
-    insertedCount: number;
-    /** 总批次数 */
-    batchCount: number;
-    /** 错误列表 */
-    errors: Array<{ batchIndex: number; message: string; details?: any }>;
-    /** 重试记录列表 */
-    retries: Array<{ batchIndex: number; attempts: number; success: boolean }>;
-    /** 插入的文档 _id 映射表 */
-    insertedIds: Record<number, any>;
-}
-
-/**
- * updateBatch 返回结果
- */
-export interface UpdateBatchResult {
-    /** 是否被确认 */
-    acknowledged: boolean;
-    /** 总文档数（estimateProgress=true时有值） */
-    totalCount: number | null;
-    /** 匹配文档数 */
-    matchedCount: number;
-    /** 成功更新数 */
-    modifiedCount: number;
-    /** 插入数（upsert=true时） */
-    upsertedCount: number;
-    /** 总批次数 */
-    batchCount: number;
-    /** 错误列表 */
-    errors: Array<{ batchIndex: number; message: string; details?: any }>;
-    /** 重试记录列表 */
-    retries: Array<{ batchIndex: number; attempts: number; success: boolean }>;
-}
-
-/**
- * deleteBatch 返回结果
- */
-export interface DeleteBatchResult {
-    /** 是否被确认 */
-    acknowledged: boolean;
-    /** 总文档数（estimateProgress=true时有值） */
-    totalCount: number | null;
-    /** 成功删除数 */
-    deletedCount: number;
-    /** 总批次数 */
-    batchCount: number;
-    /** 错误列表 */
-    errors: Array<{ batchIndex: number; message: string; details?: any }>;
-    /** 重试记录列表 */
-    retries: Array<{ batchIndex: number; attempts: number; success: boolean }>;
-}
-

package/types/cache.ts

@@ -1,71 +0,0 @@
-/**
- * 缓存相关类型定义
- * @module types/cache
- */
-
-/**
- * 缓存接口
- */
-export interface CacheLike {
-    get(key: string): Promise<any>;
-    set(key: string, val: any, ttl?: number): Promise<void>;
-    del(key: string): Promise<boolean>;
-    exists(key: string): Promise<boolean>;
-    getMany(keys: string[]): Promise<Record<string, any>>;
-    setMany(obj: Record<string, any>, ttl?: number): Promise<boolean>;
-    delMany(keys: string[]): Promise<number>;
-    delPattern(pattern: string): Promise<number>;
-    clear(): void;
-    keys(pattern?: string): string[];
-    getStats?(): any;
-}
-
-/**
- * 内置内存缓存的配置（MemoryCacheOptions）
- * - maxSize: 最大键数量（默认 100000）
- * - maxMemory: 最大内存占用（字节；0 表示不限制）
- * - enableStats: 是否启用统计，默认 true
- * - autoInvalidate: 是否启用精准缓存失效，默认 false（v1.1.5+）
- */
-export interface MemoryCacheOptions {
-    maxSize?: number;
-    maxMemory?: number;
-    enableStats?: boolean;
-    /** 🆕 v1.1.5: 是否启用精准缓存失效（默认 false） */
-    autoInvalidate?: boolean;
-    // 允许透传其他实现细节，但不做强约束
-    [k: string]: any;
-}
-
-/**
- * 多层缓存写策略
- * - both：本地+远端双写（等待远端完成）
- * - local-first-async-remote：本地先返回，远端异步写（降低尾延迟）
- */
-export type WritePolicy = 'both' | 'local-first-async-remote';
-
-/**
- * 多层缓存策略配置
- */
-export interface MultiLevelCachePolicy {
-    writePolicy?: WritePolicy;
-    /** 远端命中后是否回填本地，默认 true */
-    backfillLocalOnRemoteHit?: boolean;
-}
-
-/**
- * 多层缓存配置对象（配置式启用双层缓存）
- * 说明：当 BaseOptions.cache 传入该对象时（且 multiLevel=true），框架会自动创建 MultiLevelCache：
- * - local：始终使用内置内存缓存（仅接受配置对象 MemoryCacheOptions）
- * - remote：可传 CacheLike 实例（推荐生产），或传配置对象以退化为"内存占位"
- * - remote.timeoutMs：远端操作超时（毫秒，默认 50）
- * - publish：可选的广播函数（例如用于 pub/sub 触发跨进程本地失效）
- */
-export interface MultiLevelCacheOptions {
-    multiLevel: true;
-    local?: MemoryCacheOptions;
-    remote?: CacheLike | (MemoryCacheOptions & { timeoutMs?: number });
-    policy?: MultiLevelCachePolicy;
-    publish?: (msg: any) => void;
-}
-