id-scanner-lib 1.5.0 → 1.6.2

package/src/utils/error-handler.ts

@@ -0,0 +1,110 @@
+/**
+ * @file 统一错误处理工具
+ * @description 提供统一的错误处理和日志记录功能
+ * @module utils/error-handler
+ */
+
+import { Logger } from '../core/logger';
+
+/**
+ * 错误严重级别
+ */
+export enum ErrorSeverity {
+  DEBUG = 'debug',
+  INFO = 'info',
+  WARN = 'warn',
+  ERROR = 'error'
+}
+
+/**
+ * 错误处理工具类
+ */
+export class ErrorHandler {
+  private static logger = Logger.getInstance();
+
+  /**
+   * 处理错误并记录日志
+   * @param context 错误上下文(模块名)
+   * @param message 错误消息
+   * @param error 错误对象
+   * @param severity 错误级别
+   */
+  static handle(
+    context: string,
+    message: string,
+    error?: unknown,
+    severity: ErrorSeverity = ErrorSeverity.ERROR
+  ): void {
+    const errorObj = error instanceof Error ? error : error ? new Error(String(error)) : undefined;
+    
+    switch (severity) {
+      case ErrorSeverity.DEBUG:
+        this.logger.debug(context, message, errorObj);
+        break;
+      case ErrorSeverity.INFO:
+        this.logger.info(context, message, errorObj);
+        break;
+      case ErrorSeverity.WARN:
+        this.logger.warn(context, message, errorObj);
+        break;
+      case ErrorSeverity.ERROR:
+      default:
+        this.logger.error(context, message, errorObj);
+    }
+  }
+
+  /**
+   * 处理异步错误
+   * @param context 错误上下文
+   * @param message 错误消息
+   * @returns 返回一个错误处理函数
+   */
+  static asyncHandler(
+    context: string,
+    message: string
+  ): (error: unknown) => void {
+    return (error: unknown) => {
+      this.handle(context, message, error);
+    };
+  }
+
+  /**
+   * 安全执行异步函数并处理错误
+   * @param fn 异步函数
+   * @param context 错误上下文
+   * @param fallbackValue 错误时的返回值
+   * @returns 函数结果或 fallbackValue
+   */
+  static async safeExecute<T>(
+    fn: () => Promise<T>,
+    context: string,
+    fallbackValue: T
+  ): Promise<T> {
+    try {
+      return await fn();
+    } catch (error) {
+      this.handle(context, 'Operation failed', error);
+      return fallbackValue;
+    }
+  }
+
+  /**
+   * 安全执行函数并处理错误
+   * @param fn 函数
+   * @param context 错误上下文
+   * @param fallbackValue 错误时的返回值
+   * @returns 函数结果或 fallbackValue
+   */
+  static safeExecuteSync<T>(
+    fn: () => T,
+    context: string,
+    fallbackValue: T
+  ): T {
+    try {
+      return fn();
+    } catch (error) {
+      this.handle(context, 'Operation failed', error);
+      return fallbackValue;
+    }
+  }
+}

package/src/utils/index.test.ts

