id-scanner-lib/src/core/scanner.ts

Browser-based ID card, QR code, and face recognition scanner with liveness detection

/**
 * @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';