@taicode/common-base 3.7.7 → 3.7.8

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.js';
+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": "3.7.7",
+  "version": "3.7.8",
   "author": "Alain",
   "license": "ISC",
   "description": "",