id-scanner-lib 1.7.0 → 2.0.0

package/src/core/errors.ts

@@ -1,174 +1,125 @@
 /**
- * @file 错误处理模块
- * @description 定义ID-Scanner-Lib的错误类层次结构
+ * @file Scanner Errors
+ * @description Error classes for Scanner
  * @module core/errors
  */
 
 /**
- * ID-Scanner-Lib 基础错误类
- * 所有库特定错误的基类
+ * Scanner specific error
  */
-export class IDScannerError extends Error {
-  /** 错误代码 */
+export class ScannerError extends Error {
+  /**
+   * Error code
+   */
   public code: string;
-  /** 错误原因 */
-  public cause?: Error;
+  /**
+   * Module that threw the error
+   */
+  public module?: string;
 
   /**
-   * 构造函数
-   * @param message 错误消息
-   * @param options 错误选项
+   * Create a ScannerError
+   * @param message Error message
+   * @param code Error code
+   * @param module Module name
    */
-  constructor(message: string, options?: { code?: string; cause?: Error }) {
+  constructor(message: string, code: string, module?: string) {
     super(message);
-    
-    // 设置错误名称
-    this.name = this.constructor.name;
-    
-    // 设置错误代码
-    this.code = options?.code || 'UNKNOWN_ERROR';
-    
-    // 设置错误原因
-    this.cause = options?.cause;
-    
-    // 捕获堆栈 (Node.js专有，浏览器环境忽略)
-    if (typeof (Error as any).captureStackTrace === 'function') {
-      (Error as any).captureStackTrace(this, this.constructor);
-    }
+    this.name = 'ScannerError';
+    this.code = code;
+    this.module = module;
   }
 }
 
 /**
- * 初始化错误
- * 当库初始化失败时抛出
+ * Camera access error
  */
-export class InitializationError extends IDScannerError {
-  constructor(message: string, details?: string) {
-    super(`初始化失败: ${message}${details ? ` (${details})` : ''}`, { code: 'INIT_FAILED' });
-    this.name = 'InitializationError';
+export class CameraAccessError extends Error {
+  constructor(message = 'Camera access denied') {
+    super(message);
+    this.name = 'CameraAccessError';
   }
 }
 
 /**
- * 设备错误
- * 当访问硬件设备(如摄像头)失败时抛出
+ * Device error
  */
-export class DeviceError extends IDScannerError {
-  constructor(message: string) {
-    super(`设备错误: ${message}`, { code: 'DEVICE_ERROR' });
+export class DeviceError extends Error {
+  constructor(message = 'Device error') {
+    super(message);
     this.name = 'DeviceError';
   }
 }
 
 /**
- * 摄像头访问错误
- * 当无法访问或启动摄像头时抛出
+ * Resource load error
  */
-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 ResourceLoadError extends Error {
+  public readonly id?: string;
+  constructor(message = 'Failed to load resource', id?: string) {
+    super(message);
+    this.name = 'ResourceLoadError';
+    this.id = id;
   }
 }
 
 /**
- * 人脸检测错误
- * 当人脸检测过程失败时抛出
+ * Face detection error
  */
-export class FaceDetectionError extends IDScannerError {
-  constructor(message: string) {
-    super(`人脸检测失败: ${message}`, { code: 'FACE_DETECTION_FAILED' });
+export class FaceDetectionError extends Error {
+  constructor(message = 'Face detection failed') {
+    super(message);
     this.name = 'FaceDetectionError';
   }
 }
 
 /**
- * 人脸比对错误
- * 当人脸比对过程失败时抛出
+ * Face comparison error
  */
-export class FaceComparisonError extends IDScannerError {
-  constructor(message: string) {
-    super(`人脸比对失败: ${message}`, { code: 'FACE_COMPARISON_FAILED' });
+export class FaceComparisonError extends Error {
+  constructor(message = 'Face comparison failed') {
+    super(message);
     this.name = 'FaceComparisonError';
   }
 }
 
 /**
- * 活体检测错误
- * 当活体检测过程失败时抛出
- */
-export class LivenessDetectionError extends IDScannerError {
-  constructor(message: string) {
-    super(`活体检测失败: ${message}`, { code: 'LIVENESS_DETECTION_FAILED' });
-    this.name = 'LivenessDetectionError';
-  }
-}
-
-/**
- * OCR识别错误
- * 当OCR文字识别失败时抛出
+ * Initialization error
  */
-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 InitializationError extends Error {
+  constructor(message = 'Initialization failed') {
+    super(message);
+    this.name = 'InitializationError';
   }
 }
 
 /**
- * 资源加载错误
- * 当无法加载必要资源(如模型)时抛出
+ * Liveness detection error
  */
-export class ResourceLoadError extends IDScannerError {
-  constructor(resource: string, reason: string) {
-    super(`无法加载资源 ${resource}: ${reason}`, { code: 'RESOURCE_LOAD_FAILED' });
-    this.name = 'ResourceLoadError';
+export class LivenessDetectionError extends Error {
+  constructor(message = 'Liveness detection failed') {
+    super(message);
+    this.name = 'LivenessDetectionError';
   }
 }
 
 /**
- * 参数错误
- * 当提供的参数无效时抛出
+ * Error codes for Scanner
  */
-export class InvalidArgumentError extends IDScannerError {
-  constructor(paramName: string, reason: string) {
-    super(`无效的参数 ${paramName}: ${reason}`, { code: 'INVALID_ARGUMENT' });
-    this.name = 'InvalidArgumentError';
-  }
-}
+export const ErrorCodes = {
+  /** Scanner not initialized */
+  NOT_INITIALIZED: 'SCANNER_001',
+  /** Module not found */
+  MODULE_NOT_FOUND: 'SCANNER_002',
+  /** Detection failed */
+  DETECTION_FAILED: 'SCANNER_003',
+  /** Camera access denied */
+  CAMERA_ACCESS_DENIED: 'CAMERA_001',
+  /** Camera not available */
+  CAMERA_NOT_AVAILABLE: 'CAMERA_002',
+} as const;
 
 /**
- * 不支持错误
- * 当尝试使用不支持的功能或当前环境无法使用的功能时抛出
+ * Type for error codes
  */
-export class NotSupportedError extends IDScannerError {
-  constructor(feature: string) {
-    super(`不支持的功能: ${feature}`, { code: 'NOT_SUPPORTED' });
-    this.name = 'NotSupportedError';
-  }
-} 
+export type ErrorCode = typeof ErrorCodes[keyof typeof ErrorCodes];

package/src/core/resource-manager.ts

@@ -10,6 +10,156 @@ import { ResourceLoadError } from './errors';
 import { EventEmitter } from './event-emitter';
 import { Result } from './result';
 
+/**
+ * 模型分片信息
+ */
+export interface ModelShard {
+  name: string;        // e.g. 'face-detector'
+  version: string;     // e.g. '1.0.0'
+  url: string;         // 完整 URL
+  size: number;        // bytes
+  hash?: string;       // 完整性校验
+}
+
+/**
+ * 模型缓存信息
+ */
+export interface ModelCacheInfo {
+  name: string;
+  version: string;
+  cachedAt: number;
+  size: number;
+}
+
+/**
+ * IndexedDB 模型缓存管理器
+ * 提供分片模型的持久化缓存功能
+ */
+export class ModelCacheManager {
+  private _dbName = 'id-scanner-lib-models';
+  private _storeName = 'model-cache';
+  private _db: IDBDatabase | null = null;
+
+  /**
+   * 初始化缓存管理器（打开 IndexedDB）
+   */
+  async init(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      const request = indexedDB.open(this._dbName, 1);
+      request.onerror = () => reject(new Error('Failed to open IndexedDB'));
+      request.onsuccess = () => {
+        this._db = request.result;
+        resolve();
+      };
+      request.onupgradeneeded = (event) => {
+        const db = (event.target as IDBOpenDBRequest).result;
+        if (!db.objectStoreNames.contains(this._storeName)) {
+          const store = db.createObjectStore(this._storeName, { keyPath: 'key' });
+          store.createIndex('name', 'name', { unique: false });
+          store.createIndex('version', 'version', { unique: false });
+        }
+      };
+    });
+  }
+
+  /**
+   * 生成缓存键
+   */
+  private _makeKey(model: ModelShard): string {
+    return `${model.name}@${model.version}`;
+  }
+
+  /**
+   * 检查模型是否已缓存
+   */
+  async has(model: ModelShard): Promise<boolean> {
+    if (!this._db) return false;
+    return new Promise((resolve, reject) => {
+      const tx = this._db!.transaction(this._storeName, 'readonly');
+      const store = tx.objectStore(this._storeName);
+      const req = store.get(this._makeKey(model));
+      req.onsuccess = () => resolve(!!req.result);
+      req.onerror = () => reject(req.error);
+    });
+  }
+
+  /**
+   * 存储模型数据
+   */
+  async store(model: ModelShard, data: ArrayBuffer): Promise<void> {
+    if (!this._db) throw new Error('ModelCacheManager not initialized');
+    return new Promise((resolve, reject) => {
+      const tx = this._db!.transaction(this._storeName, 'readwrite');
+      const store = tx.objectStore(this._storeName);
+      const record = {
+        key: this._makeKey(model),
+        name: model.name,
+        version: model.version,
+        url: model.url,
+        size: model.size,
+        data,
+        cachedAt: Date.now(),
+      };
+      const req = store.put(record);
+      req.onsuccess = () => resolve();
+      req.onerror = () => reject(req.error);
+    });
+  }
+
+  /**
+   * 加载模型数据
+   */
+  async load(model: ModelShard): Promise<ArrayBuffer | null> {
+    if (!this._db) throw new Error('ModelCacheManager not initialized');
+    return new Promise((resolve, reject) => {
+      const tx = this._db!.transaction(this._storeName, 'readonly');
+      const store = tx.objectStore(this._storeName);
+      const req = store.get(this._makeKey(model));
+      req.onsuccess = () => resolve(req.result ? req.result.data : null);
+      req.onerror = () => reject(req.error);
+    });
+  }
+
+  /**
+   * 清除所有缓存
+   */
+  async clear(): Promise<void> {
+    if (!this._db) return;
+    return new Promise((resolve, reject) => {
+      const tx = this._db!.transaction(this._storeName, 'readwrite');
+      const store = tx.objectStore(this._storeName);
+      const req = store.clear();
+      req.onsuccess = () => resolve();
+      req.onerror = () => reject(req.error);
+    });
+  }
+
+  /**
+   * 列出已缓存模型
+   */
+  async listCached(): Promise<ModelCacheInfo[]> {
+    if (!this._db) return [];
+    return new Promise((resolve, reject) => {
+      const tx = this._db!.transaction(this._storeName, 'readonly');
+      const store = tx.objectStore(this._storeName);
+      const req = store.getAll();
+      req.onsuccess = () => {
+        const results: ModelCacheInfo[] = req.result.map((r: any) => ({
+          name: r.name,
+          version: r.version,
+          cachedAt: r.cachedAt,
+          size: r.size,
+        }));
+        resolve(results);
+      };
+      req.onerror = () => reject(req.error);
+    });
+  }
+}
+
+/** 全局模型缓存管理器实例 */
+export const modelCache = new ModelCacheManager();
+
 /**
  * 资源类型枚举
  */

package/src/core/scanner.ts

@@ -0,0 +1,109 @@
+/**
+ * @file Scanner Core Class
+ * @description Main entry point for the Scanner library
+ * @module core/scanner
+ */
+
+import { ScannerConfig, ScannerModule, ImageSource, Face } from './config';
+import { ScannerError, ErrorCodes } from './errors';
+
+/**
+ * Scanner main class
+ * Provides unified interface for all scanning operations
+ */
+export class Scanner {
+  /**
+   * Internal configuration
+   */
+  private _config: Required<ScannerConfig>;
+  /**
+   * Loaded modules
+   */
+  private _modules: Map<string, ScannerModule>;
+  /**
+   * Initialization state
+   */
+  private _initialized: boolean = false;
+
+  /**
+   * Create a new Scanner instance
+   * @param config Scanner configuration
+   */
+  constructor(config: ScannerConfig = {}) {
+    this._config = this._normalizeConfig(config);
+    this._modules = new Map();
+  }
+
+  /**
+   * Check if scanner is initialized
+   */
+  get initialized(): boolean {
+    return this._initialized;
+  }
+
+  /**
+   * Normalize configuration with defaults
+   * @param config User provided config
+   * @returns Normalized config with defaults
+   */
+  private _normalizeConfig(config: ScannerConfig): Required<ScannerConfig> {
+    return {
+      debug: config.debug ?? false,
+      modules: {
+        face: config.modules?.face ?? true,
+        faceComparator: config.modules?.faceComparator ?? false,
+        faceLiveness: config.modules?.faceLiveness ?? false,
+        idCard: config.modules?.idCard ?? false,
+        qr: config.modules?.qr ?? false,
+      },
+      performance: {
+        maxCanvasWidth: config.performance?.maxCanvasWidth ?? 1280,
+        useWorker: config.performance?.useWorker ?? true,
+        lazyLoad: config.performance?.lazyLoad ?? true,
+      },
+    };
+  }
+
+  /**
+   * Initialize the scanner and load enabled modules
+   */
+  async initialize(): Promise<void> {
+    // Immediately load face core module
+    const { FaceDetector } = await import('../modules/face/detector');
+    const detector = new FaceDetector();
+    await detector.initialize();
+    this._modules.set('face-detector', detector);
+    this._initialized = true;
+  }
+
+  /**
+   * Detect faces in an image source
+   * @param input Image source (video, canvas, image, etc.)
+   * @returns Array of detected faces
+   */
+  async detectFace(input: ImageSource): Promise<Face[]> {
+    const detector = this._modules.get('face-detector');
+    if (!detector) {
+      throw new ScannerError(
+        'Scanner not initialized. Call initialize() first.',
+        ErrorCodes.NOT_INITIALIZED
+      );
+    }
+    return (detector as any).detect(input);
+  }
+
+  /**
+   * Destroy the scanner and release all resources
+   */
+  async destroy(): Promise<void> {
+    for (const module of this._modules.values()) {
+      await module.destroy();
+    }
+    this._modules.clear();
+    this._initialized = false;
+  }
+}
+
+// Re-export types
+export { ScannerConfig, ScannerModule, ImageSource, Face } from './config';
+export { ScannerError, ErrorCodes } from './errors';

package/src/core/utils/browser.ts

@@ -0,0 +1,7 @@
+/**
+ * @file Browser Utilities
+ * @description Browser environment utility functions
+ * @module core/utils/browser
+ */
+
+export {};

package/src/core/utils/canvas-pool.ts

@@ -0,0 +1,171 @@
+/**
+ * @file Canvas 对象池
+ * @description 提供 OffscreenCanvas/HTMLCanvasElement 的复用机制，减少内存分配和 GC 压力
+ * @module core/utils/canvas-pool
+ */
+
+/**
+ * Canvas 池条目
+ */
+export interface PooledCanvas {
+  canvas: OffscreenCanvas | HTMLCanvasElement;
+  width: number;
+  height: number;
+  inUse: boolean;
+}
+
+interface PoolEntry {
+  canvas: OffscreenCanvas | HTMLCanvasElement;
+  width: number;
+  height: number;
+  inUse: boolean;
+  lastUsed: number;
+}
+
+/**
+ * Canvas 对象池
+ *
+ * 复用 Canvas 元素，避免频繁创建和销毁导致的内存抖动
+ *
+ * @example
+ * ```typescript
+ * const pool = new CanvasPool();
+ * const acquired = pool.acquire(640, 480);
+ * // 使用 canvas 进行绘制...
+ * pool.release(acquired);
+ * ```
+ */
+export class CanvasPool {
+  private _pool: PoolEntry[] = [];
+  private _maxSize: number = 4;
+  private _useOffscreen: boolean;
+
+  /**
+   * 创建 Canvas 池
+   * @param maxSize 最大池大小
+   * @param useOffscreen 是否使用 OffscreenCanvas
+   */
+  constructor(maxSize: number = 4, useOffscreen: boolean = true) {
+    this._maxSize = maxSize;
+    this._useOffscreen = useOffscreen && typeof OffscreenCanvas !== 'undefined';
+  }
+
+  /**
+   * 从池中获取 Canvas
+   *
+   * 1. 查找尺寸匹配的可用 canvas（允许 10% 误差）
+   * 2. 无匹配则创建新的
+   * 3. 超出 _maxSize 则回收最旧的 inUse=false 的
+   * 4. 返回 PooledCanvas，标记 inUse=true
+   *
+   * @param width  宽度
+   * @param height 高度
+   */
+  acquire(width: number, height: number): PooledCanvas {
+    // 1. 查找尺寸匹配的可用 canvas（允许 10% 误差）
+    const matched = this._pool.find(p =>
+      !p.inUse &&
+      Math.abs(p.width - width) / width <= 0.1 &&
+      Math.abs(p.height - height) / height <= 0.1
+    );
+
+    if (matched) {
+      matched.inUse = true;
+      matched.lastUsed = Date.now();
+      return {
+        canvas: matched.canvas,
+        width: matched.width,
+        height: matched.height,
+        inUse: true,
+      };
+    }
+
+    // 2. 无匹配则创建新的
+    let canvas: OffscreenCanvas | HTMLCanvasElement;
+    if (this._useOffscreen) {
+      canvas = new OffscreenCanvas(width, height);
+    } else {
+      // 在非 OffscreenCanvas 环境（如 Node.js 测试）回退到 HTMLCanvasElement
+      if (typeof document !== 'undefined') {
+        canvas = document.createElement('canvas');
+        canvas.width = width;
+        canvas.height = height;
+      } else {
+        // 无法创建 canvas
+        throw new Error('CanvasPool: 无法创建 canvas (OffscreenCanvas 不可用，且 document 不存在)');
+      }
+    }
+
+    const entry: PoolEntry = {
+      canvas,
+      width,
+      height,
+      inUse: true,
+      lastUsed: Date.now(),
+    };
+
+    // 3. 超出 _maxSize 则回收最旧的 inUse=false 的
+    if (this._pool.length >= this._maxSize) {
+      const oldestIdx = this._findOldestAvailableIndex();
+      if (oldestIdx !== -1) {
+        this._pool.splice(oldestIdx, 1);
+      }
+    }
+
+    this._pool.push(entry);
+    return {
+      canvas: entry.canvas,
+      width: entry.width,
+      height: entry.height,
+      inUse: true,
+    };
+  }
+
+  /**
+   * 归还 Canvas 到池中
+   * @param pooled 要归还的 PooledCanvas
+   */
+  release(pooled: PooledCanvas): void {
+    const entry = this._pool.find(p => p.canvas === pooled.canvas);
+    if (entry) {
+      entry.inUse = false;
+      entry.lastUsed = Date.now();
+    }
+  }
+
+  /**
+   * 清空池
+   */
+  clear(): void {
+    this._pool = [];
+  }
+
+  /**
+   * 获取池统计信息
+   */
+  getStats(): { total: number; inUse: number; available: number } {
+    return {
+      total: this._pool.length,
+      inUse: this._pool.filter(p => p.inUse).length,
+      available: this._pool.filter(p => !p.inUse).length,
+    };
+  }
+
+  /**
+   * 查找最旧的可用条目索引
+   */
+  private _findOldestAvailableIndex(): number {
+    let oldestIdx = -1;
+    let oldestTime = Infinity;
+    for (let i = 0; i < this._pool.length; i++) {
+      if (!this._pool[i].inUse && this._pool[i].lastUsed < oldestTime) {
+        oldestTime = this._pool[i].lastUsed;
+        oldestIdx = i;
+      }
+    }
+    return oldestIdx;
+  }
+}
+
+/** 全局共享的 Canvas 池实例 */
+export const globalCanvasPool = new CanvasPool();

package/src/core/utils/canvas.ts

@@ -0,0 +1,7 @@
+/**
+ * @file Canvas Utilities
+ * @description Canvas-related utility functions
+ * @module core/utils/canvas
+ */
+
+export {};