id-scanner-lib 1.3.3 → 1.6.2

package/src/utils/retry.test.ts

@@ -0,0 +1,142 @@
+/**
+ * @file 重试工具测试
+ * @description 测试重试功能
+ */
+
+import { withRetry, AsyncCache, Semaphore } from './retry';
+
+describe('withRetry', () => {
+  it('should retry on failure and succeed', async () => {
+    let attempts = 0;
+    const fn = async () => {
+      attempts++;
+      if (attempts < 3) throw new Error('fail');
+      return 'success';
+    };
+
+    const result = await withRetry(fn, {
+      maxAttempts: 3,
+      initialDelay: 10
+    });
+
+    expect(result).toBe('success');
+    expect(attempts).toBe(3);
+  });
+
+  it('should fail after max attempts', async () => {
+    const fn = async () => {
+      throw new Error('always fails');
+    };
+
+    await expect(
+      withRetry(fn, { maxAttempts: 2, initialDelay: 10 })
+    ).rejects.toThrow('always fails');
+  });
+
+  it('should not retry if shouldRetry returns false', async () => {
+    let attempts = 0;
+    const fn = async () => {
+      attempts++;
+      throw new Error('test');
+    };
+
+    await expect(
+      withRetry(fn, {
+        maxAttempts: 3,
+        initialDelay: 10,
+        shouldRetry: () => false
+      })
+    ).rejects.toThrow();
+
+    expect(attempts).toBe(1);
+  });
+});
+
+describe('AsyncCache', () => {
+  it('should store and retrieve values', async () => {
+    const cache = new AsyncCache<string>(1000);
+    cache.set('key1', 'value1');
+
+    expect(cache.get('key1')).toBe('value1');
+  });
+
+  it('should return undefined for expired cache', async () => {
+    const cache = new AsyncCache<string>(50);
+    cache.set('key1', 'value1');
+
+    await new Promise(resolve => setTimeout(resolve, 60));
+
+    expect(cache.get('key1')).toBeUndefined();
+  });
+
+  it('should getOrSet value if not exists', async () => {
+    const cache = new AsyncCache<string>(1000);
+    
+    const result = await cache.getOrSet('key1', async () => 'computed');
+    
+    expect(result).toBe('computed');
+    expect(cache.get('key1')).toBe('computed');
+  });
+
+  it('should not recompute if exists', async () => {
+    const cache = new AsyncCache<string>(1000);
+    let computeCount = 0;
+    
+    const compute = async () => {
+      computeCount++;
+      return 'value';
+    };
+
+    await cache.getOrSet('key1', compute);
+    await cache.getOrSet('key1', compute);
+    
+    expect(computeCount).toBe(1);
+  });
+
+  it('should clear all cache', async () => {
+    const cache = new AsyncCache<string>(1000);
+    cache.set('key1', 'value1');
+    cache.set('key2', 'value2');
+    
+    expect(cache.size).toBe(2);
+    
+    cache.clear();
+    expect(cache.size).toBe(0);
+  });
+});
+
+describe('Semaphore', () => {
+  it('should acquire and release permits', async () => {
+    const sem = new Semaphore(2);
+    
+    expect(sem.availablePermits).toBe(2);
+    
+    await sem.acquire();
+    expect(sem.availablePermits).toBe(1);
+    
+    await sem.acquire();
+    expect(sem.availablePermits).toBe(0);
+    
+    sem.release();
+    expect(sem.availablePermits).toBe(1);
+  });
+
+  it('should tryAcquire returns false when no permits', () => {
+    const sem = new Semaphore(1);
+    sem.acquire();
+    
+    expect(sem.tryAcquire()).toBe(false);
+  });
+
+  it('should queue waiting acquires', async () => {
+    const sem = new Semaphore(1);
+    
+    // First acquire
+    await sem.acquire();
+    expect(sem.availablePermits).toBe(0);
+    
+    // Release
+    sem.release();
+    expect(sem.availablePermits).toBe(1);
+  });
+});

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/types.ts

@@ -70,12 +70,100 @@ export interface DetectionResult {
  * ```
  */
 export interface IDCardInfo {
+  /** 姓名 */
   name?: string;
+  /** 性别 */
   gender?: string;
-  nationality?: string;
+  /** 民族 */
+  ethnicity?: string;
+  /** 出生日期 */
   birthDate?: string;
+  /** 地址 */
   address?: string;
+  /** 身份证号码 */
   idNumber?: string;
-  issuingAuthority?: string;
+  /** 签发机关 */
+  issueAuthority?: string;
+  /** 有效期起始日期 */
+  validFrom?: string;
+  /** 有效期截止日期 */
+  validTo?: string;
+  /** 有效期限（完整文本） */
   validPeriod?: string;
+  /** 照片区域 */
+  photoRegion?: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  };
+  /** 类型 */
+  type?: string;
+  /** 置信度 */
+  confidence?: number;
+  /** 其他属性 */
+  [key: string]: any;
+}
+
+/**
+ * 点坐标
+ */
+export interface Point {
+  x: number;
+  y: number;
+}
+
+/**
+ * 矩形区域
+ */
+export interface Rect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+/**
+ * 可释放资源接口
+ */
+export interface Disposable {
+  /** 释放资源 */
+  dispose(): Promise<void>;
+}
+
+/**
+ * 图像处理选项
+ */
+export interface ImageProcessingOptions {
+  /** 亮度调整 (-100 到 100) */
+  brightness?: number;
+  /** 对比度调整 (-100 到 100) */
+  contrast?: number;
+  /** 饱和度调整 (-100 到 100) */
+  saturation?: number;
+  /** 锐化强度 (0 到 10) */
+  sharpen?: number | boolean;
+  /** 高斯模糊半径 (0 到 10) */
+  blur?: number;
+  /** 是否应用灰度转换 */
+  grayscale?: boolean;
+  /** 是否应用二值化 */
+  binarize?: boolean;
+  /** 二值化阈值 (0 到 255) */
+  threshold?: number;
+  /** 是否应用边缘检测 */
+  edgeDetection?: boolean;
+  /** 是否应用降噪 */
+  denoise?: boolean;
+  /** 是否应用直方图均衡化 */
+  histogramEqualization?: boolean;
+  /** 是否应用透视校正 */
+  perspectiveCorrection?: boolean;
+  /** 透视校正点 */
+  perspectivePoints?: {
+    topLeft: Point;
+    topRight: Point;
+    bottomRight: Point;
+    bottomLeft: Point;
+  };
 } 

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);
+    });
+  });
+});