@taicode/common-base 1.7.1 → 1.7.2

package/output/batching-buffer/batching-buffer.d.ts

@@ -25,12 +25,6 @@ export interface BatchingBufferOptions<T> {
      * @default true
      */
     autoFlush?: boolean;
-    /**
-     * 错误处理回调函数
-     * @param error 发生的错误
-     * @param failedItems 处理失败的项目
-     */
-    onError?: (error: Error, failedItems: T[]) => void;
 }
 /**
  * 批处理缓冲区
@@ -48,11 +42,7 @@ export interface BatchingBufferOptions<T> {
  *     await saveToDatabase(items)
  *   },
  *   bufferSize: 10,
- *   flushInterval: 5000,
- *   onError: (error, failedItems) => {
- *     console.error('处理失败:', error, '失败项目:', failedItems)
- *     // 可以进行重试或其他错误处理逻辑
- *   }
+ *   flushInterval: 5000
  * })
  *
  * // 单个处理模式
@@ -66,9 +56,8 @@ export interface BatchingBufferOptions<T> {
  * })
  *
  * // 添加数据
- * buffer.add('data1')                    // 添加单个数据
- * buffer.add('data2', 'data3', 'data4')  // 添加多个数据
- * buffer.add(...array)                   // 展开数组添加
+ * buffer.add('data1')
+ * buffer.add('data2')
  *
  * // 手动刷新
  * await buffer.flush()
@@ -87,13 +76,17 @@ export declare class BatchingBuffer<T> {
     private readonly bufferSize;
     private readonly flushInterval;
     private readonly autoFlush;
-    private readonly onError?;
     constructor(options: BatchingBufferOptions<T>);
     /**
      * 添加数据到缓冲区
-     * @param items 要添加的数据项
+     * @param item 要添加的数据项
+     */
+    add(item: T): void;
+    /**
+     * 批量添加数据到缓冲区
+     * @param items 要添加的数据项数组
      */
