@taicode/common-base 3.7.7 → 3.7.8

package/output/throttle/throttle.test.js

@@ -0,0 +1,177 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { throttle, throttleFn } from './throttle.js';
+describe('throttle', () => {
+    beforeEach(() => {
+        vi.useFakeTimers();
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+        vi.useRealTimers();
+    });
+    describe('throttleFn', () => {
+        it('应该立即执行第一次调用', () => {
+            const mockFn = vi.fn().mockReturnValue('result');
+            const throttledFn = throttleFn(mockFn, 100);
+            const result = throttledFn('arg1', 'arg2');
+            expect(mockFn).toHaveBeenCalledOnce();
+            expect(mockFn).toHaveBeenCalledWith('arg1', 'arg2');
+            expect(result).toBe('result');
+        });
+        it('应该在间隔时间内忽略后续调用', () => {
+            const mockFn = vi.fn().mockReturnValue('result');
+            const throttledFn = throttleFn(mockFn, 100);
+            // 第一次调用应该立即执行
+            throttledFn('first');
+            expect(mockFn).toHaveBeenCalledOnce();
+            // 在间隔时间内的调用应该被忽略
+            throttledFn('second');
+            throttledFn('third');
+            expect(mockFn).toHaveBeenCalledOnce();
+        });
+        it('应该在间隔时间结束后允许新的调用', () => {
+            const mockFn = vi.fn().mockReturnValue('result');
+            const throttledFn = throttleFn(mockFn, 100);
+            // 第一次调用
+            throttledFn('first');
+            expect(mockFn).toHaveBeenCalledOnce();
+            // 推进时间超过间隔
+            vi.advanceTimersByTime(150);
+            // 现在应该允许新的调用
+            throttledFn('second');
+            expect(mockFn).toHaveBeenCalledTimes(2);
+            expect(mockFn).toHaveBeenLastCalledWith('second');
+        });
+        it('应该支持 leading: false 选项', () => {
+            const mockFn = vi.fn().mockReturnValue('result');
+            const throttledFn = throttleFn(mockFn, 100, { leading: false });
+            // 第一次调用不应该立即执行
+            throttledFn('first');
+            expect(mockFn).not.toHaveBeenCalled();
+        });
+        it('应该支持 trailing: true 选项', () => {
+            const mockFn = vi.fn().mockReturnValue('result');
+            const throttledFn = throttleFn(mockFn, 100, { trailing: true });
+            // 第一次调用
+            throttledFn('first');
+            expect(mockFn).toHaveBeenCalledOnce();
+            // 在间隔时间内的调用
+            throttledFn('second');
+            throttledFn('third');
+            // 推进时间，应该执行 trailing 调用
+            vi.advanceTimersByTime(100);
+            expect(mockFn).toHaveBeenCalledTimes(2);
+            expect(mockFn).toHaveBeenLastCalledWith('third');
+        });
+        it('应该支持 trailing: false 选项', () => {
+            const mockFn = vi.fn().mockReturnValue('result');
+            const throttledFn = throttleFn(mockFn, 100, { trailing: false });
+            // 第一次调用
+            throttledFn('first');
+            expect(mockFn).toHaveBeenCalledOnce();
+            // 在间隔时间内的调用
+            throttledFn('second');
+            throttledFn('third');
+            // 推进时间，不应该执行 trailing 调用
+            vi.advanceTimersByTime(100);
+            expect(mockFn).toHaveBeenCalledOnce();
+        });
+        it('应该保持 this 上下文', () => {
+            class TestClass {
+                value = 'test-value';
+                getValue() {
+                    return this.value;
+                }
+            }
+            const instance = new TestClass();
+            const throttledMethod = throttleFn(instance.getValue, 100);
+            const result = throttledMethod.call(instance);
+            expect(result).toBe('test-value');
+        });
+        it('应该返回最后一次执行的结果', () => {
+            const mockFn = vi.fn()
+                .mockReturnValueOnce('first')
+                .mockReturnValueOnce('second');
+            const throttledFn = throttleFn(mockFn, 100);
+            const result1 = throttledFn();
+            expect(result1).toBe('first');
+            // 在间隔时间内，应该返回缓存的结果
+            const result2 = throttledFn();
+            expect(result2).toBe('first');
+            // 推进时间后的新调用
+            vi.advanceTimersByTime(150);
+            const result3 = throttledFn();
+            expect(result3).toBe('second');
+        });
+    });
+    describe('throttle decorator', () => {
+        it('应该装饰类方法', () => {
+            class TestClass {
+                callCount = 0;
+                @throttle(100)
+                increment() {
+                    this.callCount++;
+                    return this.callCount;
+                }
+            }
+            const instance = new TestClass();
+            // 第一次调用应该立即执行
+            const result1 = instance.increment();
+            expect(result1).toBe(1);
+            expect(instance.callCount).toBe(1);
+            // 快速连续调用应该被节流
+            instance.increment();
+            instance.increment();
+            expect(instance.callCount).toBe(1);
+        });
+        it('应该为每个实例独立工作', () => {
+            class TestClass {
+                callCount = 0;
+                @throttle(100)
+                increment() {
+                    this.callCount++;
+                    return this.callCount;
+                }
+            }
+            const instance1 = new TestClass();
+            const instance2 = new TestClass();
+            instance1.increment();
+            instance2.increment();
+            expect(instance1.callCount).toBe(1);
+            expect(instance2.callCount).toBe(1);
+        });
+        it('应该支持带选项的装饰器', () => {
+            class TestClass {
+                callCount = 0;
+                @throttle(100, { leading: false, trailing: true })
+                increment() {
+                    this.callCount++;
+                    return this.callCount;
+                }
+            }
+            const instance = new TestClass();
+            // leading: false，第一次调用不应该立即执行
+            instance.increment();
+            expect(instance.callCount).toBe(0);
+            // trailing: true，应该在延迟后执行
+            vi.advanceTimersByTime(100);
+            expect(instance.callCount).toBe(1);
+        });
+        it('应该处理带参数的方法', () => {
+            class TestClass {
+                lastArgs = [];
+                @throttle(100)
+                saveArgs(...args) {
+                    this.lastArgs = args;
+                    return args.length;
+                }
+            }
+            const instance = new TestClass();
+            const result = instance.saveArgs(1, 2, 3);
+            expect(result).toBe(3);
+            expect(instance.lastArgs).toEqual([1, 2, 3]);
+            // 在间隔时间内的调用应该被忽略
+            instance.saveArgs(4, 5, 6, 7);
+            expect(instance.lastArgs).toEqual([1, 2, 3]); // 应该保持原值
+        });
+    });
+});

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

@@ -0,0 +1,2 @@
+export { TtlCache, type TtlCacheOptions, type TtlCacheStats } from './ttl-cache.js';
+//# 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,gBAAgB,CAAA"}

package/output/ttl-cache/index.js

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

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