@abtnode/db-cache 1.17.8-beta-20260109-075740-5f484e08 → 1.17.8-beta-20260113-015027-32a1cec4

package/dist/index.d.cts

@@ -6,6 +6,12 @@ interface BaseDBCacheParams {
     sqlitePath: string;
     /** Default TTL (ms) */
     ttl: number;
+    /** Maximum size for LRU cache */
+    lruMaxSize?: number;
+    /** Enable LRU cache */
+    enableLruCache?: boolean;
+    /** Enable sync */
+    enableSync?: boolean;
     /** Cleanup interval (ms) for expired rows in SQLite */
     cleanupInterval?: number;
     /** URL for Redis (falls back to process.env.REDIS_URL if undefined) */
@@ -34,6 +40,11 @@ interface IDBAdapter {
     deserialize(raw: string | null | undefined): unknown;
     close(): Promise<void>;
     flushAll(): Promise<void>;
+    getLruCacheStats(): {
+        size: number;
+        groupCount: number;
+        maxSize: number;
+    } | null;
 }
 
 declare class BaseDBCache {
@@ -62,6 +73,15 @@ declare class BaseDBCache {
     groupDel(key: string, subKey: string): Promise<void>;
     close(): Promise<void>;
     flushAll(): Promise<void>;
+    /**
+     * 获取 LRU 缓存统计信息
+     * @returns 缓存统计信息，如果未启用 LRU 缓存则返回 null
+     */
+    getLruCacheStats(): {
+        size: number;
+        groupCount: number;
+        maxSize: number;
+    } | null;
 }
 
 declare class SingleFlightDBCache extends BaseDBCache {
@@ -134,9 +154,120 @@ interface WithRetryOptions {
 }
 declare function withRetry<T>(fn: () => Promise<T>, { max, backoffBase, backoffExponent, backoffJitter, needRetry, }?: WithRetryOptions): Promise<T>;
 
+interface LruCacheOptions {
+    /** 缓存前缀，用于区分不同的缓存实例 */
+    prefix: string;
+    /** 最大缓存条数，默认 10000 */
+    maxSize?: number;
+    /** 是否启用跨 worker 同步，默认 true（在支持的环境中） */
+    enableSync?: boolean;
+}
+/**
+ * LRU 内存缓存工具类
+ *
+ * 特点：
+ * 1. 基于 LRU 算法的内存缓存
+ * 2. 支持 TTL 过期
+ * 3. 支持 Node.js 集群模式下的跨 worker 同步
+ * 4. 可单独使用，也可作为 Redis/SQLite 适配器的 L1 缓存层
+ *
+ * CLUSTER MODE NOTE:
+ * 当运行在 cluster 模式下时，缓存数据会通过 event hub 广播给所有 worker，
+ * 确保所有 worker 的内存缓存数据一致。
+ */
+declare class LruCache {
+    private static caches;
+    private static groupCaches;
+    private static listenerSetup;
+    private cacheKey;
+    private maxSize;
+    private enableSync;
+    constructor(options: LruCacheOptions);
+    private getCache;
+    private getGroupCaches;
+    private getOrCreateGroupCache;
+    /**
+     * 设置同步监听器，接收其他 worker 广播的缓存数据
+     */
+    private _setupSyncListener;
+    /**
+     * 广播缓存数据给其他 worker
+     */
+    private _broadcastSync;
+    /**
+     * 广播删除缓存给其他 worker
+     */
+    private _broadcastDelete;
+    /**
+     * 广播清空缓存给其他 worker
+     */
+    private _broadcastClear;
+    private isExpired;
+    /**
+     * 设置缓存
+     * @param key 缓存键
+     * @param value 序列化后的值
+     * @param expiresAt 过期时间戳，null 表示永不过期
+     */
+    set(key: string, value: string, expiresAt: number | null): void;
+    /**
+     * 获取缓存
+     * @param key 缓存键
+     * @returns 序列化的值，未命中或过期返回 null
+     */
+    get(key: string): string | null;
+    /**
+     * 检查缓存是否存在且未过期
+     */
+    has(key: string): boolean;
+    /**
+     * 删除缓存
+     */
+    del(key: string): void;
+    /**
+     * 按前缀删除缓存
+     * @returns 删除的数量
+     */
+    delByPrefix(prefix: string): number;
+    /**
+     * 设置分组缓存
+     */
+    groupSet(key: string, subKey: string, value: string, expiresAt: number | null): void;
+    /**
+     * 获取分组缓存
+     */
+    groupGet(key: string, subKey: string): string | null;
+    /**
+     * 检查分组缓存是否存在
+     */
+    groupHas(key: string, subKey: string): boolean;
+    /**
+     * 删除分组缓存
+     */
+    groupDel(key: string, subKey: string): void;
+    /**
+     * 清空所有缓存
+     */
+    clear(): void;
+    /**
+     * 获取缓存统计信息
+     */
+    getStats(): {
+        size: number;
+        groupCount: number;
+        maxSize: number;
+    };
+    /**
+     * 关闭缓存（清理资源）
+     *
+     * 注意：不会广播 close 事件给其他 worker，因为每个 worker 有独立的生命周期
+     */
+    close(): void;
+}
+
 declare const getAbtNodeRedisAndSQLiteUrl: () => {
     redisUrl: string | undefined;
     sqlitePath: string | undefined;
 };
 
-export { type BaseDBCacheOptions, LockDBCache as DBCache, type IDBAdapter, getAbtNodeRedisAndSQLiteUrl, withRetry };
+export { type BaseDBCacheOptions, LockDBCache as DBCache, type ForceType, type IDBAdapter, LruCache, getAbtNodeRedisAndSQLiteUrl, withRetry };

package/dist/index.d.mts

@@ -6,6 +6,12 @@ interface BaseDBCacheParams {
     sqlitePath: string;
     /** Default TTL (ms) */
     ttl: number;
+    /** Maximum size for LRU cache */
+    lruMaxSize?: number;
+    /** Enable LRU cache */
+    enableLruCache?: boolean;
+    /** Enable sync */
+    enableSync?: boolean;
     /** Cleanup interval (ms) for expired rows in SQLite */
     cleanupInterval?: number;
     /** URL for Redis (falls back to process.env.REDIS_URL if undefined) */
@@ -34,6 +40,11 @@ interface IDBAdapter {
     deserialize(raw: string | null | undefined): unknown;
     close(): Promise<void>;
     flushAll(): Promise<void>;
+    getLruCacheStats(): {
+        size: number;
+        groupCount: number;
+        maxSize: number;
+    } | null;
 }
 
 declare class BaseDBCache {
@@ -62,6 +73,15 @@ declare class BaseDBCache {
     groupDel(key: string, subKey: string): Promise<void>;
     close(): Promise<void>;
     flushAll(): Promise<void>;
+    /**
+     * 获取 LRU 缓存统计信息
+     * @returns 缓存统计信息，如果未启用 LRU 缓存则返回 null
+     */
+    getLruCacheStats(): {
+        size: number;
+        groupCount: number;
+        maxSize: number;
+    } | null;
 }
 
 declare class SingleFlightDBCache extends BaseDBCache {
@@ -134,9 +154,120 @@ interface WithRetryOptions {
 }
 declare function withRetry<T>(fn: () => Promise<T>, { max, backoffBase, backoffExponent, backoffJitter, needRetry, }?: WithRetryOptions): Promise<T>;
 
+interface LruCacheOptions {
+    /** 缓存前缀，用于区分不同的缓存实例 */
+    prefix: string;
+    /** 最大缓存条数，默认 10000 */
+    maxSize?: number;
+    /** 是否启用跨 worker 同步，默认 true（在支持的环境中） */
+    enableSync?: boolean;
+}
+/**
+ * LRU 内存缓存工具类
+ *
+ * 特点：
+ * 1. 基于 LRU 算法的内存缓存
+ * 2. 支持 TTL 过期
+ * 3. 支持 Node.js 集群模式下的跨 worker 同步
+ * 4. 可单独使用，也可作为 Redis/SQLite 适配器的 L1 缓存层
+ *
+ * CLUSTER MODE NOTE:
+ * 当运行在 cluster 模式下时，缓存数据会通过 event hub 广播给所有 worker，
+ * 确保所有 worker 的内存缓存数据一致。
+ */
+declare class LruCache {
+    private static caches;
+    private static groupCaches;
+    private static listenerSetup;
+    private cacheKey;
+    private maxSize;
+    private enableSync;
+    constructor(options: LruCacheOptions);
+    private getCache;
+    private getGroupCaches;
+    private getOrCreateGroupCache;
+    /**
+     * 设置同步监听器，接收其他 worker 广播的缓存数据
+     */
+    private _setupSyncListener;
+    /**
+     * 广播缓存数据给其他 worker
+     */
+    private _broadcastSync;
+    /**
+     * 广播删除缓存给其他 worker
+     */
+    private _broadcastDelete;
+    /**
+     * 广播清空缓存给其他 worker
+     */
+    private _broadcastClear;
+    private isExpired;
+    /**
+     * 设置缓存
+     * @param key 缓存键
+     * @param value 序列化后的值
+     * @param expiresAt 过期时间戳，null 表示永不过期
+     */
+    set(key: string, value: string, expiresAt: number | null): void;
+    /**
+     * 获取缓存
+     * @param key 缓存键
+     * @returns 序列化的值，未命中或过期返回 null
+     */
+    get(key: string): string | null;
+    /**
+     * 检查缓存是否存在且未过期
+     */
+    has(key: string): boolean;
+    /**
+     * 删除缓存
+     */
+    del(key: string): void;
+    /**
+     * 按前缀删除缓存
+     * @returns 删除的数量
+     */
+    delByPrefix(prefix: string): number;
+    /**
+     * 设置分组缓存
+     */
+    groupSet(key: string, subKey: string, value: string, expiresAt: number | null): void;
+    /**
+     * 获取分组缓存
+     */
+    groupGet(key: string, subKey: string): string | null;
+    /**
+     * 检查分组缓存是否存在
+     */
+    groupHas(key: string, subKey: string): boolean;
+    /**
+     * 删除分组缓存
+     */
+    groupDel(key: string, subKey: string): void;
+    /**
+     * 清空所有缓存
+     */
+    clear(): void;
+    /**
+     * 获取缓存统计信息
+     */
+    getStats(): {
+        size: number;
+        groupCount: number;
+        maxSize: number;
+    };
+    /**
+     * 关闭缓存（清理资源）
+     *
+     * 注意：不会广播 close 事件给其他 worker，因为每个 worker 有独立的生命周期
+     */
+    close(): void;
+}
+
 declare const getAbtNodeRedisAndSQLiteUrl: () => {
     redisUrl: string | undefined;
     sqlitePath: string | undefined;
 };
 
-export { type BaseDBCacheOptions, LockDBCache as DBCache, type IDBAdapter, getAbtNodeRedisAndSQLiteUrl, withRetry };
+export { type BaseDBCacheOptions, LockDBCache as DBCache, type ForceType, type IDBAdapter, LruCache, getAbtNodeRedisAndSQLiteUrl, withRetry };

package/dist/index.d.ts

@@ -6,6 +6,12 @@ interface BaseDBCacheParams {
     sqlitePath: string;
     /** Default TTL (ms) */
     ttl: number;
+    /** Maximum size for LRU cache */
+    lruMaxSize?: number;
+    /** Enable LRU cache */
+    enableLruCache?: boolean;
+    /** Enable sync */
+    enableSync?: boolean;
     /** Cleanup interval (ms) for expired rows in SQLite */
     cleanupInterval?: number;
     /** URL for Redis (falls back to process.env.REDIS_URL if undefined) */
@@ -34,6 +40,11 @@ interface IDBAdapter {
     deserialize(raw: string | null | undefined): unknown;
     close(): Promise<void>;
     flushAll(): Promise<void>;
+    getLruCacheStats(): {
+        size: number;
+        groupCount: number;
+        maxSize: number;
+    } | null;
 }
 
 declare class BaseDBCache {
@@ -62,6 +73,15 @@ declare class BaseDBCache {
     groupDel(key: string, subKey: string): Promise<void>;
     close(): Promise<void>;
     flushAll(): Promise<void>;
+    /**
+     * 获取 LRU 缓存统计信息
+     * @returns 缓存统计信息，如果未启用 LRU 缓存则返回 null
+     */
+    getLruCacheStats(): {
+        size: number;
+        groupCount: number;
+        maxSize: number;
+    } | null;
 }
 
 declare class SingleFlightDBCache extends BaseDBCache {
@@ -134,9 +154,120 @@ interface WithRetryOptions {
 }
 declare function withRetry<T>(fn: () => Promise<T>, { max, backoffBase, backoffExponent, backoffJitter, needRetry, }?: WithRetryOptions): Promise<T>;
 
+interface LruCacheOptions {
+    /** 缓存前缀，用于区分不同的缓存实例 */
+    prefix: string;
+    /** 最大缓存条数，默认 10000 */
+    maxSize?: number;
+    /** 是否启用跨 worker 同步，默认 true（在支持的环境中） */
+    enableSync?: boolean;
+}
+/**
+ * LRU 内存缓存工具类
+ *
+ * 特点：
+ * 1. 基于 LRU 算法的内存缓存
+ * 2. 支持 TTL 过期
+ * 3. 支持 Node.js 集群模式下的跨 worker 同步
+ * 4. 可单独使用，也可作为 Redis/SQLite 适配器的 L1 缓存层
+ *
+ * CLUSTER MODE NOTE:
+ * 当运行在 cluster 模式下时，缓存数据会通过 event hub 广播给所有 worker，
+ * 确保所有 worker 的内存缓存数据一致。
+ */
+declare class LruCache {
+    private static caches;
+    private static groupCaches;
+    private static listenerSetup;
+    private cacheKey;
+    private maxSize;
+    private enableSync;
+    constructor(options: LruCacheOptions);
+    private getCache;
+    private getGroupCaches;
+    private getOrCreateGroupCache;
+    /**
+     * 设置同步监听器，接收其他 worker 广播的缓存数据
+     */
+    private _setupSyncListener;
+    /**
+     * 广播缓存数据给其他 worker
+     */
+    private _broadcastSync;
+    /**
+     * 广播删除缓存给其他 worker
+     */
+    private _broadcastDelete;
+    /**
+     * 广播清空缓存给其他 worker
+     */
+    private _broadcastClear;
+    private isExpired;
+    /**
+     * 设置缓存
+     * @param key 缓存键
+     * @param value 序列化后的值
+     * @param expiresAt 过期时间戳，null 表示永不过期
+     */
+    set(key: string, value: string, expiresAt: number | null): void;
+    /**
+     * 获取缓存
+     * @param key 缓存键
+     * @returns 序列化的值，未命中或过期返回 null
+     */
+    get(key: string): string | null;
+    /**
+     * 检查缓存是否存在且未过期
+     */
+    has(key: string): boolean;
+    /**
+     * 删除缓存
+     */
+    del(key: string): void;
+    /**
+     * 按前缀删除缓存
+     * @returns 删除的数量
+     */
+    delByPrefix(prefix: string): number;
+    /**
+     * 设置分组缓存
+     */
+    groupSet(key: string, subKey: string, value: string, expiresAt: number | null): void;
+    /**
+     * 获取分组缓存
+     */
+    groupGet(key: string, subKey: string): string | null;
+    /**
+     * 检查分组缓存是否存在
+     */
+    groupHas(key: string, subKey: string): boolean;
+    /**
+     * 删除分组缓存
+     */
+    groupDel(key: string, subKey: string): void;
+    /**
+     * 清空所有缓存
+     */
+    clear(): void;
+    /**
+     * 获取缓存统计信息
+     */
+    getStats(): {
+        size: number;
+        groupCount: number;
+        maxSize: number;
+    };
+    /**
+     * 关闭缓存（清理资源）
+     *
+     * 注意：不会广播 close 事件给其他 worker，因为每个 worker 有独立的生命周期
+     */
+    close(): void;
+}
+
 declare const getAbtNodeRedisAndSQLiteUrl: () => {
     redisUrl: string | undefined;
     sqlitePath: string | undefined;
 };
 
-export { type BaseDBCacheOptions, LockDBCache as DBCache, type IDBAdapter, getAbtNodeRedisAndSQLiteUrl, withRetry };
+export { type BaseDBCacheOptions, LockDBCache as DBCache, type ForceType, type IDBAdapter, LruCache, getAbtNodeRedisAndSQLiteUrl, withRetry };