-    add(...items: T[]): void;
+    addBatch(items: T[]): void;
     /**
      * 手动刷新缓冲区，处理所有待处理的数据
      * @returns Promise，在处理完成后 resolve

package/output/batching-buffer/batching-buffer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"batching-buffer.d.ts","sourceRoot":"","sources":["../../source/batching-buffer/batching-buffer.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,qBAAqB,CAAC,CAAC;IACtC;;OAEG;IACH,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IAErD;;OAEG;IACH,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IAEjD;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IAEnB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;IAEtB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;IAEnB;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC,EAAE,KAAK,IAAI,CAAA;CACnD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,qBAAa,cAAc,CAAC,CAAC;IAC3B,OAAO,CAAC,MAAM,CAAU;IACxB,OAAO,CAAC,KAAK,CAAmB;IAChC,OAAO,CAAC,WAAW,CAAiB;IACpC,OAAO,CAAC,aAAa,CAAqB;IAC1C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAsC;IACtE,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAmC;IAClE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAQ;IACnC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAQ;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAA0C;gBAEvD,OAAO,EAAE,qBAAqB,CAAC,CAAC,CAAC;IA2B7C;;;OAGG;IACH,GAAG,CAAC,GAAG,KAAK,EAAE,CAAC,EAAE,GAAG,IAAI;IAiCxB;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;OAEG;IACH,IAAI,OAAO,IAAI,OAAO,CAErB;IAED;;OAEG;IACH,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED;;OAEG;IACH,IAAI,kBAAkB,IAAI,MAAM,CAE/B;IAED;;;OAGG;IACG,OAAO,CAAC,cAAc,GAAE,OAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAgB5D;;OAEG;IACH,OAAO,CAAC,UAAU;IAQlB;;OAEG;IACH,OAAO,CAAC,UAAU;IAOlB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAgEzB;;OAEG;YACW,kBAAkB;CA2BjC"}
+{"version":3,"file":"batching-buffer.d.ts","sourceRoot":"","sources":["../../source/batching-buffer/batching-buffer.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,qBAAqB,CAAC,CAAC;IACtC;;OAEG;IACH,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IAErD;;OAEG;IACH,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IAEjD;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IAEnB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;IAEtB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,qBAAa,cAAc,CAAC,CAAC;IAC3B,OAAO,CAAC,MAAM,CAAU;IACxB,OAAO,CAAC,KAAK,CAAmB;IAChC,OAAO,CAAC,WAAW,CAAiB;IACpC,OAAO,CAAC,aAAa,CAAqB;IAC1C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAsC;IACtE,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAmC;IAClE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAQ;IACnC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAQ;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAEvB,OAAO,EAAE,qBAAqB,CAAC,CAAC,CAAC;IA0B7C;;;OAGG;IACH,GAAG,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI;IAmBlB;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,IAAI;IAyB1B;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;OAEG;IACH,IAAI,OAAO,IAAI,OAAO,CAErB;IAED;;OAEG;IACH,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED;;OAEG;IACH,IAAI,kBAAkB,IAAI,MAAM,CAE/B;IAED;;;OAGG;IACG,OAAO,CAAC,cAAc,GAAE,OAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAgB5D;;OAEG;IACH,OAAO,CAAC,UAAU;IAQlB;;OAEG;IACH,OAAO,CAAC,UAAU;IAOlB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAiDzB;;OAEG;YACW,kBAAkB;CA2BjC"}

package/output/batching-buffer/batching-buffer.js

@@ -14,11 +14,7 @@
  *     await saveToDatabase(items)
  *   },
  *   bufferSize: 10,
- *   flushInterval: 5000,
- *   onError: (error, failedItems) => {
- *     console.error('处理失败:', error, '失败项目:', failedItems)
- *     // 可以进行重试或其他错误处理逻辑
- *   }
+ *   flushInterval: 5000
  * })
  *
  * // 单个处理模式
@@ -32,9 +28,8 @@
  * })
  *
  * // 添加数据
- * buffer.add('data1')                    // 添加单个数据
- * buffer.add('data2', 'data3', 'data4')  // 添加多个数据
- * buffer.add(...array)                   // 展开数组添加
+ * buffer.add('data1')
+ * buffer.add('data2')
  *
  * // 手动刷新
  * await buffer.flush()
@@ -53,7 +48,6 @@ export class BatchingBuffer {
     bufferSize;
     flushInterval;
     autoFlush;
-    onError;
     constructor(options) {
         // 验证处理器配置
         if (!options.batchProcessor && !options.itemProcessor) {
@@ -67,7 +61,6 @@ export class BatchingBuffer {
         this.bufferSize = options.bufferSize ?? 100;
         this.flushInterval = options.flushInterval ?? 5000;
         this.autoFlush = options.autoFlush ?? true;
-        this.onError = options.onError;
         // 验证配置参数
         if (this.bufferSize <= 0) {
             throw new Error('bufferSize 必须大于 0');
@@ -78,33 +71,46 @@ export class BatchingBuffer {
     }
     /**
      * 添加数据到缓冲区
-     * @param items 要添加的数据项
+     * @param item 要添加的数据项
      */
