@taicode/common-base 1.7.1 → 1.7.3

package/output/flow-queue/index.d.ts

@@ -0,0 +1,3 @@
+export { FlowQueue } from './flow-queue';
+export type { FlowQueueOptions, FlowQueueProcessor, FlowQueueRetryStrategy, FlowQueueRetryConfig, FlowQueueDelayConfig, FlowQueueOnGenerate } from './flow-queue';
+//# sourceMappingURL=index.d.ts.map

package/output/flow-queue/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../source/flow-queue/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AACxC,YAAY,EACV,gBAAgB,EAChB,kBAAkB,EAClB,sBAAsB,EACtB,oBAAoB,EACpB,oBAAoB,EACpB,mBAAmB,EACpB,MAAM,cAAc,CAAA"}

package/output/flow-queue/index.js

@@ -0,0 +1,3 @@
+// Flow Queue 模块入口
+// 提供流式处理队列功能，支持重试、延迟等高级特性
+export { FlowQueue } from './flow-queue';

package/output/index.d.ts

@@ -3,6 +3,7 @@ export * from './event-emitter';
 export * from './logger';
 export * from './error';
 export * from './service';
+export * from './ttl-cache';
 export * from './lru-cache';
 export * from './ring-cache';
 export * from './batching-buffer';
@@ -13,4 +14,5 @@ export * from './number';
 export * from './catch';
 export * from './debounce';
 export * from './throttle';
+export * from './flow-queue';
 //# sourceMappingURL=index.d.ts.map

package/output/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../source/index.ts"],"names":[],"mappings":"AACA,cAAc,YAAY,CAAA;AAG1B,cAAc,iBAAiB,CAAA;AAG/B,cAAc,UAAU,CAAA;AAGxB,cAAc,SAAS,CAAA;AAGvB,cAAc,WAAW,CAAA;AAGzB,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAG5B,cAAc,mBAAmB,CAAA;AAGjC,cAAc,UAAU,CAAA;AACxB,cAAc,SAAS,CAAA;AACvB,cAAc,UAAU,CAAA;AACxB,cAAc,UAAU,CAAA;AACxB,cAAc,SAAS,CAAA;AAGvB,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../source/index.ts"],"names":[],"mappings":"AACA,cAAc,YAAY,CAAA;AAG1B,cAAc,iBAAiB,CAAA;AAG/B,cAAc,UAAU,CAAA;AAGxB,cAAc,SAAS,CAAA;AAGvB,cAAc,WAAW,CAAA;AAGzB,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAG5B,cAAc,mBAAmB,CAAA;AAGjC,cAAc,UAAU,CAAA;AACxB,cAAc,SAAS,CAAA;AACvB,cAAc,UAAU,CAAA;AACxB,cAAc,UAAU,CAAA;AACxB,cAAc,SAAS,CAAA;AAGvB,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA;AAE1B,cAAc,cAAc,CAAA"}

package/output/index.js

@@ -9,6 +9,7 @@ export * from './error';
 // === 服务管理 ===
 export * from './service';
 // === 缓存系统 ===
+export * from './ttl-cache';
 export * from './lru-cache';
 export * from './ring-cache';
 // === 数据管理 ===
@@ -22,3 +23,4 @@ export * from './catch';
 // === 函数增强 ===
 export * from './debounce';
 export * from './throttle';
+export * from './flow-queue';

package/output/logger/logger.d.ts

@@ -1,5 +1,5 @@
-import { LogFormatter } from './formatter';
 import { LogTransport } from './transport';
