id-scanner-lib 1.5.0 → 1.6.2

package/src/utils/retry.ts

@@ -0,0 +1,282 @@
+/**
+ * @file 重试工具
+ * @description 提供重试逻辑功能
+ * @module utils/retry
+ */
+
+/**
+ * 重试选项
+ */
+export interface RetryOptions {
+  /** 最大重试次数 */
+  maxAttempts?: number;
+  /** 初始等待时间(ms) */
+  initialDelay?: number;
+  /** 最大等待时间(ms) */
+  maxDelay?: number;
+  /** 指数退避因子 */
+  backoffFactor?: number;
+  /** 是否随机抖动 */
+  jitter?: boolean;
+  /** 重试条件 */
+  shouldRetry?: (error: unknown) => boolean;
+}
+
+/**
+ * 默认重试选项
+ */
+const DEFAULT_OPTIONS: Required<RetryOptions> = {
+  maxAttempts: 3,
+  initialDelay: 1000,
+  maxDelay: 10000,
+  backoffFactor: 2,
+  jitter: true,
+  shouldRetry: () => true
+};
+
+/**
+ * 带重试的异步函数包装器
+ * @param fn 要执行的异步函数
+ * @param options 重试选项
+ * @returns 函数结果
+ */
+export async function withRetry<T>(
+  fn: () => Promise<T>,
+  options: RetryOptions = {}
+): Promise<T> {
+  const opts = { ...DEFAULT_OPTIONS, ...options };
+  let lastError: unknown;
+  let delay = opts.initialDelay;
+
+  for (let attempt = 1; attempt <= opts.maxAttempts; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error;
+
+      // 检查是否应该重试
+      if (!opts.shouldRetry(error)) {
+        throw error;
+      }
+
+      // 如果不是最后一次尝试，等待后重试
+      if (attempt < opts.maxAttempts) {
+        // 添加随机抖动
+        const jitterAmount = opts.jitter ? Math.random() * delay : 0;
+        const waitTime = Math.min(delay + jitterAmount, opts.maxDelay);
+
+        await sleep(waitTime);
+
+        // 指数退避
+        delay = Math.min(delay * opts.backoffFactor, opts.maxDelay);
+      }
+    }
+  }
+
+  throw lastError;
+}
+
+/**
+ * 睡眠函数
+ * @param ms 毫秒数
+ */
+function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/**
+ * 创建指数退避重试函数
+ * @param options 重试选项
+ * @returns 包装后的重试函数
+ */
+export function createRetryable<T extends (...args: any[]) => Promise<any>>(
+  fn: T,
+  options: RetryOptions = {}
+): T {
+  const wrapped = (...args: Parameters<T>): Promise<ReturnType<T>> => {
+    return withRetry(() => fn(...args), options);
+  };
+  Object.defineProperty(wrapped, 'name', { value: fn.name, configurable: true });
+  return wrapped as T;
+}
+
+/**
+ * 异步缓存
+ * @description 用于缓存异步函数的结果
+ */
+export class AsyncCache<T> {
+  private cache: Map<string, { value: T; expiry: number }> = new Map();
+  private defaultTTL: number;
+
+  /**
+   * @param defaultTTL 默认过期时间(毫秒)
+   */
+  constructor(defaultTTL: number = 5 * 60 * 1000) {
+    this.defaultTTL = defaultTTL;
+  }
+
+  /**
+   * 获取缓存值
+   * @param key 缓存键
+   * @returns 缓存值，如果不存在或已过期则返回undefined
+   */
+  get(key: string): T | undefined {
+    const entry = this.cache.get(key);
+    if (!entry) return undefined;
+
+    if (Date.now() > entry.expiry) {
+      this.cache.delete(key);
+      return undefined;
+    }
+
+    return entry.value;
+  }
+
+  /**
+   * 设置缓存值
+   * @param key 缓存键
+   * @param value 缓存值
+   * @param ttl 过期时间(毫秒)
+   */
+  set(key: string, value: T, ttl?: number): void {
+    this.cache.set(key, {
+      value,
+      expiry: Date.now() + (ttl || this.defaultTTL)
+    });
+  }
+
+  /**
+   * 删除缓存值
+   * @param key 缓存键
+   */
+  delete(key: string): void {
+    this.cache.delete(key);
+  }
+
+  /**
+   * 清空缓存
+   */
+  clear(): void {
+    this.cache.clear();
+  }
+
+  /**
+   * 获取缓存大小
+   */
+  get size(): number {
+    // 清理过期项 (避免在迭代中删除)
+    const now = Date.now();
+    const expiredKeys: string[] = [];
+    for (const [key, entry] of this.cache.entries()) {
+      if (now > entry.expiry) {
+        expiredKeys.push(key);
+      }
+    }
+    expiredKeys.forEach(key => this.cache.delete(key));
+    return this.cache.size;
+  }
+
+  /**
+   * 异步获取或设置缓存
+   * @param key 缓存键
+   * @param fn 获取值的函数
+   * @param ttl 过期时间
+   * @returns 缓存值
+   */
+  async getOrSet(
+    key: string,
+    fn: () => Promise<T>,
+    ttl?: number
+  ): Promise<T> {
+    const cached = this.get(key);
+    if (cached !== undefined) {
+      return cached;
+    }
+
+    const value = await fn();
+    this.set(key, value, ttl);
+    return value;
+  }
+}
+
+/**
+ * 简单信号量
+ * @description 用于控制并发数量
+ */
+export class Semaphore {
+  private permits: number;
+  private queue: Array<() => void> = [];
+
+  /**
+   * @param permits 最大许可数
+   */
+  constructor(permits: number) {
+    this.permits = permits;
+  }
+
+  /**
+   * 获取许可
+   * @returns Promise
+   */
+  async acquire(): Promise<void> {
+    if (this.permits > 0) {
+      this.permits--;
+      return Promise.resolve();
+    }
+
+    return new Promise<void>(resolve => {
+      this.queue.push(resolve);
+    });
+  }
+
+  /**
+   * 释放许可
+   */
+  release(): void {
+    this.permits++;
+    const next = this.queue.shift();
+    if (next) {
+      this.permits--;
+      next();
+    }
+  }
+
+  /**
+   * 尝试获取许可
+   * @returns 是否获取成功
+   */
+  tryAcquire(): boolean {
+    if (this.permits > 0) {
+      this.permits--;
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * 获取当前可用许可数
+   */
+  get availablePermits(): number {
+    return this.permits;
+  }
+}
+
+/**
+ * 带信号量的异步函数包装器
+ * @param fn 异步函数
+ * @param semaphore 信号量
+ * @returns 包装后的函数
+ */
+export function withSemaphore<T extends (...args: any[]) => Promise<any>>(
+  fn: T,
+  semaphore: Semaphore
+): T {
+  return (async (...args: Parameters<T>): Promise<ReturnType<T>> => {
+    await semaphore.acquire();
+    try {
+      return await fn(...args);
+    } finally {
+      semaphore.release();
+    }
+  }) as T;
+}

package/src/utils/utils.test.ts

@@ -0,0 +1,171 @@
+/**
+ * @file 工具函数测试
+ * @description 测试通用工具函数
+ */
+
+import {
+  delay,
+  throttle,
+  debounce,
+  formatBytes,
+  generateUUID,
+  chunk,
+  safeParseJSON,
+  clamp,
+  isValidUrl,
+} from '../utils';
+
+describe('Utils', () => {
+  describe('delay', () => {
+    it('should delay for specified milliseconds', async () => {
+      const start = Date.now();
+      await delay(100);
+      const elapsed = Date.now() - start;
+      expect(elapsed).toBeGreaterThanOrEqual(90);
+    });
+  });
+
+  describe('throttle', () => {
+    beforeEach(() => {
+      jest.useFakeTimers();
+    });
+
+    afterEach(() => {
+      jest.useRealTimers();
+    });
+
+    it('should throttle function calls', () => {
+      const fn = jest.fn();
+      const throttled = throttle(fn, 100);
+
+      throttled();
+      throttled();
+      throttled();
+
+      expect(fn).toHaveBeenCalledTimes(1);
+    });
+
+    it('should allow calls after throttle period', () => {
+      const fn = jest.fn();
+      const throttled = throttle(fn, 100);
+
+      throttled();
+      jest.advanceTimersByTime(100);
+      throttled();
+
+      expect(fn).toHaveBeenCalledTimes(2);
+    });
+  });
+
+  describe('debounce', () => {
+    beforeEach(() => {
+      jest.useFakeTimers();
+    });
+
+    afterEach(() => {
+      jest.useRealTimers();
+    });
+
+    it('should debounce function calls', () => {
+      const fn = jest.fn();
+      const debounced = debounce(fn, 100);
+
+      debounced();
+      debounced();
+      debounced();
+
+      jest.advanceTimersByTime(100);
+
+      expect(fn).toHaveBeenCalledTimes(1);
+    });
+
+    it('should execute immediately when immediate is true', () => {
+      const fn = jest.fn();
+      const debounced = debounce(fn, 100, true);
+
+      debounced();
+      debounced();
+      debounced();
+
+      expect(fn).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe('formatBytes', () => {
+    it('should format bytes correctly', () => {
+      expect(formatBytes(0)).toBe('0 Bytes');
+      expect(formatBytes(1024)).toBe('1 KB');
+      expect(formatBytes(1024 * 1024)).toBe('1 MB');
+      expect(formatBytes(1024 * 1024 * 1024)).toBe('1 GB');
+    });
+
+    it('should respect decimal places', () => {
+      expect(formatBytes(1536, 2)).toBe('1.5 KB');
+      expect(formatBytes(1536, 0)).toBe('2 KB');
+    });
+  });
+
+  describe('generateUUID', () => {
+    it('should generate valid UUID format', () => {
+      const uuid = generateUUID();
+      const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+      expect(uuid).toMatch(uuidRegex);
+    });
+
+    it('should generate unique UUIDs', () => {
+      const uuids = new Set(Array.from({ length: 100 }, () => generateUUID()));
+      expect(uuids.size).toBe(100);
+    });
+  });
+
+  describe('chunk', () => {
+    it('should split array into chunks', () => {
+      const arr = [1, 2, 3, 4, 5, 6, 7, 8, 9];
+      const chunks = chunk(arr, 3);
+      expect(chunks).toEqual([[1, 2, 3], [4, 5, 6], [7, 8, 9]]);
+    });
+
+    it('should handle last chunk smaller than chunk size', () => {
+      const arr = [1, 2, 3, 4, 5];
+      const chunks = chunk(arr, 2);
+      expect(chunks).toEqual([[1, 2], [3, 4], [5]]);
+    });
+
+    it('should throw error for invalid chunk size', () => {
+      expect(() => chunk([1, 2, 3], 0)).toThrow('Chunk size must be greater than 0');
+    });
+  });
+
+  describe('safeParseJSON', () => {
+    it('should parse valid JSON', () => {
+      const result = safeParseJSON('{"a": 1}', null);
+      expect(result).toEqual({ a: 1 });
+    });
+
+    it('should return fallback for invalid JSON', () => {
+      const result = safeParseJSON('invalid', { fallback: true });
+      expect(result).toEqual({ fallback: true });
+    });
+  });
+
+  describe('clamp', () => {
+    it('should clamp value within range', () => {
+      expect(clamp(5, 0, 10)).toBe(5);
+      expect(clamp(-5, 0, 10)).toBe(0);
+      expect(clamp(15, 0, 10)).toBe(10);
+    });
+  });
+
+  describe('isValidUrl', () => {
+    it('should validate correct URLs', () => {
+      expect(isValidUrl('https://example.com')).toBe(true);
+      expect(isValidUrl('http://localhost:3000')).toBe(true);
+      expect(isValidUrl('ftp://files.example.com')).toBe(true);
+    });
+
+    it('should reject invalid URLs', () => {
+      expect(isValidUrl('not-a-url')).toBe(false);
+      expect(isValidUrl('')).toBe(false);
+    });
+  });
+});

package/src/version.ts

@@ -5,7 +5,7 @@
  */
 
 // 当前版本号
-export const VERSION = '1.5.0';
+export const VERSION = '1.3.3';
 
 // 构建日期
 export const BUILD_DATE = new Date().toISOString(); 

package/dist/types/core/base-module.d.ts

@@ -1,44 +0,0 @@
-/**
- * @file 基础模块
- * @description 提供基础模块实现，作为所有功能模块的基类
- * @module core/base-module
- */
-import { EventEmitter } from './event-emitter';
-import { Logger } from './logger';
-import { Module } from './module-manager';
-/**
- * 基础模块类
- * 提供模块的基本功能和生命周期管理
- */
-export declare abstract class BaseModule extends EventEmitter implements Module {
-    /** 模块名称 */
-    abstract readonly name: string;
-    /** 模块版本 */
-    readonly version: string;
-    /** 模块是否已初始化 */
-    protected _isInitialized: boolean;
-    /** 日志工具 */
-    protected logger: Logger;
-    /**
-     * 构造函数
-     */
-    constructor();
-    /**
-     * 获取模块是否已初始化
-     */
-    get isInitialized(): boolean;
-    /**
-     * 初始化模块
-     * 子类必须实现此方法
-     */
-    abstract initialize(): Promise<void>;
-    /**
-     * 释放模块资源
-     * 子类可以覆盖此方法以添加额外的资源释放逻辑
-     */
-    dispose(): Promise<void>;
-    /**
-     * 检查模块是否已初始化，如果未初始化则抛出错误
-     */
-    protected ensureInitialized(): void;
-}