@taicode/common-base 1.7.0 → 1.7.2

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.0",
+  "version": "1.7.2",
   "author": "Alain",
   "license": "ISC",
   "description": "",