id-scanner-lib 1.3.2 → 1.5.0

package/src/core/config.ts

@@ -0,0 +1,268 @@
+/**
+ * @file 配置管理器
+ * @description 提供全局配置管理功能
+ * @module core/config
+ */
+
+/**
+ * 配置管理器
+ * 负责存储和管理应用程序的配置
+ */
+export class ConfigManager {
+  /** 单例实例 */
+  private static instance: ConfigManager;
+  
+  /** 配置存储 */
+  private config: Record<string, any> = {};
+  
+  /** 配置变更回调 */
+  private changeCallbacks: Map<string, Array<(value: any, oldValue: any) => void>> = new Map();
+  
+  /**
+   * 私有构造函数
+   */
+  private constructor() {
+    // 设置默认配置
+    this.config = {
+      debug: false,
+      logLevel: 'info',
+      camera: {
+        resolution: {
+          width: 1280,
+          height: 720
+        },
+        frameRate: 30,
+        facingMode: 'environment'
+      },
+      performance: {
+        useCache: true
+      }
+    };
+  }
+  
+  /**
+   * 获取单例实例
+   */
+  public static getInstance(): ConfigManager {
+    if (!ConfigManager.instance) {
+      ConfigManager.instance = new ConfigManager();
+    }
+    return ConfigManager.instance;
+  }
+  
+  /**
+   * 获取配置值
+   * @param key 配置键，支持点号分隔的路径
+   * @param defaultValue 默认值
+   */
+  get<T = any>(key: string, defaultValue?: T): T {
+    const value = this.getNestedValue(this.config, key);
+    return (value !== undefined) ? value : (defaultValue as T);
+  }
+  
+  /**
+   * 设置配置值
+   * @param key 配置键，支持点号分隔的路径
+   * @param value 配置值
+   */
+  set<T = any>(key: string, value: T): void {
+    const oldValue = this.get(key);
+    
+    // 如果值相同，不做任何事
+    if (oldValue === value) {
+      return;
+    }
+    
+    this.setNestedValue(this.config, key, value);
+    
+    // 触发变更回调
+    this.triggerChangeCallbacks(key, value, oldValue);
+  }
+  
+  /**
+   * 批量更新配置
+   * @param config 配置对象
+   */
+  updateConfig(config: Record<string, any>): void {
+    Object.entries(config).forEach(([key, value]) => {
+      this.set(key, value);
+    });
+  }
+  
+  /**
+   * 重置为默认配置
+   */
+  reset(): void {
+    const oldConfig = { ...this.config };
+    
+    // 重新创建默认配置
+    this.config = {
+      debug: false,
+      logLevel: 'info',
+      camera: {
+        resolution: {
+          width: 1280,
+          height: 720
+        },
+        frameRate: 30,
+        facingMode: 'environment'
+      },
+      performance: {
+        useCache: true
+      }
+    };
+    
+    // 触发所有回调
+    Object.keys(oldConfig).forEach(key => {
+      this.triggerChangeCallbacks(key, this.get(key), oldConfig[key]);
+    });
+  }
+  
+  /**
+   * 注册配置变更回调
+   * @param key 配置键
+   * @param callback 回调函数
+   */
+  onConfigChange<T = any>(key: string, callback: (value: T, oldValue: T) => void): void {
+    if (!this.changeCallbacks.has(key)) {
+      this.changeCallbacks.set(key, []);
+    }
+    
+    this.changeCallbacks.get(key)!.push(callback);
+  }
+  
+  /**
+   * 移除配置变更回调
+   * @param key 配置键
+   * @param callback 特定回调函数，如不提供则移除所有
+   */
+  offConfigChange<T = any>(key: string, callback?: (value: T, oldValue: T) => void): void {
+    if (!this.changeCallbacks.has(key)) {
+      return;
+    }
+    
+    if (callback) {
+      // 移除特定回调
+      const callbacks = this.changeCallbacks.get(key)!;
+      const index = callbacks.indexOf(callback as any);
+      if (index !== -1) {
+        callbacks.splice(index, 1);
+      }
+      
+      // 如果没有回调，删除键
+      if (callbacks.length === 0) {
+        this.changeCallbacks.delete(key);
+      }
+    } else {
+      // 移除所有回调
+      this.changeCallbacks.delete(key);
+    }
+  }
+  
+  /**
+   * 获取嵌套值
+   * @param obj 对象
+   * @param path 路径
+   */
+  private getNestedValue(obj: Record<string, any>, path: string): any {
+    // 处理根路径
+    if (!path) {
+      return obj;
+    }
+    
+    // 处理嵌套路径
+    const parts = path.split('.');
+    let current = obj;
+    
+    for (const part of parts) {
+      if (current === undefined || current === null) {
+        return undefined;
+      }
+      
+      current = current[part];
+    }
+    
+    return current;
+  }
+  
+  /**
+   * 设置嵌套值
+   * @param obj 对象
+   * @param path 路径
+   * @param value 值
+   */
+  private setNestedValue(obj: Record<string, any>, path: string, value: any): void {
+    // 处理根路径
+    if (!path) {
+      return;
+    }
+    
+    // 处理嵌套路径
+    const parts = path.split('.');
+    let current = obj;
+    
+    // 遍历路径，直到倒数第二部分
+    for (let i = 0; i < parts.length - 1; i++) {
+      const part = parts[i];
+      
+      // 如果不存在，创建新对象
+      if (current[part] === undefined || current[part] === null || typeof current[part] !== 'object') {
+        current[part] = {};
+      }
+      
+      current = current[part];
+    }
+    
+    // 设置最终值
+    current[parts[parts.length - 1]] = value;
+  }
+  
+  /**
+   * 触发变更回调
+   * @param key 配置键
+   * @param value 新值
+   * @param oldValue 旧值
+   */
+  private triggerChangeCallbacks(key: string, value: any, oldValue: any): void {
+    // 触发特定键的回调
+    if (this.changeCallbacks.has(key)) {
+      const callbacks = this.changeCallbacks.get(key)!;
+      callbacks.forEach(callback => {
+        try {
+          callback(value, oldValue);
+        } catch (error) {
+          console.error(`Error in config change callback for key ${key}:`, error);
+        }
+      });
+    }
+    
+    // 触发父路径的回调
+    const parts = key.split('.');
+    while (parts.length > 1) {
+      parts.pop();
+      const parentKey = parts.join('.');
+      
+      if (this.changeCallbacks.has(parentKey)) {
+        const parentValue = this.get(parentKey);
+        this.changeCallbacks.get(parentKey)!.forEach(callback => {
+          try {
+            callback(parentValue, parentValue);
+          } catch (error) {
+            console.error(`Error in config change callback for parent key ${parentKey}:`, error);
+          }
+        });
+      }
+    }
+  }
+} 
+
+/**
+ * 模块配置接口
+ * 定义所有模块共享的基础配置属性
+ */
+export interface ModuleConfig {
+  /** 是否启用该模块 */
+  enabled: boolean;
+  /** 其他模块特定配置 */
+  [key: string]: any;
+} 