+import { LogFormatter } from './formatter';
 export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
 export interface LoggerOptions {
     level?: LogLevel;
@@ -12,8 +12,8 @@ export interface LoggerOptions {
 }
 export declare class Logger {
     private _level;
-    private transports;
     private formatter;
+    private transports;
     private print?;
     constructor(options?: LoggerOptions);
     private defaultPrint;
@@ -48,7 +48,7 @@ export declare class Logger {
     /**
      * 关闭所有 LogTransports
      */
-    close(): Promise<void>;
+    closeTransports(): Promise<void>;
     /**
      * Pino 兼容的 child 方法
      * 创建一个共享配置的子 logger

package/output/logger/logger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../source/logger/logger.ts"],"names":[],"mappings":"AACA,OAAO,EAA4C,YAAY,EAAE,MAAM,aAAa,CAAA;AACpF,OAAO,EAAE,YAAY,EAAa,MAAM,aAAa,CAAA;AAErD,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAA;AAE9E,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE,QAAQ,CAAA;IAChB,oCAAoC;IACpC,UAAU,CAAC,EAAE,YAAY,EAAE,CAAA;IAC3B,aAAa;IACb,SAAS,CAAC,EAAE,YAAY,CAAA;IACxB,0BAA0B;IAC1B,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAA;CAClD;AAED,qBAAa,MAAM;IACjB,OAAO,CAAC,MAAM,CAAU;IACxB,OAAO,CAAC,UAAU,CAAgB;IAClC,OAAO,CAAC,SAAS,CAAc;IAC/B,OAAO,CAAC,KAAK,CAAC,CAA2C;gBAE7C,OAAO,GAAE,aAAkB;IAYvC,OAAO,CAAC,YAAY;IA0BpB,OAAO,CAAC,SAAS;IAKjB;;OAEG;IACH,OAAO,CAAC,eAAe;IA2BvB;;OAEG;IACH,OAAO,CAAC,UAAU;IAUlB,KAAK,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE;IAOpB,KAAK,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE;IAOpB,IAAI,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE;IAOnB,IAAI,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE;IAOnB,KAAK,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE;IAOpB,KAAK,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE;IAOpB,MAAM;IAIN;;OAEG;IACH,YAAY,CAAC,SAAS,EAAE,YAAY,GAAG,IAAI;IAI3C;;OAEG;IACH,eAAe,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI;IAI5C;;OAEG;IACH,aAAa,IAAI,SAAS,YAAY,EAAE;IAIxC;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ5B;;;OAGG;IACH,KAAK,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG,MAAM;IAkB/E;;OAEG;IACH,IAAI,KAAK,IAAI,QAAQ,CAEpB;IAED,IAAI,KAAK,CAAC,QAAQ,EAAE,QAAQ,EAE3B;CACF;AAED,eAAO,MAAM,MAAM,QAAe,CAAA"}
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../source/logger/logger.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAa,MAAM,aAAa,CAAA;AACrD,OAAO,EAAuB,YAAY,EAAE,MAAM,aAAa,CAAA;AAE/D,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAA;AAE9E,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE,QAAQ,CAAA;IAChB,oCAAoC;IACpC,UAAU,CAAC,EAAE,YAAY,EAAE,CAAA;IAC3B,aAAa;IACb,SAAS,CAAC,EAAE,YAAY,CAAA;IACxB,0BAA0B;IAC1B,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAA;CAClD;AAED,qBAAa,MAAM;IACjB,OAAO,CAAC,MAAM,CAAU;IACxB,OAAO,CAAC,SAAS,CAAc;IAC/B,OAAO,CAAC,UAAU,CAAgB;IAClC,OAAO,CAAC,KAAK,CAAC,CAA2C;gBAE7C,OAAO,GAAE,aAAkB;IAYvC,OAAO,CAAC,YAAY;IA0BpB,OAAO,CAAC,SAAS;IAKjB;;OAEG;IACH,OAAO,CAAC,eAAe;IA2BvB;;OAEG;IACH,OAAO,CAAC,UAAU;IAUlB,KAAK,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE;IAOpB,KAAK,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE;IAOpB,IAAI,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE;IAOnB,IAAI,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE;IAOnB,KAAK,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE;IAOpB,KAAK,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE;IAOpB,MAAM;IAIN;;OAEG;IACH,YAAY,CAAC,SAAS,EAAE,YAAY,GAAG,IAAI;IAI3C;;OAEG;IACH,eAAe,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI;IAI5C;;OAEG;IACH,aAAa,IAAI,SAAS,YAAY,EAAE;IAIxC;;OAEG;IACG,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC;IAQtC;;;OAGG;IACH,KAAK,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG,MAAM;IAkB/E;;OAEG;IACH,IAAI,KAAK,IAAI,QAAQ,CAEpB;IAED,IAAI,KAAK,CAAC,QAAQ,EAAE,QAAQ,EAE3B;CACF;AAED,eAAO,MAAM,MAAM,QAAe,CAAA"}

package/output/logger/logger.js

@@ -1,9 +1,8 @@
-// 基础 Logger 实现，支持简单的日志输出和扩展能力
 import { defaultLogFormatter } from './formatter';
 export class Logger {
     _level;
-    transports;
     formatter;
+    transports;
     print;
     constructor(options = {}) {
         this._level = options.level || 'info';
@@ -143,7 +142,7 @@ export class Logger {
     /**
      * 关闭所有 LogTransports
      */
-    async close() {
+    async closeTransports() {
         const closePromises = this.transports
             .map(transport => transport.close?.())
             .filter(Boolean);

package/output/logger/logger.test.js

@@ -229,7 +229,7 @@ describe('Logger Transport 集成', () => {
             close: mockClose2
         };
         const logger = new Logger({ transports: [transport1, transport2] });
-        await logger.close();
+        await logger.closeTransports();
         expect(mockClose1).toHaveBeenCalled();
         expect(mockClose2).toHaveBeenCalled();
     });

package/output/ttl-cache/index.d.ts

@@ -0,0 +1,2 @@
+export { TtlCache, type TtlCacheOptions, type TtlCacheStats } from './ttl-cache';
+//# sourceMappingURL=index.d.ts.map

package/output/ttl-cache/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../source/ttl-cache/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,KAAK,eAAe,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAA"}

package/output/ttl-cache/index.js

@@ -0,0 +1 @@
+export { TtlCache } from './ttl-cache';

package/output/ttl-cache/ttl-cache.d.ts

@@ -0,0 +1,148 @@
+/**
+ * TTL 缓存配置选项
+ */
+export interface TtlCacheOptions {
+    /** 默认 TTL 时间（毫秒），默认为 5 分钟 */
+    defaultTtl?: number;
+    /** 清理间隔（毫秒），默认为 1 分钟 */
+    cleanupInterval?: number;
+    /** 最大缓存条目数量，默认无限制 */
+    maxSize?: number;
+    /** 是否启用自动清理，默认为 true */
+    enableCleanup?: boolean;
+}
+/**
+ * TTL 缓存统计信息
+ */
+export interface TtlCacheStats {
+    /** 当前条目数量 */
+    size: number;
+    /** 最大条目数量限制 */
+    maxSize?: number;
+    /** 命中次数 */
+    hits: number;
+    /** 未命中次数 */
+    misses: number;
+    /** 过期次数 */
+    expiredCount: number;
+    /** 命中率 */
+    hitRate: number;
+}
+/**
+ * TTL（Time To Live）缓存实现
+ * 支持过期时间、自动清理、统计信息等功能
+ *
+ * 特点：
+ * - 支持为每个条目设置独立的 TTL
+ * - 自动定期清理过期条目
+ * - 支持最大容量限制
+ * - 提供详细的统计信息
+ * - 优雅的资源清理机制
+ */
+export declare class TtlCache<T> {
+    private cache;
+    private cleanupTimer?;
+    private readonly options;
+    private stats;
+    constructor(options?: TtlCacheOptions);
+    /**
+     * 设置缓存项
+     * @param key 缓存键
+     * @param value 缓存值
+     * @param ttl 过期时间（毫秒），默认使用构造函数中的值
+     */
+    set(key: string, value: T, ttl?: number): void;
+    /**
+     * 获取缓存项
+     * @param key 缓存键
+     * @returns 缓存值或 undefined
+     */
+    get(key: string): T | undefined;
+    /**
+     * 检查缓存项是否存在且未过期
+     * @param key 缓存键
+     */
+    has(key: string): boolean;
+    /**
+     * 删除缓存项
+     * @param key 缓存键
+     * @returns 是否成功删除
+     */
+    delete(key: string): boolean;
+    /**
+     * 清空所有缓存
+     */
+    clear(): void;
+    /**
+     * 获取当前缓存大小
+     */
+    get size(): number;
+    /**
+     * 获取缓存容量
+     */
+    get capacity(): number;
+    /**
+     * 获取所有未过期的键
+     */
+    keys(): string[];
+    /**
+     * 获取所有未过期的值
+     */
+    values(): T[];
+    /**
+     * 获取所有未过期的键值对
+     */
+    entries(): Array<[string, T]>;
+    /**
+     * 获取或设置缓存（如果不存在）
+     * @param key 缓存键
+     * @param factory 工厂函数，用于生成缓存值
+     * @param ttl 过期时间（毫秒）
+     */
+    getOrSet(key: string, factory: () => Promise<T>, ttl?: number): Promise<T>;
+    getOrSet(key: string, factory: () => T, ttl?: number): T;
+    /**
+     * 获取缓存统计信息
+     */
+    getStats(): TtlCacheStats;
+    /**
+     * 重置统计信息
+     */
+    resetStats(): void;
+    /**
+     * 手动清理过期缓存
+     * @returns 清理的条目数量
+     */
+    cleanup(): number;
+    /**
+     * 获取指定键的剩余 TTL 时间
+     * @param key 缓存键
+     * @returns 剩余时间（毫秒），如果不存在或已过期返回 -1
+     */
+    getTtl(key: string): number;
+    /**
+     * 销毁缓存实例，清理所有资源
+     */
+    destroy(): void;
+    /**
+     * 启动定期清理过期缓存
+     */
+    private startCleanup;
+    /**
+     * 停止定期清理
+     */
+    private stopCleanup;
+    /**
+     * 驱逐最旧的缓存条目
+     */
+    private evictOldest;
+    /**
+     * 更新统计信息
+     */
+    private updateStats;
+    /**
+     * 更新命中率
+     */
+    private updateHitRate;
+}
+//# sourceMappingURL=ttl-cache.d.ts.map

package/output/ttl-cache/ttl-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ttl-cache.d.ts","sourceRoot":"","sources":["../../source/ttl-cache/ttl-cache.ts"],"names":[],"mappings":"AAYA;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,6BAA6B;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,wBAAwB;IACxB,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,qBAAqB;IACrB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,wBAAwB;IACxB,aAAa,CAAC,EAAE,OAAO,CAAA;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,aAAa;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,eAAe;IACf,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,WAAW;IACX,IAAI,EAAE,MAAM,CAAA;IACZ,YAAY;IACZ,MAAM,EAAE,MAAM,CAAA;IACd,WAAW;IACX,YAAY,EAAE,MAAM,CAAA;IACpB,UAAU;IACV,OAAO,EAAE,MAAM,CAAA;CAChB;AAED;;;;;;;;;;GAUG;AACH,qBAAa,QAAQ,CAAC,CAAC;IACrB,OAAO,CAAC,KAAK,CAA+B;IAC5C,OAAO,CAAC,YAAY,CAAC,CAAK;IAC1B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA2B;IACnD,OAAO,CAAC,KAAK,CAAe;gBAEhB,OAAO,GAAE,eAAoB;IAiCzC;;;;;OAKG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI;IA0B9C;;;;OAIG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAuB/B;;;OAGG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAiBzB;;;;OAIG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAQ5B;;OAEG;IACH,KAAK,IAAI,IAAI;IAMb;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;OAEG;IACH,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED;;OAEG;IACH,IAAI,IAAI,MAAM,EAAE;IAahB;;OAEG;IACH,MAAM,IAAI,CAAC,EAAE;IAab;;OAEG;IACH,OAAO,IAAI,KAAK,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IAa7B;;;;;OAKG;IACG,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IAChF,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,CAAC;IAoBxD;;OAEG;IACH,QAAQ,IAAI,aAAa;IAKzB;;OAEG;IACH,UAAU,IAAI,IAAI;IAWlB;;;OAGG;IACH,OAAO,IAAI,MAAM;IAmBjB;;;;OAIG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAc3B;;OAEG;IACH,OAAO,IAAI,IAAI;IAKf;;OAEG;IACH,OAAO,CAAC,YAAY;IAUpB;;OAEG;IACH,OAAO,CAAC,WAAW;IAOnB;;OAEG;IACH,OAAO,CAAC,WAAW;IAgBnB;;OAEG;IACH,OAAO,CAAC,WAAW;IAKnB;;OAEG;IACH,OAAO,CAAC,aAAa;CAItB"}

package/output/ttl-cache/ttl-cache.js

@@ -0,0 +1,313 @@
+/**
+ * TTL（Time To Live）缓存实现
+ * 支持过期时间、自动清理、统计信息等功能
+ *
+ * 特点：
+ * - 支持为每个条目设置独立的 TTL
+ * - 自动定期清理过期条目
+ * - 支持最大容量限制
+ * - 提供详细的统计信息
+ * - 优雅的资源清理机制
+ */
+export class TtlCache {
+    cache;
+    cleanupTimer;
+    options;
+    stats;
+    constructor(options = {}) {
+        this.options = {
+            defaultTtl: options.defaultTtl ?? 5 * 60 * 1000, // 默认5分钟
+            cleanupInterval: options.cleanupInterval ?? 60 * 1000, // 默认1分钟清理一次
+            maxSize: options.maxSize ?? Infinity,
+            enableCleanup: options.enableCleanup ?? true
+        };
+        if (this.options.defaultTtl <= 0) {
+            throw new Error('defaultTtl must be greater than 0');
+        }
+        if (this.options.cleanupInterval <= 0) {
+            throw new Error('cleanupInterval must be greater than 0');
+        }
+        if (this.options.maxSize <= 0) {
+            throw new Error('maxSize must be greater than 0');
+        }
+        this.cache = new Map();
+        this.stats = {
+            size: 0,
+            maxSize: this.options.maxSize === Infinity ? undefined : this.options.maxSize,
+            hits: 0,
+            misses: 0,
+            expiredCount: 0,
+            hitRate: 0
+        };
+        if (this.options.enableCleanup) {
+            this.startCleanup();
+        }
+    }
+    /**
+     * 设置缓存项
+     * @param key 缓存键
+     * @param value 缓存值
+     * @param ttl 过期时间（毫秒），默认使用构造函数中的值
+     */
+    set(key, value, ttl) {
+        const now = Date.now();
+        const actualTtl = ttl ?? this.options.defaultTtl;
+        const expireAt = now + actualTtl;
+        // 检查容量限制
+        if (!this.cache.has(key) && this.cache.size >= this.options.maxSize) {
+            // 尝试清理过期条目
+            this.cleanup();
+            // 如果清理后仍然超过容量，删除最旧的条目
+            if (this.cache.size >= this.options.maxSize) {
+                this.evictOldest();
+            }
+        }
+        const entry = {
+            value,
+            expireAt,
+            createdAt: now
+        };
+        this.cache.set(key, entry);
+        this.updateStats();
+    }
+    /**
+     * 获取缓存项
+     * @param key 缓存键
+     * @returns 缓存值或 undefined
+     */
+    get(key) {
+        const entry = this.cache.get(key);
+        if (!entry) {
+            this.stats.misses++;
+            this.updateHitRate();
+            return undefined;
+        }
+        const now = Date.now();
+        if (now > entry.expireAt) {
+            this.cache.delete(key);
+            this.stats.expiredCount++;
+            this.stats.misses++;
+            this.updateStats();
+            return undefined;
+        }
+        this.stats.hits++;
+        this.updateHitRate();
+        return entry.value;
+    }
+    /**
+     * 检查缓存项是否存在且未过期
+     * @param key 缓存键
+     */
+    has(key) {
+        const entry = this.cache.get(key);
+        if (!entry) {
+            return false;
+        }
+        const now = Date.now();
+        if (now > entry.expireAt) {
+            this.cache.delete(key);
+            this.stats.expiredCount++;
+            this.updateStats();
+            return false;
+        }
+        return true;
+    }
+    /**
+     * 删除缓存项
+     * @param key 缓存键
+     * @returns 是否成功删除
+     */
+    delete(key) {
+        const result = this.cache.delete(key);
+        if (result) {
+            this.updateStats();
+        }
+        return result;
+    }
+    /**
+     * 清空所有缓存
+     */
+    clear() {
+        this.cache.clear();
+        this.stats.expiredCount = 0;
+        this.updateStats();
+    }
+    /**
+     * 获取当前缓存大小
+     */
+    get size() {
+        return this.cache.size;
+    }
+    /**
+     * 获取缓存容量
+     */
+    get capacity() {
+        return this.options.maxSize;
+    }
+    /**
+     * 获取所有未过期的键
+     */
+    keys() {
+        const keys = [];
+        const now = Date.now();
+        for (const [key, entry] of this.cache.entries()) {
+            if (now <= entry.expireAt) {
+                keys.push(key);
+            }
+        }
+        return keys;
+    }
+    /**
+     * 获取所有未过期的值
+     */
+    values() {
+        const values = [];
+        const now = Date.now();
+        for (const entry of this.cache.values()) {
+            if (now <= entry.expireAt) {
+                values.push(entry.value);
+            }
+        }
+        return values;
+    }
+    /**
+     * 获取所有未过期的键值对
+     */
+    entries() {
+        const entries = [];
+        const now = Date.now();
+        for (const [key, entry] of this.cache.entries()) {
+            if (now <= entry.expireAt) {
+                entries.push([key, entry.value]);
+            }
+        }
+        return entries;
+    }
+    getOrSet(key, factory, ttl) {
+        const cached = this.get(key);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const result = factory();
+        if (result instanceof Promise) {
+            return result.then(value => {
+                this.set(key, value, ttl);
+                return value;
+            });
+        }
+        this.set(key, result, ttl);
+        return result;
+    }
+    /**
+     * 获取缓存统计信息
+     */
+    getStats() {
+        this.updateStats();
+        return { ...this.stats };
+    }
+    /**
+     * 重置统计信息
+     */
+    resetStats() {
+        this.stats = {
+            size: this.cache.size,
+            maxSize: this.options.maxSize === Infinity ? undefined : this.options.maxSize,
+            hits: 0,
+            misses: 0,
+            expiredCount: 0,
+            hitRate: 0
+        };
+    }
+    /**
+     * 手动清理过期缓存
+     * @returns 清理的条目数量
+     */
+    cleanup() {
+        const now = Date.now();
+        let expiredCount = 0;
+        for (const [key, entry] of this.cache.entries()) {
+            if (now > entry.expireAt) {
+                this.cache.delete(key);
+                expiredCount++;
+            }
+        }
+        if (expiredCount > 0) {
+            this.stats.expiredCount += expiredCount;
+            this.updateStats();
+        }
+        return expiredCount;
+    }
+    /**
+     * 获取指定键的剩余 TTL 时间
+     * @param key 缓存键
+     * @returns 剩余时间（毫秒），如果不存在或已过期返回 -1
+     */
+    getTtl(key) {
+        const entry = this.cache.get(key);
+        if (!entry) {
+            return -1;
+        }
+        const now = Date.now();
+        if (now > entry.expireAt) {
+            return -1;
+        }
+        return entry.expireAt - now;
+    }
+    /**
+     * 销毁缓存实例，清理所有资源
+     */
+    destroy() {
+        this.clear();
+        this.stopCleanup();
+    }
+    /**
+     * 启动定期清理过期缓存
+     */
+    startCleanup() {
+        if (this.cleanupTimer) {
+            return;
+        }
+        this.cleanupTimer = setInterval(() => {
+            this.cleanup();
+        }, this.options.cleanupInterval);
+    }
+    /**
+     * 停止定期清理
+     */
+    stopCleanup() {
+        if (this.cleanupTimer) {
+            clearInterval(this.cleanupTimer);
+            this.cleanupTimer = undefined;
+        }
+    }
+    /**
+     * 驱逐最旧的缓存条目
+     */
+    evictOldest() {
+        let oldestKey;
+        let oldestTime = Infinity;
+        for (const [key, entry] of this.cache.entries()) {
+            if (entry.createdAt < oldestTime) {
+                oldestTime = entry.createdAt;
+                oldestKey = key;
+            }
+        }
+        if (oldestKey) {
+            this.cache.delete(oldestKey);
+        }
+    }
+    /**
+     * 更新统计信息
+     */
+    updateStats() {
+        this.stats.size = this.cache.size;
+        this.updateHitRate();
+    }
+    /**
+     * 更新命中率
+     */
+    updateHitRate() {
+        const total = this.stats.hits + this.stats.misses;
+        this.stats.hitRate = total > 0 ? this.stats.hits / total : 0;
+    }
+}

package/output/ttl-cache/ttl-cache.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ttl-cache.test.d.ts.map

package/output/ttl-cache/ttl-cache.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ttl-cache.test.d.ts","sourceRoot":"","sources":["../../source/ttl-cache/ttl-cache.test.ts"],"names":[],"mappings":""}