-    add(...items) {
+    add(item) {
         if (this.isDestroyed) {
             throw new Error('BatchingBuffer 已被销毁，不能添加新数据');
         }
-        if (items.length === 0) {
+        this.buffer.push(item);
+        // 检查是否需要基于大小触发处理
+        if (this.buffer.length >= this.bufferSize) {
+            this.processBufferSync();
             return;
         }
+        // 启动或重置定时器
+        if (this.autoFlush) {
+            this.resetTimer();
+        }
+    }
+    /**
+     * 批量添加数据到缓冲区
+     * @param items 要添加的数据项数组
+     */
+    addBatch(items) {
+        if (this.isDestroyed) {
+            throw new Error('BatchingBuffer 已被销毁，不能添加新数据');
+        }
         let i = 0;
         while (i < items.length) {
-            // 计算本次可以添加的数量
-            const remainingBufferSpace = this.bufferSize - this.buffer.length;
-            const itemsToAdd = Math.min(remainingBufferSpace, items.length - i);
-            // 添加数据到缓冲区
-            for (let j = 0; j < itemsToAdd; j++) {
-                this.buffer.push(items[i + j]);
+            // 填充缓冲区直到达到大小限制
+            while (i < items.length && this.buffer.length < this.bufferSize) {
+                this.buffer.push(items[i]);
+                i++;
             }
-            i += itemsToAdd;
             // 如果缓冲区满了，处理它
             if (this.buffer.length >= this.bufferSize) {
                 this.processBufferSync();
             }
         }
-        // 为剩余数据启动定时器（如果还有数据且启用自动刷新）
-        if (this.buffer.length > 0 && this.autoFlush) {
-            this.resetTimer();
+        // 处理剩余的项目（如果有的话）
+        if (this.buffer.length > 0) {
+            this.processBufferSync();
         }
     }
     /**
@@ -188,44 +194,29 @@ export class BatchingBuffer {
                 const result = this.batchProcessor(itemsToProcess);
                 // 如果返回 Promise，处理异步
                 if (result && typeof result.then === 'function') {
-                    result.catch((error) => {
-                        // 处理失败时，将数据重新放回缓冲区开头（如果没有被销毁）
-                        if (!this.isDestroyed) {
-                            this.buffer.unshift(...itemsToProcess);
-                        }
-                        // 调用错误处理回调
-                        if (this.onError) {
-                            this.onError(error, itemsToProcess);
-                        }
+                    result.catch(() => {
+                        // 处理失败时，将数据重新放回缓冲区开头
+                        this.buffer.unshift(...itemsToProcess);
                     });
                 }
             }
             else if (this.itemProcessor) {
                 // 单个处理模式 - 同步处理每个项目
-                const failedItems = [];
                 for (let i = 0; i < itemsToProcess.length; i++) {
                     const item = itemsToProcess[i];
                     try {
                         const result = this.itemProcessor(item);
                         // 如果返回 Promise，处理异步
                         if (result && typeof result.then === 'function') {
-                            result.catch((error) => {
-                                // 处理失败时，将数据重新放回缓冲区开头（如果没有被销毁）
-                                if (!this.isDestroyed) {
-                                    this.buffer.unshift(item);
-                                }
-                                // 调用错误处理回调
-                                if (this.onError) {
-                                    this.onError(error, [item]);
-                                }
+                            result.catch(() => {
+                                // 处理失败时，将数据重新放回缓冲区开头
+                                this.buffer.unshift(item);
                             });
                         }
                     }
                     catch (error) {
-                        // 同步错误处理 - 把当前项目和未处理的项目放回缓冲区
-                        failedItems.push(item);
-                        failedItems.push(...itemsToProcess.slice(i + 1));
-                        this.buffer.unshift(...failedItems);
+                        // 同步错误处理 - 只把未处理的项目放回缓冲区
+                        this.buffer.unshift(...itemsToProcess.slice(i));
                         throw error;
                     }
                 }

package/output/batching-buffer/batching-buffer.test.js

@@ -122,32 +122,12 @@ describe('BatchingBuffer', () => {
             expect(buffer.size).toBe(0);
         });
         it('应该支持批量添加数据', () => {
-            buffer.add('item1', 'item2', 'item3', 'item4', 'item5');
-            expect(batchProcessor).toHaveBeenCalledTimes(1);
+            buffer.addBatch(['item1', 'item2', 'item3', 'item4', 'item5']);
+            expect(batchProcessor).toHaveBeenCalledTimes(2);
             expect(batchProcessor).toHaveBeenNthCalledWith(1, ['item1', 'item2', 'item3']);
-            // 剩余的项目应该在缓冲区中
-            expect(buffer.size).toBe(2);
-        });
-        it('应该支持添加空参数', () => {
-            buffer.add();
-            expect(batchProcessor).not.toHaveBeenCalled();
-            expect(buffer.size).toBe(0);
-        });
-        it('应该支持混合添加单个和多个数据', () => {
-            buffer.add('item1'); // 单个
-            buffer.add('item2', 'item3'); // 多个
-            expect(batchProcessor).toHaveBeenCalledTimes(1);
-            expect(batchProcessor).toHaveBeenCalledWith(['item1', 'item2', 'item3']);
+            expect(batchProcessor).toHaveBeenNthCalledWith(2, ['item4', 'item5']);
             expect(buffer.size).toBe(0);
         });
-        it('应该支持使用数组展开语法', () => {
-            const items = ['item1', 'item2', 'item3', 'item4', 'item5'];
-            buffer.add(...items);
-            expect(batchProcessor).toHaveBeenCalledTimes(1);
-            expect(batchProcessor).toHaveBeenNthCalledWith(1, ['item1', 'item2', 'item3']);
-            // 剩余的项目应该在缓冲区中
-            expect(buffer.size).toBe(2);
-        });
         it('应该正确处理处理器异常', () => {
             const error = new Error('处理失败');
             batchProcessor.mockImplementationOnce(() => {
@@ -236,11 +216,10 @@ describe('BatchingBuffer', () => {
         it('应该正确报告距离上次刷新的时间', async () => {
             const startTime = Date.now();
             buffer.add(1);
-            // 使用假定时器来精确控制时间
             vi.advanceTimersByTime(500);
-            expect(buffer.timeSinceLastFlush).toBe(500);
+            expect(buffer.timeSinceLastFlush).toBeGreaterThanOrEqual(500);
             await buffer.flush();
-            expect(buffer.timeSinceLastFlush).toBe(0);
+            expect(buffer.timeSinceLastFlush).toBeLessThan(100);
         });
     });
     describe('销毁功能', () => {
@@ -275,7 +254,7 @@ describe('BatchingBuffer', () => {
                 buffer.add('item1');
             }).toThrow('BatchingBuffer 已被销毁，不能添加新数据');
             expect(() => {
-                buffer.add('item1', 'item2');
+                buffer.addBatch(['item1', 'item2']);
             }).toThrow('BatchingBuffer 已被销毁，不能添加新数据');
         });
         it('应该支持重复销毁', async () => {
@@ -314,45 +293,6 @@ describe('BatchingBuffer', () => {
             expect(batchProcessor).toHaveBeenCalledWith(['item1', 'item2']);
             await buffer.destroy();
         });
-        it('应该正确处理定时器重置', async () => {
-            const buffer = new BatchingBuffer({
-                batchProcessor: batchProcessor,
-                bufferSize: 5,
-                flushInterval: 1000,
-                autoFlush: true
-            });
-            // 添加第一个项目，启动定时器
-            buffer.add('item1');
-            vi.advanceTimersByTime(500);
-            // 添加第二个项目，应该重置定时器
-            buffer.add('item2');
-            vi.advanceTimersByTime(500);
-            // 此时应该还没触发（总共过了1000ms，但最后一次重置后只过了500ms）
-            expect(batchProcessor).not.toHaveBeenCalled();
-            // 再等500ms，现在应该触发了
-            vi.advanceTimersByTime(500);
-            await vi.runAllTimersAsync();
-            expect(batchProcessor).toHaveBeenCalledTimes(1);
-            expect(batchProcessor).toHaveBeenCalledWith(['item1', 'item2']);
-            await buffer.destroy();
-        });
-        it('应该在销毁时清除定时器避免内存泄漏', async () => {
-            const buffer = new BatchingBuffer({
-                batchProcessor: batchProcessor,
-                bufferSize: 5,
-                flushInterval: 1000,
-                autoFlush: true
-            });
-            buffer.add('item1');
-            // 立即销毁，应该处理剩余数据但不会因为定时器再次触发
-            await buffer.destroy();
-            expect(batchProcessor).toHaveBeenCalledTimes(1);
-            // 等待原本的定时器时间，不应该再次触发
-            vi.advanceTimersByTime(1000);
-            await vi.runAllTimersAsync();
-            // 仍然只被调用一次
-            expect(batchProcessor).toHaveBeenCalledTimes(1);
-        });
     });
     describe('复杂数据类型', () => {
         let buffer;
@@ -381,11 +321,11 @@ describe('BatchingBuffer', () => {
         let asyncItemProcessor;
         beforeEach(() => {
             asyncBatchProcessor = vi.fn().mockImplementation(async (items) => {
-                // 使用 fake timer 而不是真实的 setTimeout
+                await new Promise(resolve => setTimeout(resolve, 100));
                 return `处理了 ${items.length} 个项目`;
             });
             asyncItemProcessor = vi.fn().mockImplementation(async (item) => {
-                // 使用 fake timer 而不是真实的 setTimeout
+                await new Promise(resolve => setTimeout(resolve, 50));
                 return `处理了项目: ${item}`;
             });
         });
@@ -415,97 +355,4 @@ describe('BatchingBuffer', () => {
             buffer.destroy();
         });
     });
-    describe('错误处理回调', () => {
-        it('应该支持配置错误处理回调', () => {
-            const onError = vi.fn();
-            const buffer = new BatchingBuffer({
-                batchProcessor: vi.fn(),
-                bufferSize: 10,
-                flushInterval: 1000,
-                onError
-            });
-            expect(buffer).toBeDefined();
-            buffer.destroy();
-        });
-        it('错误处理回调应该可以正确配置', () => {
-            const onError = vi.fn();
-            const buffer = new BatchingBuffer({
-                batchProcessor: vi.fn(),
-                bufferSize: 10,
-                flushInterval: 1000,
-                onError
-            });
-            // 验证缓冲区正常工作
-            buffer.add('item1');
-            expect(buffer.size).toBe(1);
-            buffer.destroy();
-        });
-    });
-    describe('边界条件测试', () => {
-        it('应该正确处理极小的 bufferSize', () => {
-            const buffer = new BatchingBuffer({
-                batchProcessor: batchProcessor,
-                bufferSize: 1,
-                flushInterval: 1000
-            });
-            buffer.add('item1');
-            expect(batchProcessor).toHaveBeenCalledTimes(1);
-            expect(batchProcessor).toHaveBeenCalledWith(['item1']);
-            buffer.destroy();
-        });
-        it('应该正确处理极小的 flushInterval', async () => {
-            const buffer = new BatchingBuffer({
-                batchProcessor: batchProcessor,
-                bufferSize: 5,
-                flushInterval: 1 // 1ms
-            });
-            buffer.add('item1');
-            vi.advanceTimersByTime(1);
-            await vi.runAllTimersAsync();
-            expect(batchProcessor).toHaveBeenCalledTimes(1);
-            expect(batchProcessor).toHaveBeenCalledWith(['item1']);
-            await buffer.destroy();
-        });
-        it('应该正确处理同时达到大小和时间限制', async () => {
-            const buffer = new BatchingBuffer({
-                batchProcessor: batchProcessor,
-                bufferSize: 2,
-                flushInterval: 100
-            });
-            buffer.add('item1');
-            // 在时间限制之前添加第二个项目，应该立即触发
-            buffer.add('item2');
-            expect(batchProcessor).toHaveBeenCalledTimes(1);
-            expect(batchProcessor).toHaveBeenCalledWith(['item1', 'item2']);
-            await buffer.destroy();
-        });
-        it('应该正确处理在处理过程中继续添加数据', () => {
-            const processedBatches = [];
-            let processingCount = 0;
-            const batchProcessorWithCallback = vi.fn().mockImplementation((items) => {
-                processingCount++;
-                processedBatches.push([...items]);
-                // 在第一次处理过程中添加新数据
-                if (processingCount === 1) {
-                    buffer.add('item4');
-                }
-            });
-            const buffer = new BatchingBuffer({
-                batchProcessor: batchProcessorWithCallback,
-                bufferSize: 2,
-                flushInterval: 1000
-            });
-            buffer.add('item1', 'item2', 'item3');
-            // 验证处理次数
-            expect(batchProcessorWithCallback).toHaveBeenCalledTimes(2);
-            // 验证第一次处理了前两个项目
-            expect(processedBatches[0]).toEqual(['item1', 'item2']);
-            // 第二次处理的顺序可能是 ['item4', 'item3'] 或 ['item3', 'item4']
-            // 这取决于具体实现，我们验证包含了正确的项目
-            expect(processedBatches[1]).toHaveLength(2);
-            expect(processedBatches[1]).toContain('item3');
-            expect(processedBatches[1]).toContain('item4');
-            buffer.destroy();
-        });
-    });
 });

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';

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"}

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';
 // === 数据管理 ===

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":""}

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

@@ -0,0 +1,222 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { TtlCache } from './ttl-cache';
+describe('TtlCache', () => {
+    let cache;
+    beforeEach(() => {
+        vi.useFakeTimers();
+        cache = new TtlCache({ defaultTtl: 1000, enableCleanup: false });
+    });
+    afterEach(() => {
+        cache.destroy();
+        vi.useRealTimers();
+    });
+    describe('基础功能', () => {
+        it('应该能够设置和获取缓存项', () => {
+            cache.set('key1', 'value1');
+            expect(cache.get('key1')).toBe('value1');
+        });
+        it('应该能够检查缓存项是否存在', () => {
+            cache.set('key1', 'value1');
+            expect(cache.has('key1')).toBe(true);
+            expect(cache.has('nonexistent')).toBe(false);
+        });
+        it('应该能够删除缓存项', () => {
+            cache.set('key1', 'value1');
+            expect(cache.delete('key1')).toBe(true);
+            expect(cache.get('key1')).toBeUndefined();
+            expect(cache.delete('nonexistent')).toBe(false);
+        });
+        it('应该能够清空所有缓存', () => {
+            cache.set('key1', 'value1');
+            cache.set('key2', 'value2');
+            cache.clear();
+            expect(cache.size).toBe(0);
+            expect(cache.get('key1')).toBeUndefined();
+            expect(cache.get('key2')).toBeUndefined();
+        });
+        it('应该能够获取缓存大小', () => {
+            expect(cache.size).toBe(0);
+            cache.set('key1', 'value1');
+            expect(cache.size).toBe(1);
+            cache.set('key2', 'value2');
+            expect(cache.size).toBe(2);
+        });
+    });
+    describe('TTL 功能', () => {
+        it('应该在 TTL 过期后删除缓存项', () => {
+            cache.set('key1', 'value1', 500);
+            expect(cache.get('key1')).toBe('value1');
+            // 前进 600ms，超过 TTL
+            vi.advanceTimersByTime(600);
+            expect(cache.get('key1')).toBeUndefined();
+        });
+        it('应该使用默认 TTL', () => {
+            cache.set('key1', 'value1');
+            expect(cache.get('key1')).toBe('value1');
+            // 前进 1100ms，超过默认 TTL (1000ms)
+            vi.advanceTimersByTime(1100);
+            expect(cache.get('key1')).toBeUndefined();
+        });
+        it('应该能够获取剩余 TTL 时间', () => {
+            cache.set('key1', 'value1', 1000);
+            expect(cache.getTtl('key1')).toBe(1000);
+            vi.advanceTimersByTime(500);
+            expect(cache.getTtl('key1')).toBe(500);
+            vi.advanceTimersByTime(600);
+            expect(cache.getTtl('key1')).toBe(-1); // 已过期
+        });
+        it('不存在的键应该返回 -1 的 TTL', () => {
+            expect(cache.getTtl('nonexistent')).toBe(-1);
+        });
+    });
+    describe('容量限制', () => {
+        beforeEach(() => {
+            cache.destroy();
+            cache = new TtlCache({ maxSize: 2, enableCleanup: false });
+        });
+        it('应该遵守最大容量限制', () => {
+            cache.set('key1', 'value1');
+            cache.set('key2', 'value2');
+            cache.set('key3', 'value3'); // 应该驱逐最旧的条目
+            expect(cache.size).toBe(2);
+            expect(cache.get('key1')).toBeUndefined(); // 最旧的条目被驱逐
+            expect(cache.get('key2')).toBe('value2');
+            expect(cache.get('key3')).toBe('value3');
+        });
+        it('应该能够获取容量信息', () => {
+            expect(cache.capacity).toBe(2);
+        });
+    });
+    describe('getOrSet 功能', () => {
+        it('应该返回已存在的缓存值', async () => {
+            cache.set('key1', 'existing');
+            const factory = vi.fn(() => Promise.resolve('new'));
+            const result = await cache.getOrSet('key1', factory);
+            expect(result).toBe('existing');
+            expect(factory).not.toHaveBeenCalled();
+        });
+        it('应该在缓存不存在时调用工厂函数并缓存结果', async () => {
+            const factory = vi.fn(() => Promise.resolve('new'));
+            const result = await cache.getOrSet('key1', factory);
+            expect(result).toBe('new');
+            expect(factory).toHaveBeenCalledOnce();
+            expect(cache.get('key1')).toBe('new');
+        });
+        it('应该支持同步工厂函数', () => {
+            const factory = vi.fn(() => 'sync-value');
+            const result = cache.getOrSet('key1', factory);
+            expect(result).toBe('sync-value');
+            expect(factory).toHaveBeenCalledOnce();
+            expect(cache.get('key1')).toBe('sync-value');
+        });
+    });
+    describe('集合操作', () => {
+        beforeEach(() => {
+            cache.set('key1', 'value1');
+            cache.set('key2', 'value2');
+            cache.set('expired', 'expired-value', 100);
+            vi.advanceTimersByTime(200); // 使 'expired' 过期
+        });
+        it('应该返回所有未过期的键', () => {
+            const keys = cache.keys();
+            expect(keys).toContain('key1');
+            expect(keys).toContain('key2');
+            expect(keys).not.toContain('expired');
+        });
+        it('应该返回所有未过期的值', () => {
+            const values = cache.values();
+            expect(values).toContain('value1');
+            expect(values).toContain('value2');
+            expect(values).not.toContain('expired-value');
+        });
+        it('应该返回所有未过期的键值对', () => {
+            const entries = cache.entries();
+            expect(entries).toContainEqual(['key1', 'value1']);
+            expect(entries).toContainEqual(['key2', 'value2']);
+            expect(entries).not.toContainEqual(['expired', 'expired-value']);
+        });
+    });
+    describe('统计功能', () => {
+        it('应该跟踪命中和未命中', () => {
+            cache.set('key1', 'value1');
+            // 命中
+            cache.get('key1');
+            cache.get('key1');
+            // 未命中
+            cache.get('nonexistent');
+            const stats = cache.getStats();
+            expect(stats.hits).toBe(2);
+            expect(stats.misses).toBe(1);
+            expect(stats.hitRate).toBeCloseTo(2 / 3);
+        });
+        it('应该跟踪过期次数', () => {
+            cache.set('key1', 'value1', 100);
+            vi.advanceTimersByTime(200);
+            cache.get('key1'); // 触发过期
+            const stats = cache.getStats();
+            expect(stats.expiredCount).toBe(1);
+        });
+        it('应该能够重置统计信息', () => {
+            cache.get('nonexistent'); // 创建一些统计数据
+            cache.resetStats();
+            const stats = cache.getStats();
+            expect(stats.hits).toBe(0);
+            expect(stats.misses).toBe(0);
+            expect(stats.expiredCount).toBe(0);
+            expect(stats.hitRate).toBe(0);
+        });
+    });
+    describe('清理功能', () => {
+        it('应该手动清理过期条目', () => {
+            cache.set('key1', 'value1', 100);
+            cache.set('key2', 'value2', 1000);
+            vi.advanceTimersByTime(200);
+            const cleaned = cache.cleanup();
+            expect(cleaned).toBe(1);
+            expect(cache.size).toBe(1);
+            expect(cache.get('key1')).toBeUndefined();
+            expect(cache.get('key2')).toBe('value2');
+        });
+        it('应该启用自动清理', () => {
+            cache.destroy();
+            cache = new TtlCache({
+                defaultTtl: 1000,
+                cleanupInterval: 500,
+                enableCleanup: true
+            });
+            cache.set('key1', 'value1', 100);
+            vi.advanceTimersByTime(600); // 触发清理
+            expect(cache.size).toBe(0);
+        });
+    });
+    describe('配置验证', () => {
+        it('应该拒绝无效的默认 TTL', () => {
+            expect(() => new TtlCache({ defaultTtl: 0 })).toThrow('defaultTtl must be greater than 0');
+            expect(() => new TtlCache({ defaultTtl: -1 })).toThrow('defaultTtl must be greater than 0');
+        });
+        it('应该拒绝无效的清理间隔', () => {
+            expect(() => new TtlCache({ cleanupInterval: 0 })).toThrow('cleanupInterval must be greater than 0');
+            expect(() => new TtlCache({ cleanupInterval: -1 })).toThrow('cleanupInterval must be greater than 0');
+        });
+        it('应该拒绝无效的最大容量', () => {
+            expect(() => new TtlCache({ maxSize: 0 })).toThrow('maxSize must be greater than 0');
+            expect(() => new TtlCache({ maxSize: -1 })).toThrow('maxSize must be greater than 0');
+        });
+    });
+    describe('边界情况', () => {
+        it('应该处理空字符串键', () => {
+            cache.set('', 'empty-key-value');
+            expect(cache.get('')).toBe('empty-key-value');
+        });
+        it('应该处理 undefined 值', () => {
+            cache.set('key1', undefined);
+            expect(cache.get('key1')).toBeUndefined();
+            expect(cache.has('key1')).toBe(true); // 值虽然是 undefined，但键存在
+        });
+        it('应该处理非常短的 TTL', () => {
+            cache.set('key1', 'value1', 1);
+            vi.advanceTimersByTime(2);
+            expect(cache.get('key1')).toBeUndefined();
+        });
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taicode/common-base",
-  "version": "1.7.1",
+  "version": "1.7.2",
   "author": "Alain",
   "license": "ISC",
   "description": "",