monsqlize 1.0.2 → 1.0.5

package/index.d.ts

@@ -279,6 +279,33 @@ declare module 'monsqlize' {
         [k: string]: any;
     }
 
+    /**
+     * SSH 隧道配置
+     * @since v1.3.0
+     */
+    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;
+    }
+
     /**
      * 多层缓存写策略
      * - both：本地+远端双写（等待远端完成）
@@ -311,6 +338,8 @@ declare module 'monsqlize' {
         type: DbType;
         databaseName: string;
         config: any;
+        /** SSH 隧道配置（v1.3.0+） */
+        ssh?: SSHConfig;
         cache?: CacheLike | MemoryCacheOptions | MultiLevelCacheOptions | object;
         logger?: LoggerLike;
         maxTimeMS?: number; // 全局默认查询超时（毫秒）
@@ -338,6 +367,40 @@ declare module 'monsqlize' {
             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;
+        };
     }
     interface FindOptions {
         projection?: Record<string, any> | string[];
@@ -366,6 +429,189 @@ declare module 'monsqlize' {
         meta?: boolean | MetaOptions;
     }
 
+    // ============================================================================
+    // 批量操作相关类型定义（Batch Operations）
+    // ============================================================================
+
+    /**
+     * insertBatch 选项
+     * @since v1.0.0
+     */
+    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?: { w?: number | string; j?: boolean; wtimeout?: number };
+        /** 是否绕过文档验证（默认 false） */
+        bypassDocumentValidation?: boolean;
+        /** 操作注释（用于日志追踪） */
+        comment?: string;
+    }
+
+    /**
+     * updateBatch 选项
+     * @since v1.0.0
+     */
+    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?: { w?: number | string; j?: boolean; wtimeout?: number };
+        /** 未匹配时是否插入（默认 false） */
+        upsert?: boolean;
+        /** 数组过滤器 */
+        arrayFilters?: any[];
+        /** 操作注释（用于日志追踪） */
+        comment?: string;
+    }
+
+    /**
+     * deleteBatch 选项
+     * @since v1.0.0
+     */
+    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?: { w?: number | string; j?: boolean; wtimeout?: number };
+        /** 操作注释（用于日志追踪） */
+        comment?: string;
+    }
+
+    /**
+     * 批量操作进度信息
+     */
+    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;
+    }
+
+    /**
+     * 重试信息
+     */
+    interface RetryInfo {
+        /** 批次索引（从0开始） */
+        batchIndex: number;
+        /** 当前重试次数 */
+        attempt: number;
+        /** 最大重试次数 */
+        maxAttempts: number;
+        /** 错误信息 */
+        error: Error;
+    }
+
+    /**
+     * insertBatch 返回结果
+     */
+    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 返回结果
+     */
+    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 返回结果
+     */
+    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 }>;
+    }
+
     interface AggregateOptions {
         cache?: number;                  // 缓存时间（毫秒），默认 0（不缓存）
         maxTimeMS?: number;              // 查询超时时间（毫秒）
@@ -628,7 +874,7 @@ declare module 'monsqlize' {
          */
         findOneById(id: string | any, options?: Omit<FindOptions, 'meta'>): Promise<any | null>;
 
-u        /**
+        u        /**
          * 批量通过 _id 查询多个文档（便利方法）
          * @param ids - _id 数组（支持字符串和 ObjectId 混合）
          * @param options - 查询选项
@@ -782,8 +1028,86 @@ u        /**
         }>;
 
         invalidate(op?: 'find' | 'findOne' | 'count' | 'findPage' | 'aggregate' | 'distinct'): Promise<number>;
+
+        // ============================================================================
+        // 批量操作方法 (Batch Operations)
+        // ============================================================================
+
+        /**
+         * 大批量插入（自动分批+重试）
+         * @param documents - 要插入的文档数组
+         * @param options - 批量插入选项
+         * @returns Promise<InsertBatchResult>
+         * @since v1.0.0
+         * @example
+         * const result = await collection('products').insertBatch(largeDataset, {
+         *   batchSize: 1000,
+         *   onProgress: (p) => console.log(`${p.percentage}%`)
+         * });
+         */
+        insertBatch<T = TSchema>(documents: T[], options?: InsertBatchOptions): Promise<InsertBatchResult>;
+
+        /**
+         * 批量更新文档（流式查询+分批更新）
+         * @param filter - 查询条件
+         * @param update - 更新操作（必须使用更新操作符）
+         * @param options - 批量更新选项
+         * @returns Promise<UpdateBatchResult>
+         * @since v1.0.0
+         * @example
+         * const result = await collection('users').updateBatch(
+         *   { status: 'pending' },
+         *   { $set: { status: 'processed' } },
+         *   { batchSize: 5000, onError: 'retry' }
+         * );
+         */
+        updateBatch(
+            filter: Record<string, any>,
+            update: Record<string, any>,
+            options?: UpdateBatchOptions
+        ): Promise<UpdateBatchResult>;
+
+        /**
+         * 批量删除文档（流式查询+分批删除）
+         * @param filter - 查询条件
+         * @param options - 批量删除选项
+         * @returns Promise<DeleteBatchResult>
+         * @since v1.0.0
+         * @example
+         * const result = await collection('logs').deleteBatch(
+         *   { createdAt: { $lt: expireDate } },
+         *   { batchSize: 5000, estimateProgress: true }
+         * );
+         */
+        deleteBatch(
+            filter: Record<string, any>,
+            options?: DeleteBatchOptions
+        ): Promise<DeleteBatchResult>;
+
+        /**
+         * 查询文档并返回总数（便利方法）
+         * @param filter - 查询条件
+         * @param options - 查询选项
+         * @returns Promise<{ documents: T[], total: number }>
+         * @since v1.0.0
+         * @example
+         * const { documents, total } = await collection('users').findAndCount(
+         *   { status: 'active' },
+         *   { limit: 10, cache: 60000 }
+         * );
+         */
+        findAndCount<T = TSchema>(
+            filter?: Record<string, any>,
+            options?: FindOptions
+        ): Promise<{ documents: T[]; total: number }>;
     }
 
+    /**
+     * Collection 类型别名（与 CollectionAccessor 等价）
+     * @since v1.0.4
+     */
+    type Collection<TSchema = any> = CollectionAccessor<TSchema>;
+
     type DbAccessor = {
         collection<TSchema = any>(name: string): CollectionAccessor<TSchema>;
         db(dbName: string): { collection<TSchema = any>(name: string): CollectionAccessor<TSchema> };
@@ -872,7 +1196,7 @@ u        /**
          * @returns Transaction 实例
          * @since v0.2.0
          * @example
-         * const tx = await msq.startTransaction();
+         * const tx = await msq.startSession();
          * try {
          *   await collection('users').updateOne({...}, {...}, { session: tx.session });
          *   await tx.commit();
@@ -880,7 +1204,7 @@ u        /**
          *   await tx.abort();
          * }
          */
-        startTransaction(options?: TransactionOptions): Promise<Transaction>;
+        startSession(options?: TransactionOptions): Promise<Transaction>;
 
         /**
          * 自动管理事务生命周期（推荐）
@@ -1286,4 +1610,367 @@ u        /**
          */
         finally(onfinally?: (() => void) | null): Promise<T[]>;
     }
+
+    // ============================================================================
+    // Model 层类型定义（Model API）
+    // @since v1.0.3
+    // ============================================================================
+
+    /**
+     * Schema DSL 函数类型
+     */
+    type SchemaDSL = (dsl: any) => any;
+
+    /**
+     * Model 定义配置
+     */
+    interface ModelDefinition<T = any> {
+        /**
+         * 枚举配置（可被 schema 引用）
+         * @example
+         * enums: {
+         *   role: 'admin|user|guest',
+         *   status: 'active|inactive'
+         * }
+         */
+        enums?: Record<string, string>;
+
+        /**
+         * Schema 定义（数据验证规则）
+         * 使用 function 时，this 自动绑定到 definition，可访问 this.enums
+         *
+         * @param dsl - schema-dsl 函数
+         * @returns Schema 对象
+         *
+         * @example
+         * // 使用 function（推荐）
+         * schema: function(dsl) {
+         *   return dsl({
+         *     username: 'string:3-32!',
+         *     role: this.enums.role.default('user')
+         *   });
+         * }
+         *
+         * // 使用箭头函数
+         * schema: (dsl) => dsl({
+         *   username: 'string:3-32!',
+         *   email: 'email!'
+         * })
+         */
+        schema: SchemaDSL | ((this: ModelDefinition<T>, dsl: SchemaDSL) => any);
+
+        /**
+         * 自定义方法
+         *
+         * @param model - ModelInstance 实例
+         * @returns 包含 instance 和 static 方法的对象
+         *
+         * @example
+         * methods: (model) => ({
+         *   instance: {
+         *     checkPassword(password: string) {
+         *       return this.password === password;
+         *     }
+         *   },
+         *   static: {
+         *     async findByUsername(username: string) {
+         *       return await model.findOne({ username });
+         *     }
+         *   }
+         * })
+         */
+        methods?: (model: ModelInstance<T>) => {
+            instance?: Record<string, Function>;
+            static?: Record<string, Function>;
+        };
+
+        /**
+         * 生命周期钩子
+         *
+         * @param model - ModelInstance 实例
+         * @returns 包含各操作钩子的对象
+         *
+         * @example
+         * hooks: (model) => ({
+         *   insert: {
+         *     before: async (ctx, docs) => {
+         *       ctx.timestamp = Date.now();
+         *       return { ...docs, createdAt: new Date() };
+         *     },
+         *     after: async (ctx, result) => {
+         *       console.log('插入耗时:', Date.now() - ctx.timestamp);
+         *     }
+         *   }
+         * })
+         */
+        hooks?: (model: ModelInstance<T>) => {
+            find?: {
+                before?: (ctx: HookContext, options: any) => void | Promise<void>;
+                after?: (ctx: HookContext, result: any) => any | Promise<any>;
+            };
+            insert?: {
+                before?: (ctx: HookContext, docs: any) => any | Promise<any>;
+                after?: (ctx: HookContext, result: any) => void | Promise<void>;
+            };
+            update?: {
+                before?: (ctx: HookContext, filter: any, update: any) => [any, any] | Promise<[any, any]>;
+                after?: (ctx: HookContext, result: any) => void | Promise<void>;
+            };
+            delete?: {
+                before?: (ctx: HookContext, filter: any) => void | Promise<void>;
+                after?: (ctx: HookContext, result: any) => void | Promise<void>;
+            };
+        };
+
+        /**
+         * 索引定义（自动创建）
+         *
+         * @example
+         * indexes: [
+         *   { key: { username: 1 }, unique: true },
+         *   { key: { email: 1 }, unique: true },
+         *   { key: { status: 1, createdAt: -1 } }
+         * ]
+         */
+        indexes?: Array<{
+            key: Record<string, 1 | -1>;
+            unique?: boolean;
+            sparse?: boolean;
+            expireAfterSeconds?: number;
+            [key: string]: any;
+        }>;
+
+        /**
+         * 关系定义（预留，未完全实现）
+         */
+        relations?: Record<string, {
+            type: 'hasOne' | 'hasMany' | 'belongsTo';
+            target: string;
+            foreignKey: string;
+        }>;
+
+        /**
+         * Model 选项配置
+         * @since v1.0.3
+         */
+        options?: {
+            /**
+             * 自动时间戳
+             * 启用后自动管理 createdAt 和 updatedAt 字段
+             *
+             * @example
+             * // 简单模式：启用默认字段名
+             * options: { timestamps: true }
+             *
+             * // 自定义字段名
+             * options: {
+             *   timestamps: {
+             *     createdAt: 'created_time',
+             *     updatedAt: 'updated_time'
+             *   }
+             * }
+             *
+             * // 只启用其中一个
+             * options: {
+             *   timestamps: {
+             *     createdAt: true,
+             *     updatedAt: false
+             *   }
+             * }
+             */
+            timestamps?: boolean | {
+                /** 创建时间字段名，false 表示禁用 */
+                createdAt?: boolean | string;
+                /** 更新时间字段名，false 表示禁用 */
+                updatedAt?: boolean | string;
+            };
+
+            /**
+             * 是否启用 Schema 验证（默认 true）
+             * @since v1.0.3
+             */
+            schemaValidation?: boolean;
+
+            /**
+             * 是否启用严格模式（不允许未定义的字段，默认 false）
+             * @since v1.0.3
+             */
+            strict?: boolean;
+
+            /**
+             * 自定义错误消息
+             * @since v1.0.3
+             */
+            messages?: Record<string, string>;
+        };
+    }
+
+    /**
+     * Hook 上下文
+     * 用于在 before 和 after 钩子之间传递数据
+     */
+    interface HookContext {
+        [key: string]: any;
+    }
+
+    /**
+     * 数据验证结果
+     */
+    interface ValidationResult {
+        /** 是否验证通过 */
+        valid: boolean;
+        /** 错误列表 */
+        errors: Array<{
+            field: string;
+            message: string;
+            value?: any;
+        }>;
+        /** 验证后的数据 */
+        data: any;
+    }
+
+    /**
+     * Model 类（静态方法）
+     */
+    class Model {
+        /**
+         * 注册一个 Model 定义
+         *
+         * @param collectionName - 集合名称
+         * @param definition - Model 定义对象
+         * @throws {Error} 集合名称无效、schema 未定义、Model 已存在
+         *
+         * @example
+         * Model.define('users', {
+         *   schema: (dsl) => dsl({
+         *     username: 'string:3-32!',
+         *     email: 'email!'
+         *   }),
+         *   methods: (model) => ({
+         *     instance: {
+         *       checkPassword(password) {
+         *         return this.password === password;
+         *       }
+         *     }
+         *   })
+         * });
+         */
+        static define<T = any>(collectionName: string, definition: ModelDefinition<T>): void;
+
+        /**
+         * 获取已注册的 Model 定义
+         *
+         * @param collectionName - 集合名称
+         * @returns Model 定义对象，如果不存在返回 undefined
+         */
+        static get<T = any>(collectionName: string): ModelDefinition<T> | undefined;
+
+        /**
+         * 检查 Model 是否已注册
+         *
+         * @param collectionName - 集合名称
+         * @returns 是否已注册
+         */
+        static has(collectionName: string): boolean;
+
+        /**
+         * 列出所有已注册的 Model 名称
+         *
+         * @returns Model 名称数组
+         */
+        static list(): string[];
+
+        /**
+         * 清空所有已注册的 Model（仅测试用）
+         * @private
+         */
+        static _clear(): void;
+    }
+
+    /**
+     * ModelInstance 类
+     * 继承 collection 的所有方法，并扩展 Model 特性
+     */
+    interface ModelInstance<T = any> extends Collection<T> {
+        /** 关联的 collection 对象 */
+        readonly collection: Collection<T>;
+
+        /** Model 定义对象 */
+        readonly definition: ModelDefinition<T>;
+
+        /** monSQLize 实例 */
+        readonly msq: MonSQLize;
+
+        /**
+         * 验证数据是否符合 schema 定义
+         *
+         * @param data - 待验证的数据
+         * @param options - 验证选项
+         * @returns 验证结果
+         *
+         * @example
+         * const result = User.validate({
+         *   username: 'test',
+         *   email: 'test@example.com'
+         * });
+         *
+         * if (!result.valid) {
+         *   console.error('验证失败:', result.errors);
+         * }
+         */
+        validate(data: any, options?: { locale?: 'zh-CN' | 'en-US' }): ValidationResult;
+    }
+
+    /**
+     * 扩展 MonSQLize 类，添加 model 方法
+     */
+    interface MonSQLize {
+        /**
+         * 获取已注册的 Model 实例
+         *
+         * @param collectionName - 集合名称
+         * @returns ModelInstance 实例
+         * @throws {Error} 数据库未连接、Model 未定义
+         *
+         * @example
+         * const User = msq.model('users');
+         *
+         * // 使用继承的 collection 方法
+         * const users = await User.find({ status: 'active' });
+         *
+         * // 使用自定义静态方法
+         * const admin = await User.findByUsername('admin');
+         *
+         * // 使用实例方法
+         * const user = await User.findOne({ username: 'test' });
+         * if (user.checkPassword('secret')) {
+         *   console.log('登录成功');
+         * }
+         */
+        model<T = any>(collectionName: string): ModelInstance<T>;
+
+        /**
+         * Model 类引用
+         */
+        Model: typeof Model;
+    }
+
+    /**
+     * 导出 Model 类
+     */
+    export { Model };
+
+    /**
+     * 导出锁错误类型
+     * @since v1.4.0
+     */
+    export { LockAcquireError, LockTimeoutError };
+
+    /**
+     * 导出类型别名
+     * @since v1.0.4
+     */
+    export type { Collection, CollectionAccessor };
 }
+
+