@@ -0,0 +1,186 @@
+/**
+ * @file 通用工具测试
+ * @description 测试通用工具函数
+ */
+
+import {
+  delay,
+  throttle,
+  debounce,
+  formatBytes,
+  generateUUID,
+  chunk,
+  safeParseJSON,
+  clamp,
+  isValidUrl,
+  browserCapabilities
+} from './index';
+
+describe('delay', () => {
+  it('should delay for specified milliseconds', async () => {
+    const start = Date.now();
+    await delay(50);
+    const elapsed = Date.now() - start;
+    
+    expect(elapsed).toBeGreaterThanOrEqual(45);
+  });
+});
+
+describe('throttle', () => {
+  beforeEach(() => {
+    jest.useFakeTimers();
+  });
+
+  afterEach(() => {
+    jest.useRealTimers();
+  });
+
+  it('should throttle function calls', () => {
+    let count = 0;
+    const fn = throttle(() => count++, 100);
+    
+    fn();
+    fn();
+    fn();
+    
+    expect(count).toBe(1);
+    
+    jest.advanceTimersByTime(100);
+    
+    fn();
+    expect(count).toBe(2);
+  });
+});
+
+describe('debounce', () => {
+  beforeEach(() => {
+    jest.useFakeTimers();
+  });
+
+  afterEach(() => {
+    jest.useRealTimers();
+  });
+
+  it('should debounce function calls', () => {
+    let count = 0;
+    const fn = debounce(() => count++, 100);
+    
+    fn();
+    fn();
+    fn();
+    
+    expect(count).toBe(0);
+    
+    jest.advanceTimersByTime(100);
+    
+    expect(count).toBe(1);
+  });
+
+  it('should execute immediately when immediate is true', () => {
+    let count = 0;
+    const fn = debounce(() => count++, 100, true);
+    
+    fn();
+    // Immediate should execute once
+    expect(count).toBe(1);
+    
+    // Advance time and check if it runs again
+    jest.advanceTimersByTime(100);
+    // Depending on implementation, this may vary
+    expect(count).toBeGreaterThanOrEqual(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 handle decimals', () => {
+    expect(formatBytes(1536, 2)).toBe('1.5 KB');
+  });
+});
+
+describe('generateUUID', () => {
+  it('should generate valid UUID', () => {
+    const uuid = generateUUID();
+    
+    expect(uuid).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/);
+  });
+
+  it('should generate unique UUIDs', () => {
+    const uuids = new Set<string>();
+    for (let i = 0; i < 100; i++) {
+      uuids.add(generateUUID());
+    }
+    
+    expect(uuids.size).toBe(100);
+  });
+});
+
+describe('chunk', () => {
+  it('should split array into chunks', () => {
+    const arr = [1, 2, 3, 4, 5, 6, 7];
+    const chunks = chunk(arr, 3);
+    
+    expect(chunks).toEqual([[1, 2, 3], [4, 5, 6], [7]]);
+  });
+
+  it('should throw error for invalid chunk size', () => {
+    expect(() => chunk([1, 2, 3], 0)).toThrow();
+  });
+});
+
+describe('safeParseJSON', () => {
+  it('should parse valid JSON', () => {
+    const result = safeParseJSON('{"a": 1}', { default: true });
+    expect(result).toEqual({ a: 1 });
+  });
+
+  it('should return fallback for invalid JSON', () => {
+    const result = safeParseJSON<boolean>('invalid', true);
+    expect(result).toBe(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 URLs', () => {
+    expect(isValidUrl('https://example.com')).toBe(true);
+    expect(isValidUrl('http://test.com/path')).toBe(true);
+    expect(isValidUrl('invalid')).toBe(false);
+    expect(isValidUrl('not a url')).toBe(false);
+  });
+});
+
+describe('browserCapabilities', () => {
+  it('should check camera support', () => {
+    expect(typeof browserCapabilities.hasCamera).toBe('function');
+  });
+
+  it('should check WebAssembly support', () => {
+    expect(typeof browserCapabilities.hasWasm).toBe('function');
+  });
+
+  it('should check WebWorker support', () => {
+    expect(typeof browserCapabilities.hasWebWorker).toBe('function');
+  });
+
+  it('should check WebGL support', () => {
+    expect(typeof browserCapabilities.hasWebGL).toBe('function');
+  });
+
+  it('should use supports method', () => {
+    expect(typeof browserCapabilities.supports).toBe('function');
+  });
+});

package/src/utils/index.ts

@@ -4,6 +4,9 @@
  * @module utils
  */
 
+export * from './error-handler';
+export * from './retry';
+
 /**
  * 创建延迟Promise
  * @param ms 延迟毫秒数

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