monsqlize 1.0.0 → 1.0.2

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
@@ -302,6 +391,16 @@ declare module 'monsqlize' {
         wtimeout?: number;               // 写超时时间（毫秒）
     }
 
+    /**
+     * 简化的插入选项（用于简化调用形式）
+     */
+    interface InsertOneSimplifiedOptions {
+        writeConcern?: WriteConcern;     // 写确认级别（可选）
+        bypassDocumentValidation?: boolean; // 跳过文档验证（可选）
+        comment?: string;                // 查询注释（用于生产环境日志跟踪）
+        session?: any;                   // 事务会话
+    }
+
     interface InsertOneOptions {
         document: any;                   // 要插入的文档
         writeConcern?: WriteConcern;     // 写确认级别（可选）
@@ -314,6 +413,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 +594,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 查询单个文档（便利方法）
@@ -563,9 +673,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 +683,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 +704,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>;
 
         /**
@@ -672,8 +785,8 @@ u        /**
     }
 
     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,6 +826,46 @@ 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 - 事务选项
@@ -745,6 +898,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;
     }
 
     // ============================================================================

package/lib/cache.js

@@ -13,7 +13,7 @@ class Cache {
             enableStats: options.enableStats !== false, // 启用统计信息
             ...options
         };
-        
+
         // 统计信息
         this.stats = {
             hits: 0,
@@ -141,13 +141,13 @@ class Cache {
     async delPattern(pattern) {
         const regex = this._patternToRegex(pattern);
         const keysToDelete = [];
-        
+
         for (const key of this.cache.keys()) {
             if (regex.test(key)) {
                 keysToDelete.push(key);
             }
         }
-        
+
 
         return await this.delMany(keysToDelete);
     }
@@ -231,7 +231,7 @@ class Cache {
     _estimateSize(key, value) {
         const keySize = typeof key === 'string' ? key.length * 2 : 8;
         let valueSize = 8; // 默认值
-        
+
         if (typeof value === 'string') {
             valueSize = value.length * 2;
         } else if (typeof value === 'object' && value !== null) {
@@ -241,7 +241,7 @@ class Cache {
                 valueSize = 100; // 估算值
             }
         }
-        
+
         return keySize + valueSize;
     }
 
@@ -471,7 +471,7 @@ module.exports = class CacheFactory {
         return (op, base = {}, fetcher) => {
             // 检查是否在事务中
             const inTransaction = base.session && base.session.__monSQLizeTransaction;
-            
+
             // 事务内默认不缓存（除非显式指定 cache）
             let ttl = 0;
             if (inTransaction) {
@@ -481,11 +481,11 @@ module.exports = class CacheFactory {
                 // 非事务：正常处理 cache 参数
                 ttl = base.cache ? Number(base.cache) : 0;
             }
-            
+
             // 使用浅拷贝构建用于键的对象，避免修改调用方入参
             const { cache: _cacheTTL, maxTimeMS: _maxTimeMS, session: _session, ...keyBase } = base || {};
             const key = this.buildCacheKey({ ...ctx, op, base: keyBase });
             return this.readThrough(cache, ttl, key, fetcher);
         };
     }
-}
+};

package/lib/common/validation.js

@@ -46,4 +46,67 @@ function assertCursorSortCompatible(currentSort, cursorSort) {
     }
 }
 
-module.exports = { validateLimitAfterBefore, assertCursorSortCompatible };
+/**
+ * 验证数值范围
+ * @param {number} value - 要验证的数值
+ * @param {number} min - 最小值（包含）
+ * @param {number} max - 最大值（包含）
+ * @param {string} name - 参数名称（用于错误消息）
+ * @returns {number} 验证通过后的值
+ * @throws {Error} 当值不在有效范围内时抛出 INVALID_ARGUMENT 错误
+ */
+function validateRange(value, min, max, name) {
+    const { ErrorCodes, createError } = require('../errors');
+
+    // 检查是否为有效数字
+    if (typeof value !== 'number' || isNaN(value)) {
+        throw createError(
+            ErrorCodes.INVALID_ARGUMENT,
+            `${name} 必须是一个有效的数字`
+        );
+    }
+
+    // 检查是否为有限数（排除 Infinity）
+    if (!isFinite(value)) {
+        throw createError(
+            ErrorCodes.INVALID_ARGUMENT,
+            `${name} 必须是有限数字`
+        );
+    }
+
+    // 检查范围
+    if (value < min || value > max) {
+        throw createError(
+            ErrorCodes.INVALID_ARGUMENT,
+            `${name} 必须在 ${min} 到 ${max} 之间，当前值: ${value}`
+        );
+    }
+
+    return value;
+}
+
+/**
+ * 验证正整数
+ * @param {number} value - 要验证的数值
+ * @param {string} name - 参数名称（用于错误消息）
+ * @returns {number} 验证通过后的值
+ * @throws {Error} 当值不是正整数时抛出错误
+ */
+function validatePositiveInteger(value, name) {
+    const { ErrorCodes, createError } = require('../errors');
+
+    if (!Number.isInteger(value) || value <= 0) {
+        throw createError(
+            ErrorCodes.INVALID_ARGUMENT,
+            `${name} 必须是正整数，当前值: ${value}`
+        );
+    }
+    return value;
+}
+
+module.exports = {
+    validateLimitAfterBefore,
+    assertCursorSortCompatible,
+    validateRange,
+    validatePositiveInteger
+};

package/lib/connect.js

@@ -68,9 +68,9 @@ module.exports = class ConnectionManager {
         const db = (databaseName)=>{
             return {
                 collection:(collectionName)=>instance.collection(databaseName, collectionName)
-            }
-        }
+            };
+        };
 
         return { collection, db, instance };
     }
-}
+};

package/lib/errors.js

@@ -43,6 +43,10 @@ const ErrorCodes = {
     DOCUMENTS_REQUIRED: 'DOCUMENTS_REQUIRED',
     DUPLICATE_KEY: 'DUPLICATE_KEY',
     WRITE_CONFLICT: 'WRITE_CONFLICT',
+
+    // 🆕 v1.4.0: 锁相关错误
+    LOCK_ACQUIRE_FAILED: 'LOCK_ACQUIRE_FAILED',
+    LOCK_TIMEOUT: 'LOCK_TIMEOUT',
 };
 
 /**
@@ -145,6 +149,9 @@ function createWriteError(operation, message, cause = null) {
     );
 }
 
+// 🆕 v1.4.0: 导入锁错误类
+const { LockAcquireError, LockTimeoutError } = require('./lock/errors');
+
 module.exports = {
     ErrorCodes,
     createError,
@@ -153,5 +160,8 @@ module.exports = {
     createConnectionError,
     createQueryTimeoutError,
     createWriteError,
+    // 🆕 v1.4.0: 锁错误类
+    LockAcquireError,
+    LockTimeoutError,
 };