package/src/core/errors.ts

@@ -0,0 +1,174 @@
+/**
+ * @file 错误处理模块
+ * @description 定义ID-Scanner-Lib的错误类层次结构
+ * @module core/errors
+ */
+
+/**
+ * ID-Scanner-Lib 基础错误类
+ * 所有库特定错误的基类
+ */
+export class IDScannerError extends Error {
+  /** 错误代码 */
+  public code: string;
+  /** 错误原因 */
+  public cause?: Error;
+
+  /**
+   * 构造函数
+   * @param message 错误消息
+   * @param options 错误选项
+   */
+  constructor(message: string, options?: { code?: string; cause?: Error }) {
+    super(message);
+    
+    // 设置错误名称
+    this.name = this.constructor.name;
+    
+    // 设置错误代码
+    this.code = options?.code || 'UNKNOWN_ERROR';
+    
+    // 设置错误原因
+    this.cause = options?.cause;
+    
+    // 捕获堆栈
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+}
+
+/**
+ * 初始化错误
+ * 当库初始化失败时抛出
+ */
+export class InitializationError extends IDScannerError {
+  constructor(message: string, details?: string) {
+    super(`初始化失败: ${message}${details ? ` (${details})` : ''}`, { code: 'INIT_FAILED' });
+    this.name = 'InitializationError';
+  }
+}
+
+/**
+ * 设备错误
+ * 当访问硬件设备(如摄像头)失败时抛出
+ */
+export class DeviceError extends IDScannerError {
+  constructor(message: string) {
+    super(`设备错误: ${message}`, { code: 'DEVICE_ERROR' });
+    this.name = 'DeviceError';
+  }
+}
+
+/**
+ * 摄像头访问错误
+ * 当无法访问或启动摄像头时抛出
+ */
+export class CameraAccessError extends IDScannerError {
+  constructor(message: string, options?: { code?: string; cause?: Error }) {
+    super(`摄像头访问失败: ${message}`, {
+      code: options?.code || 'CAMERA_ACCESS_FAILED',
+      cause: options?.cause
+    });
+    this.name = 'CameraAccessError';
+  }
+}
+
+/**
+ * 人脸检测错误
+ * 当人脸检测过程失败时抛出
+ */
+export class FaceDetectionError extends IDScannerError {
+  constructor(message: string) {
+    super(`人脸检测失败: ${message}`, { code: 'FACE_DETECTION_FAILED' });
+    this.name = 'FaceDetectionError';
+  }
+}
+
+/**
+ * 人脸比对错误
+ * 当人脸比对过程失败时抛出
+ */
+export class FaceComparisonError extends IDScannerError {
+  constructor(message: string) {
+    super(`人脸比对失败: ${message}`, { code: 'FACE_COMPARISON_FAILED' });
+    this.name = 'FaceComparisonError';
+  }
+}
+
+/**
+ * 活体检测错误
+ * 当活体检测过程失败时抛出
+ */
+export class LivenessDetectionError extends IDScannerError {
+  constructor(message: string) {
+    super(`活体检测失败: ${message}`, { code: 'LIVENESS_DETECTION_FAILED' });
+    this.name = 'LivenessDetectionError';
+  }
+}
+
+/**
+ * OCR识别错误
+ * 当OCR文字识别失败时抛出
+ */
+export class OCRProcessingError extends IDScannerError {
+  constructor(message: string) {
+    super(`OCR处理失败: ${message}`, { code: 'OCR_PROCESSING_FAILED' });
+    this.name = 'OCRProcessingError';
+  }
+}
+
+/**
+ * 二维码扫描错误
+ * 当二维码扫描失败时抛出
+ */
+export class QRScanError extends IDScannerError {
+  constructor(message: string) {
+    super(`二维码扫描失败: ${message}`, { code: 'QR_SCAN_FAILED' });
+    this.name = 'QRScanError';
+  }
+}
+
+/**
+ * 身份证检测错误
+ * 当身份证检测失败时抛出
+ */
+export class IDCardDetectionError extends IDScannerError {
+  constructor(message: string) {
+    super(`身份证检测失败: ${message}`, { code: 'ID_CARD_DETECTION_FAILED' });
+    this.name = 'IDCardDetectionError';
+  }
+}
+
+/**
+ * 资源加载错误
+ * 当无法加载必要资源(如模型)时抛出
+ */
+export class ResourceLoadError extends IDScannerError {
+  constructor(resource: string, reason: string) {
+    super(`无法加载资源 ${resource}: ${reason}`, { code: 'RESOURCE_LOAD_FAILED' });
+    this.name = 'ResourceLoadError';
+  }
+}
+
+/**
+ * 参数错误
+ * 当提供的参数无效时抛出
+ */
+export class InvalidArgumentError extends IDScannerError {
+  constructor(paramName: string, reason: string) {
+    super(`无效的参数 ${paramName}: ${reason}`, { code: 'INVALID_ARGUMENT' });
+    this.name = 'InvalidArgumentError';
+  }
+}
+
+/**
+ * 不支持错误
+ * 当尝试使用不支持的功能或当前环境无法使用的功能时抛出
+ */
+export class NotSupportedError extends IDScannerError {
+  constructor(feature: string) {
+    super(`不支持的功能: ${feature}`, { code: 'NOT_SUPPORTED' });
+    this.name = 'NotSupportedError';
+  }
+} 

package/src/core/event-emitter.ts

@@ -0,0 +1,110 @@
+/**
+ * @file 事件发射器
+ * @description 提供基础的事件发射和订阅功能
+ * @module core/event-emitter
+ */
+
+/**
+ * 事件处理器类型
+ */
+type EventHandler = (data?: any) => void;
+
+/**
+ * 事件发射器基类
+ * 提供基础的事件发射和订阅功能
+ */
+export class EventEmitter {
+  /** 事件处理器映射 */
+  private eventHandlers: Map<string, Set<EventHandler>> = new Map();
+  
+  /**
+   * 订阅事件
+   * @param eventName 事件名称
+   * @param handler 事件处理器
+   */
+  on(eventName: string, handler: EventHandler): void {
+    if (!this.eventHandlers.has(eventName)) {
+      this.eventHandlers.set(eventName, new Set());
+    }
+    
+    this.eventHandlers.get(eventName)!.add(handler);
+  }
+  
+  /**
+   * 取消订阅事件
+   * @param eventName 事件名称
+   * @param handler 事件处理器，如果不提供则移除该事件的所有处理器
+   */
+  off(eventName: string, handler?: EventHandler): void {
+    if (!this.eventHandlers.has(eventName)) {
+      return;
+    }
+    
+    if (handler) {
+      this.eventHandlers.get(eventName)!.delete(handler);
+      
+      // 如果没有处理器了，删除这个事件
+      if (this.eventHandlers.get(eventName)!.size === 0) {
+        this.eventHandlers.delete(eventName);
+      }
+    } else {
+      // 移除该事件的所有处理器
+      this.eventHandlers.delete(eventName);
+    }
+  }
+  
+  /**
+   * 订阅事件，但只触发一次
+   * @param eventName 事件名称
+   * @param handler 事件处理器
+   */
+  once(eventName: string, handler: EventHandler): void {
+    const onceHandler = (data?: any) => {
+      handler(data);
+      this.off(eventName, onceHandler);
+    };
+    
+    this.on(eventName, onceHandler);
+  }
+  
+  /**
+   * 发射事件
+   * @param eventName 事件名称
+   * @param data 事件数据
+   */
+  emit(eventName: string, data?: any): void {
+    if (!this.eventHandlers.has(eventName)) {
+      return;
+    }
+    
+    for (const handler of this.eventHandlers.get(eventName)!) {
+      try {
+        handler(data);
+      } catch (error) {
+        console.error(`Error in event handler for "${eventName}":`, error);
+      }
+    }
+  }
+  
+  /**
+   * 获取某个事件的处理器数量
+   * @param eventName 事件名称
+   */
+  listenerCount(eventName: string): number {
+    return this.eventHandlers.has(eventName) ? this.eventHandlers.get(eventName)!.size : 0;
+  }
+  
+  /**
+   * 移除所有事件处理器
+   */
+  removeAllListeners(): void {
+    this.eventHandlers.clear();
+  }
+  
+  /**
+   * 获取所有事件名称
+   */
+  eventNames(): string[] {
+    return Array.from(this.eventHandlers.keys());
+  }
+}