monsqlize 1.0.1 → 1.0.5

package/index.d.ts

@@ -51,6 +51,95 @@ declare module 'monsqlize' {
     // 事务相关类型定义（Transaction API）
     // ============================================================================
 
+    /**
+     * 业务锁配置选项
+     * @since v1.4.0
+     */
+    interface LockOptions {
+        /** 锁过期时间（毫秒），默认 10000 */
+        ttl?: number;
+        /** 获取锁失败时的重试次数，默认 3 */
+        retryTimes?: number;
+        /** 重试间隔（毫秒），默认 100 */
+        retryDelay?: number;
+        /** Redis 不可用时是否降级为无锁执行，默认 false */
+        fallbackToNoLock?: boolean;
+    }
+
+    /**
+     * 锁对象
+     * 表示一个已获取的锁，提供释放和续期方法
+     * @since v1.4.0
+     */
+    interface Lock {
+        /** 锁的 Key */
+        readonly key: string;
+        /** 锁的唯一ID */
+        readonly lockId: string;
+        /** 是否已释放 */
+        readonly released: boolean;
+
+        /**
+         * 释放锁
+         * @returns Promise<boolean> 是否成功释放
+         */
+        release(): Promise<boolean>;
+
+        /**
+         * 续期（延长 TTL）
+         * @param ttl - 新的过期时间（毫秒），默认使用原TTL
+         * @returns Promise<boolean> 是否成功续期
+         */
+        renew(ttl?: number): Promise<boolean>;
+
+        /**
+         * 检查锁是否仍被持有
+         * @returns boolean
+         */
+        isHeld(): boolean;
+
+        /**
+         * 获取锁持有时间（毫秒）
+         * @returns number
+         */
+        getHoldTime(): number;
+    }
+
+    /**
+     * 锁统计信息
+     * @since v1.4.0
+     */
+    interface LockStats {
+        /** 成功获取锁的次数 */
+        locksAcquired: number;
+        /** 成功释放锁的次数 */
+        locksReleased: number;
+        /** 锁检查次数 */
+        lockChecks: number;
+        /** 错误次数 */
+        errors: number;
+        /** 锁键前缀 */
+        lockKeyPrefix: string;
+        /** 锁最大持续时间 */
+        maxDuration: number;
+    }
+
+    /**
+     * 锁获取失败错误
+     * @since v1.4.0
+     */
+    class LockAcquireError extends Error {
+        readonly code: 'LOCK_ACQUIRE_FAILED';
+    }
+
+    /**
+     * 锁超时错误
+     * @since v1.4.0
+     */
+    class LockTimeoutError extends Error {
+        readonly code: 'LOCK_TIMEOUT';
+    }
+
     /**
      * MongoDB 事务会话（原生 ClientSession）
      * @since v0.2.0
@@ -190,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：本地+远端双写（等待远端完成）
@@ -222,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; // 全局默认查询超时（毫秒）
@@ -249,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[];
@@ -277,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;              // 查询超时时间（毫秒）
@@ -302,6 +637,16 @@ declare module 'monsqlize' {
         wtimeout?: number;               // 写超时时间（毫秒）
     }
 
+    /**
+     * 简化的插入选项（用于简化调用形式）
+     */
+    interface InsertOneSimplifiedOptions {
+        writeConcern?: WriteConcern;     // 写确认级别（可选）
+        bypassDocumentValidation?: boolean; // 跳过文档验证（可选）
+        comment?: string;                // 查询注释（用于生产环境日志跟踪）
+        session?: any;                   // 事务会话
+    }
+
     interface InsertOneOptions {
         document: any;                   // 要插入的文档
         writeConcern?: WriteConcern;     // 写确认级别（可选）
@@ -314,6 +659,17 @@ declare module 'monsqlize' {
         insertedId: any;                 // 插入的文档 _id
     }
 
+    /**
+     * 简化的批量插入选项（用于简化调用形式）
+     */
+    interface InsertManySimplifiedOptions {
+        ordered?: boolean;               // 是否有序插入（默认 true）
+        writeConcern?: WriteConcern;     // 写确认级别（可选）
+        bypassDocumentValidation?: boolean; // 跳过文档验证（可选）
+        comment?: string;                // 查询注释（用于生产环境日志跟踪）
+        session?: any;                   // 事务会话
+    }
+
     interface InsertManyOptions {
         documents: any[];                // 要插入的文档数组
         ordered?: boolean;               // 是否有序插入（默认 true）
@@ -484,16 +840,16 @@ declare module 'monsqlize' {
         driver?: { connected: boolean };
     }
 
-    interface CollectionAccessor {
+    interface CollectionAccessor<TSchema = any> {
         getNamespace(): { iid: string; type: string; db: string; collection: string };
         dropCollection(): Promise<boolean>;
         createCollection(name?: string | null, options?: any): Promise<boolean>;
         createView(viewName: string, source: string, pipeline?: any[]): Promise<boolean>;
 
-        // findOne 重载：支持 meta 参数
-        findOne(query?: any, options?: Omit<FindOptions, 'meta'>): Promise<any | null>;
-        findOne(query: any, options: FindOptions & { meta: true | MetaOptions }): Promise<ResultWithMeta<any | null>>;
-        findOne(query?: any, options?: FindOptions): Promise<any | null | ResultWithMeta<any | null>>;
+        // findOne 重载：支持 meta 参数和泛型
+        findOne<T = TSchema>(query?: any, options?: Omit<FindOptions, 'meta'>): Promise<T | null>;
+        findOne<T = TSchema>(query: any, options: FindOptions & { meta: true | MetaOptions }): Promise<ResultWithMeta<T | null>>;
+        findOne<T = TSchema>(query?: any, options?: FindOptions): Promise<T | null | ResultWithMeta<T | null>>;
 
         /**
          * 通过 _id 查询单个文档（便利方法）
@@ -518,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 - 查询选项
@@ -563,9 +919,9 @@ u        /**
         ): Promise<any[]>;
 
         // find 重载：支持 meta 参数和链式调用 (v2.0+)
-        find<T = any>(query?: any): FindChain<T>;
-        find<T = any>(query: any, options: FindOptions & { meta: true | MetaOptions }): Promise<ResultWithMeta<T[]>>;
-        find<T = any>(query?: any, options?: FindOptions): Promise<T[]> | FindChain<T> | ResultWithMeta<T[]>;
+        find<T = TSchema>(query?: any): FindChain<T>;
+        find<T = TSchema>(query: any, options: FindOptions & { meta: true | MetaOptions }): Promise<ResultWithMeta<T[]>>;
+        find<T = TSchema>(query?: any, options?: FindOptions): Promise<T[]> | FindChain<T> | ResultWithMeta<T[]>;
 
         // count 重载：支持 meta 参数
         count(query?: any, options?: Omit<CountOptions, 'meta'>): Promise<number>;
@@ -573,9 +929,9 @@ u        /**
         count(query?: any, options?: CountOptions): Promise<number | ResultWithMeta<number>>;
 
         // aggregate 重载：支持 meta 参数和链式调用 (v2.0+)
-        aggregate<T = any>(pipeline?: any[]): AggregateChain<T>;
-        aggregate<T = any>(pipeline: any[], options: AggregateOptions & { meta: true | MetaOptions }): Promise<ResultWithMeta<T[]>>;
-        aggregate<T = any>(pipeline?: any[], options?: AggregateOptions): Promise<T[]> | AggregateChain<T> | ResultWithMeta<T[]>;
+        aggregate<T = TSchema>(pipeline?: any[]): AggregateChain<T>;
+        aggregate<T = TSchema>(pipeline: any[], options: AggregateOptions & { meta: true | MetaOptions }): Promise<ResultWithMeta<T[]>>;
+        aggregate<T = TSchema>(pipeline?: any[], options?: AggregateOptions): Promise<T[]> | AggregateChain<T> | ResultWithMeta<T[]>;
 
         // distinct 重载：支持 meta 参数
         distinct<T = any>(field: string, query?: any, options?: Omit<DistinctOptions, 'meta'>): Promise<T[]>;
@@ -594,10 +950,13 @@ u        /**
         clearBookmarks(keyDims?: BookmarkKeyDims): Promise<ClearBookmarksResult>;
 
         // findPage：已在 PageResult 中包含 meta 字段，无需重载
-        findPage(options: FindPageOptions): Promise<PageResult>;
+        findPage<T = TSchema>(options: FindPageOptions): Promise<PageResult<T>>;
 
-        // 写入操作
+        // 写入操作 - 支持简化调用和完整配置
+        insertOne<T = TSchema>(document: T, options?: InsertOneSimplifiedOptions): Promise<InsertOneResult>;
         insertOne(options: InsertOneOptions): Promise<InsertOneResult>;
+
+        insertMany<T = TSchema>(documents: T[], options?: InsertManySimplifiedOptions): Promise<InsertManyResult>;
         insertMany(options: InsertManyOptions): Promise<InsertManyResult>;
 
         /**
@@ -669,11 +1028,89 @@ 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: (name: string) => CollectionAccessor;
-        db: (dbName: string) => { collection: (name: string) => CollectionAccessor };
+        collection<TSchema = any>(name: string): CollectionAccessor<TSchema>;
+        db(dbName: string): { collection<TSchema = any>(name: string): CollectionAccessor<TSchema> };
     };
 
     export default class MonSQLize {
@@ -713,13 +1150,53 @@ u        /**
         /** 健康检查 */
         health(): Promise<HealthView>;
 
+        /**
+         * 获取慢查询日志（持久化存储）
+         * @param filter - 查询条件（可选）
+         * @param options - 查询选项（可选）
+         * @returns 慢查询日志数组
+         * @since v1.3.1
+         * @example
+         * // 查询所有慢查询
+         * const logs = await msq.getSlowQueryLogs({}, { limit: 10 });
+         *
+         * // 按collection过滤
+         * const userLogs = await msq.getSlowQueryLogs(
+         *   { collection: 'users' },
+         *   { sort: { count: -1 }, limit: 10 }
+         * );
+         *
+         * // 按操作类型过滤
+         * const findLogs = await msq.getSlowQueryLogs({ operation: 'find' });
+         */
+        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;
+        }>>;
+
         /**
          * 创建手动事务会话
          * @param options - 事务选项
          * @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();
@@ -727,7 +1204,7 @@ u        /**
          *   await tx.abort();
          * }
          */
-        startTransaction(options?: TransactionOptions): Promise<Transaction>;
+        startSession(options?: TransactionOptions): Promise<Transaction>;
 
         /**
          * 自动管理事务生命周期（推荐）
@@ -745,6 +1222,90 @@ u        /**
             callback: (transaction: Transaction) => Promise<T>,
             options?: TransactionOptions
         ): Promise<T>;
+
+        // ============================================================================
+        // 业务锁 API (v1.4.0+)
+        // ============================================================================
+
+        /**
+         * 业务锁：自动管理锁生命周期（推荐）
+         * @param key - 锁的唯一标识
+         * @param callback - 获取锁后执行的函数
+         * @param options - 锁选项
+         * @returns callback 的返回值
+         * @since v1.4.0
+         * @example
+         * // 库存扣减
+         * await db.withLock('inventory:SKU123', async () => {
+         *   const product = await inventory.findOne({ sku: 'SKU123' });
+         *   if (product.stock >= 1) {
+         *     await inventory.updateOne({ sku: 'SKU123' }, { $inc: { stock: -1 } });
+         *   }
+         * });
+         */
+        withLock?<T = any>(
+            key: string,
+            callback: () => Promise<T>,
+            options?: LockOptions
+        ): Promise<T>;
+
+        /**
+         * 业务锁：手动获取锁（阻塞重试）
+         * @param key - 锁的唯一标识
+         * @param options - 锁选项
+         * @returns Lock 对象
+         * @since v1.4.0
+         * @example
+         * const lock = await db.acquireLock('resource:123', { ttl: 5000 });
+         * try {
+         *   // 业务逻辑
+         * } finally {
+         *   await lock.release();
+         * }
+         */
+        acquireLock?(key: string, options?: LockOptions): Promise<Lock>;
+
+        /**
+         * 业务锁：尝试获取锁（不阻塞）
+         * @param key - 锁的唯一标识
+         * @param options - 锁选项（不包含 retryTimes）
+         * @returns Lock 对象或 null
+         * @since v1.4.0
+         * @example
+         * const lock = await db.tryAcquireLock('resource:123');
+         * if (lock) {
+         *   try {
+         *     // 业务逻辑
+         *   } finally {
+         *     await lock.release();
+         *   }
+         * } else {
+         *   console.log('资源被占用');
+         * }
+         */
+        tryAcquireLock?(key: string, options?: Omit<LockOptions, 'retryTimes'>): Promise<Lock | null>;
+
+        /**
+         * 获取锁统计信息
+         * @returns 锁统计信息
+         * @since v1.4.0
+         * @example
+         * const stats = db.getLockStats();
+         * console.log(stats.locksAcquired, stats.locksReleased);
+         */
+        getLockStats?(): LockStats;
+
+        /**
+         * 创建 Redis 缓存适配器（静态方法）
+         * @param client - Redis 客户端实例（ioredis）
+         * @param options - 可选配置
+         * @returns Redis 缓存适配器实例
+         * @example
+         * const Redis = require('ioredis');
+         * const redis = new Redis();
+         * const redisCache = MonSQLize.createRedisCacheAdapter(redis);
+         */
+        static createRedisCacheAdapter(client: any, options?: any): CacheLike;
     }
 
     // ============================================================================
@@ -1049,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 };
 }
+
+