id-scanner-lib 1.6.5 → 1.6.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "id-scanner-lib",
-  "version": "1.6.5",
+  "version": "1.6.7",
   "description": "Browser-based ID card, QR code, and face recognition scanner with liveness detection",
   "main": "dist/id-scanner-lib.js",
   "module": "dist/id-scanner-lib.esm.js",

package/src/core/event-emitter.ts

@@ -52,6 +52,15 @@ export class EventEmitter {
       this.eventHandlers.delete(eventName);
     }
   }
+
+  /**
+   * 取消订阅事件 (off的别名)
+   * @param eventName 事件名称
+   * @param handler 事件处理器
+   */
+  removeListener(eventName: string, handler: EventHandler): void {
+    this.off(eventName, handler);
+  }
   
   /**
    * 订阅事件，但只触发一次

package/src/core/logger.ts

@@ -9,19 +9,24 @@ import { ConfigManager } from './config';
 /**
  * 日志级别枚举
  */
-export enum LogLevel {
+export enum LoggerLevel {
   DEBUG = 'debug',
   INFO = 'info',
   WARN = 'warn',
   ERROR = 'error'
 }
 
+/**
+ * @deprecated 使用 LoggerLevel 代替
+ */
+export const LogLevel = LoggerLevel;
+
 /**
  * 日志条目接口
  */
 export interface LogEntry {
   /** 日志级别 */
-  level: LogLevel;
+  level: LoggerLevel;
   /** 日志标签 */
   tag: string;
   /** 日志消息 */
@@ -59,16 +64,16 @@ export class ConsoleLogHandler implements LogHandler {
     const prefix = `[${timestamp}] [${entry.level.toUpperCase()}] [${entry.tag}]`;
     
     switch (entry.level) {
-      case LogLevel.DEBUG:
+      case LoggerLevel.DEBUG:
         console.debug(prefix, entry.message, entry.error || '');
         break;
-      case LogLevel.INFO:
+      case LoggerLevel.INFO:
         console.info(prefix, entry.message, entry.error || '');
         break;
-      case LogLevel.WARN:
+      case LoggerLevel.WARN:
         console.warn(prefix, entry.message, entry.error || '');
         break;
-      case LogLevel.ERROR:
+      case LoggerLevel.ERROR:
         console.error(prefix, entry.message, entry.error || '');
         break;
       default:
@@ -119,7 +124,7 @@ export class MemoryLogHandler implements LogHandler {
    * 根据级别过滤日志条目
    * @param level 日志级别
    */
-  getEntriesByLevel(level: LogLevel): LogEntry[] {
+  getEntriesByLevel(level: LoggerLevel): LogEntry[] {
     return this.entries.filter(entry => entry.level === level);
   }
   
@@ -154,6 +159,8 @@ export class RemoteLogHandler implements LogHandler {
   private flushInterval: number;
   /** 定时发送的计时器ID */
   private timerId: number | null = null;
+  /** 是否在浏览器环境 */
+  private readonly isBrowser: boolean;
   
   /**
    * 构造函数
@@ -165,14 +172,17 @@ export class RemoteLogHandler implements LogHandler {
     this.endpoint = endpoint;
     this.maxQueueSize = maxQueueSize;
     this.flushInterval = flushInterval;
+    this.isBrowser = typeof window !== 'undefined' && typeof window.addEventListener === 'function';
     
     // 设置定时发送
     this.startTimer();
     
     // 页面卸载前尝试发送剩余日志
-    window.addEventListener('beforeunload', () => {
-      this.flush();
-    });
+    if (this.isBrowser) {
+      window.addEventListener('beforeunload', () => {
+        this.flush();
+      });
+    }
   }
   
   /**
@@ -181,7 +191,7 @@ export class RemoteLogHandler implements LogHandler {
    */
   handle(entry: LogEntry): void {
     // 只处理INFO以上级别的日志
-    if (entry.level >= LogLevel.INFO) {
+    if (entry.level >= LoggerLevel.INFO) {
       this.queue.push(entry);
       
       // 如果队列满了，立即发送
@@ -249,6 +259,7 @@ export class RemoteLogHandler implements LogHandler {
    * 开始定时发送
    */
   startTimer(): void {
+    if (!this.isBrowser) return;
     if (this.timerId !== null) return;
     
     this.timerId = window.setInterval(() => {
@@ -281,7 +292,7 @@ export class Logger {
   /** 默认标签 */
   private defaultTag: string = 'IDScanner';
   /** 日志级别 */
-  private logLevel: LogLevel = LogLevel.INFO;
+  private logLevel: LoggerLevel = LoggerLevel.INFO;
   
   /**
    * 私有构造函数，防止直接实例化
@@ -293,7 +304,7 @@ export class Logger {
     this.addHandler(new ConsoleLogHandler());
     
     // 监听配置变化
-    this.config.onConfigChange('logLevel', (level: LogLevel) => {
+    this.config.onConfigChange('logLevel', (level: LoggerLevel) => {
       this.debug('Logger', `Log level changed to ${level}`);
     });
   }
@@ -307,6 +318,13 @@ export class Logger {
     }
     return Logger.instance;
   }
+
+  /**
+   * 重置单例实例（主要用于测试）
+   */
+  public static resetInstance(): void {
+    Logger.instance = undefined as any;
+  }
   
   /**
    * 添加日志处理器
@@ -349,7 +367,7 @@ export class Logger {
    * @param error 错误
    */
   debug(tag: string, message: string, error?: Error): void {
-    this.log(LogLevel.DEBUG, tag, message, error);
+    this.log(LoggerLevel.DEBUG, tag, message, error);
   }
   
   /**
@@ -359,7 +377,7 @@ export class Logger {
    * @param error 错误
    */
   info(tag: string, message: string, error?: Error): void {
-    this.log(LogLevel.INFO, tag, message, error);
+    this.log(LoggerLevel.INFO, tag, message, error);
   }
   
   /**
@@ -369,7 +387,7 @@ export class Logger {
    * @param error 错误
    */
   warn(tag: string, message: string, error?: Error): void {
-    this.log(LogLevel.WARN, tag, message, error);
+    this.log(LoggerLevel.WARN, tag, message, error);
   }
   
   /**
@@ -379,7 +397,7 @@ export class Logger {
    * @param error 错误
    */
   error(tag: string, message: string, error?: Error): void {
-    this.log(LogLevel.ERROR, tag, message, error);
+    this.log(LoggerLevel.ERROR, tag, message, error);
   }
   
   /**
@@ -397,7 +415,7 @@ export class Logger {
    * @param message 消息
    * @param error 错误
    */
-  private log(level: LogLevel, tag: string, message: string, error?: Error): void {
+  private log(level: LoggerLevel, tag: string, message: string, error?: Error): void {
     // 检查日志级别
     const levelValue = this.getLevelValue(level);
     const currentLevelValue = this.getLevelValue(this.logLevel);
@@ -439,16 +457,16 @@ export class Logger {
     const prefix = `[${timestamp}] [${entry.level.toUpperCase()}] [${entry.tag}]`;
     
     switch (entry.level) {
-      case LogLevel.DEBUG:
+      case LoggerLevel.DEBUG:
         console.debug(`${prefix} ${entry.message}`, entry.error || '');
         break;
-      case LogLevel.INFO:
+      case LoggerLevel.INFO:
         console.info(`${prefix} ${entry.message}`, entry.error || '');
         break;
-      case LogLevel.WARN:
+      case LoggerLevel.WARN:
         console.warn(`${prefix} ${entry.message}`, entry.error || '');
         break;
-      case LogLevel.ERROR:
+      case LoggerLevel.ERROR:
         console.error(`${prefix} ${entry.message}`, entry.error || '');
         break;
     }
@@ -458,15 +476,15 @@ export class Logger {
    * 获取日志级别值
    * @param level 日志级别
    */
-  private getLevelValue(level: LogLevel): number {
+  private getLevelValue(level: LoggerLevel): number {
     switch (level) {
-      case LogLevel.DEBUG:
+      case LoggerLevel.DEBUG:
         return 0;
-      case LogLevel.INFO:
+      case LoggerLevel.INFO:
         return 1;
-      case LogLevel.WARN:
+      case LoggerLevel.WARN:
         return 2;
-      case LogLevel.ERROR:
+      case LoggerLevel.ERROR:
         return 3;
       default:
         return 1; // 默认INFO级别
@@ -477,23 +495,23 @@ export class Logger {
    * 设置日志级别
    * @param level 日志级别
    */
-  public setLevel(level: LogLevel | string): void {
+  public setLevel(level: LoggerLevel | string): void {
     if (typeof level === 'string') {
       switch (level) {
         case 'debug':
-          this.logLevel = LogLevel.DEBUG;
+          this.logLevel = LoggerLevel.DEBUG;
           break;
         case 'info':
-          this.logLevel = LogLevel.INFO;
+          this.logLevel = LoggerLevel.INFO;
           break;
         case 'warn':
-          this.logLevel = LogLevel.WARN;
+          this.logLevel = LoggerLevel.WARN;
           break;
         case 'error':
-          this.logLevel = LogLevel.ERROR;
+          this.logLevel = LoggerLevel.ERROR;
           break;
         default:
-          this.logLevel = LogLevel.INFO;
+          this.logLevel = LoggerLevel.INFO;
       }
     } else {
       this.logLevel = level;
@@ -506,7 +524,7 @@ export class Logger {
    * 获取当前日志级别
    * @returns 当前日志级别
    */
-  public getLevel(): LogLevel {
+  public getLevel(): LoggerLevel {
     return this.logLevel;
   }
 }

package/src/core/resource-manager.ts

@@ -118,6 +118,8 @@ export class ResourceManager extends EventEmitter {
   /** 加载中的资源请求 */
   private pendingRequests: Map<string, Promise<any>> = new Map();
   private initialized: boolean = false;
+  /** 是否在浏览器环境 */
+  private readonly isBrowser: boolean;
   
   /**
    * 私有构造函数
@@ -126,16 +128,19 @@ export class ResourceManager extends EventEmitter {
     super();
     this.config = ConfigManager.getInstance();
     this.logger = Logger.getInstance();
+    this.isBrowser = typeof window !== 'undefined' && typeof window.addEventListener === 'function';
     
     // 初始化资源清理定时器
     this.setupCleanupTimer();
     
     // 页面卸载时尝试释放资源
-    window.addEventListener('beforeunload', () => {
-      if (this.config.get('autoReleaseResources', true)) {
-        this.releaseAll();
-      }
-    });
+    if (this.isBrowser) {
+      window.addEventListener('beforeunload', () => {
+        if (this.config.get('autoReleaseResources', true)) {
+          this.releaseAll();
+        }
+      });
+    }
   }
   
   /**
@@ -147,6 +152,13 @@ export class ResourceManager extends EventEmitter {
     }
     return ResourceManager.instance;
   }
+
+  /**
+   * 重置单例实例（主要用于测试）
+   */
+  public static resetInstance(): void {
+    ResourceManager.instance = undefined as any;
+  }
   
   /**
    * 设置基础路径
@@ -402,10 +414,10 @@ export class ResourceManager extends EventEmitter {
     const promises = resources.map(async ({ id, url, options }) => {
       const result = await this.load(id, url, options);
       
-      if (result.isSuccess() && result.data !== undefined) {
-        results[id] = result.data;
-      } else if (result.isFailure() && result.error) {
-        errors.push({ id, error: result.error });
+      if (result.isSuccess() && result.getData() !== undefined) {
+        results[id] = result.getData();
+      } else if (result.isFailure() && result.getError()) {
+        errors.push({ id, error: result.getError()! });
       }
     });
     
@@ -668,6 +680,8 @@ export class ResourceManager extends EventEmitter {
    * 设置资源清理定时器
    */
   private setupCleanupTimer(): void {
+    if (!this.isBrowser) return;
+    
     const interval = 60000; // 每分钟检查一次
     
     this.cleanupTimerId = window.setInterval(() => {

package/src/core/result.ts

@@ -72,21 +72,21 @@ export class Result<T = any> {
   /**
    * 获取结果数据
    */
-  get data(): T | undefined {
+  getData(): T | undefined {
     return this._data;
   }
   
   /**
    * 获取错误对象
    */
-  get error(): Error | undefined {
+  getError(): Error | undefined {
     return this._error;
   }
   
   /**
    * 获取元数据
    */
-  get meta(): Record<string, any> | undefined {
+  getMeta(): Record<string, any> | undefined {
     return this._meta;
   }
   

package/src/index.ts

@@ -10,7 +10,7 @@ import { IDCardModule } from './modules/id-card';
 import { QRCodeModule } from './modules/qrcode';
 import { FaceModule } from './modules/face';
 import { VERSION, BUILD_DATE } from './version';
-import { Logger, LogLevel } from './core/logger';
+import { Logger, LoggerLevel } from './core/logger';
 import { IDCardModuleOptions } from './modules/id-card/types';
 import { QRCodeModuleOptions } from './modules/qrcode/types';
 import { FaceModuleOptions } from './modules/face/types';
@@ -20,7 +20,7 @@ import { FaceModuleOptions } from './modules/face/types';
  */
 export interface IDScannerOptions {
   /** 日志级别 */
-  logLevel?: LogLevel;
+  logLevel?: LoggerLevel;
   /** 是否启用身份证识别模块 */
   enableIDCard?: boolean;
   /** 是否启用二维码识别模块 */
@@ -66,15 +66,15 @@ export class IDScanner {
     this.moduleManager = ModuleManager.getInstance();
     
     // 注册模块
-    if (options.enableIDCard !== false) {
+    if (options.enableIDCard === true) {
       this.moduleManager.register(new IDCardModule(options.idCard));
     }
     
-    if (options.enableQRCode !== false) {
+    if (options.enableQRCode === true) {
       this.moduleManager.register(new QRCodeModule(options.qrCode));
     }
     
-    if (options.enableFace !== false) {
+    if (options.enableFace === true) {
       this.moduleManager.register(new FaceModule(options.face));
     }
   }

package/src/modules/face/face-detector.ts

@@ -898,13 +898,14 @@ export class FaceDetector extends BaseScannerModule {
       if (typeof source === 'string' || source instanceof HTMLImageElement) {
         // 处理图片源
         const result = await this.processImage(source, { withEmbedding: true });
-        if (!result.isSuccess() || !result.data || result.data.length === 0) {
+        const resultData = result.getData();
+        if (!result.isSuccess() || !resultData || resultData.length === 0) {
           throw new FaceComparisonError('无法从源图像检测人脸');
         }
-        if (!result.data[0].embedding) {
+        if (!resultData[0].embedding) {
           throw new FaceComparisonError('源图像未提取特征向量');
         }
-        sourceEmbedding = result.data[0].embedding.vector;
+        sourceEmbedding = resultData[0].embedding.vector;
       } else {
         // 使用现有检测结果
         if (!source.embedding || !source.embedding.vector) {
@@ -919,13 +920,14 @@ export class FaceDetector extends BaseScannerModule {
       if (typeof target === 'string' || target instanceof HTMLImageElement) {
         // 处理图片源
         const result = await this.processImage(target, { withEmbedding: true });
-        if (!result.isSuccess() || !result.data || result.data.length === 0) {
+        const resultData = result.getData();
+        if (!result.isSuccess() || !resultData || resultData.length === 0) {
           throw new FaceComparisonError('无法从目标图像检测人脸');
         }
-        if (!result.data[0].embedding) {
+        if (!resultData[0].embedding) {
           throw new FaceComparisonError('目标图像未提取特征向量');
         }
-        targetEmbedding = result.data[0].embedding.vector;
+        targetEmbedding = resultData[0].embedding.vector;
       } else {
         // 使用现有检测结果
         if (!target.embedding || !target.embedding.vector) {

package/src/modules/face/liveness-detector.ts

@@ -227,13 +227,14 @@ export class LivenessDetector extends BaseScannerModule {
         withLandmarks: true,
         withAttributes: true
       });
+      const faceData = faceResult.getData();
       
-      if (!faceResult.isSuccess() || !faceResult.data || faceResult.data.length === 0) {
+      if (!faceResult.isSuccess() || !faceData || faceData.length === 0) {
         throw new LivenessDetectionError('未在图像中检测到人脸');
       }
       
       // 获取检测到的第一个人脸
-      const face = faceResult.data[0];
+      const face = faceData[0];
       
       // 执行被动式活体检测
       const livenessResult = this.performPassiveLivenessDetection(face);

package/src/modules/id-card/index.ts

@@ -129,21 +129,22 @@ export class IDCardModule extends BaseModule {
     try {
       // 检测身份证
       const detectionResult = await this.detector.processImage(image);
+      const detectionData = detectionResult.getData();
       
-      if (!detectionResult.isSuccess() || !detectionResult.data) {
+      if (!detectionResult.isSuccess() || !detectionData) {
         throw new Error('未检测到身份证');
       }
       
       // 创建结果对象
       const idCardInfo: IDCardInfo = {
-        type: detectionResult.data.type || IDCardType.FRONT,
-        confidence: detectionResult.data.confidence
+        type: detectionData.type || IDCardType.FRONT,
+        confidence: detectionData.confidence
       };
       
       // 如果启用OCR且OCR处理器已初始化
       if (this.options.detector?.enableOCR && this.ocrProcessor) {
         // 裁剪并处理图像
-        const processedImage = detectionResult.data.image || this.convertToImageData(image);
+        const processedImage = detectionData.image || this.convertToImageData(image);
         
         // 识别文本信息
         const ocrResult = await this.ocrProcessor.processIDCard(processedImage);
@@ -364,15 +365,16 @@ export class IDCardModule extends BaseModule {
       // 调用检测器处理图像
       const result = await this.detector.processImage(image);
       
-      if (!result.isSuccess() || !result.data) {
+      if (!result.isSuccess() || !result.getData()) {
         return { success: false, confidence: 0 };
       }
       
+      const data = result.getData()!;
       return { 
         success: true, 
-        type: result.data.type, 
-        confidence: result.data.confidence || 0,
-        croppedImage: result.data.image
+        type: data.type, 
+        confidence: data.confidence || 0,
+        croppedImage: data.image
       };
     } catch (error) {
       this.logger.error(this.name, '身份证检测失败', error instanceof Error ? error : new Error(String(error)));

package/src/utils/image-processing.ts

@@ -174,17 +174,20 @@ export class ImageProcessor {
       }
     }
 
-    // 处理边缘像素
-    for (let y = 0; y < height; y++) {
-      for (let x = 0; x < width; x++) {
-        if (y === 0 || y === height - 1 || x === 0 || x === width - 1) {
-          const pos = (y * width + x) * 4
-          outputData[pos] = data[pos]
-          outputData[pos + 1] = data[pos + 1]
-          outputData[pos + 2] = data[pos + 2]
-          outputData[pos + 3] = data[pos + 3]
-        }
-      }
+    // 处理边缘像素（仅遍历四条边，而非全图 O(width×height) → O(width+height)）
+    // 上边 + 下边
+    for (let x = 0; x < width; x++) {
+      const topPos = x * 4
+      const bottomPos = ((height - 1) * width + x) * 4
+      outputData[topPos] = data[topPos]; outputData[topPos + 1] = data[topPos + 1]; outputData[topPos + 2] = data[topPos + 2]; outputData[topPos + 3] = data[topPos + 3]
+      outputData[bottomPos] = data[bottomPos]; outputData[bottomPos + 1] = data[bottomPos + 1]; outputData[bottomPos + 2] = data[bottomPos + 2]; outputData[bottomPos + 3] = data[bottomPos + 3]
+    }
+    // 左边 + 右边（排除四角，它们已在上下一行处理）
+    for (let y = 1; y < height - 1; y++) {
+      const leftPos = y * width * 4
+      const rightPos = (y * width + width - 1) * 4
+      outputData[leftPos] = data[leftPos]; outputData[leftPos + 1] = data[leftPos + 1]; outputData[leftPos + 2] = data[leftPos + 2]; outputData[leftPos + 3] = data[leftPos + 3]
+      outputData[rightPos] = data[rightPos]; outputData[rightPos + 1] = data[rightPos + 1]; outputData[rightPos + 2] = data[rightPos + 2]; outputData[rightPos + 3] = data[rightPos + 3]
     }
 
     // 创建新的ImageData对象
@@ -199,19 +202,12 @@ export class ImageProcessor {
    * @returns 处理后的图像数据
    */
   static threshold(imageData: ImageData, threshold: number = 128): ImageData {
-    // 先转换为灰度图
-    const grayscaleImage = this.toGrayscale(
-      new ImageData(
-        new Uint8ClampedArray(imageData.data),
-        imageData.width,
-        imageData.height
-      )
-    )
+    // 先转换为灰度图（toGrayscale 内部已创建新 ImageData，无需外部拷贝）
+    const grayscaleImage = this.toGrayscale(imageData)
 
     const data = grayscaleImage.data
-    const length = data.length
 
-    for (let i = 0; i < length; i += 4) {
+    for (let i = 0; i < data.length; i += 4) {
       // 二值化处理
       const value = data[i] < threshold ? 0 : 255
       data[i] = data[i + 1] = data[i + 2] = value
@@ -227,14 +223,8 @@ export class ImageProcessor {
    * @returns 二值化后的图像数据
    */
   static toBinaryImage(imageData: ImageData): ImageData {
-    // 先转换为灰度图
-    const grayscaleImage = this.toGrayscale(
-      new ImageData(
-        new Uint8ClampedArray(imageData.data),
-        imageData.width,
-        imageData.height
-      )
-    )
+    // 先转换为灰度图（toGrayscale 内部已创建新 ImageData，无需外部拷贝）
+    const grayscaleImage = this.toGrayscale(imageData)
 
     // 使用OTSU算法自动确定阈值
     const threshold = this.getOtsuThreshold(grayscaleImage)
@@ -250,9 +240,10 @@ export class ImageProcessor {
    */
   private static getOtsuThreshold(imageData: ImageData): number {
     const data = imageData.data
-    const histogram = new Array(256).fill(0)
+    // 使用 Uint8Array 替代 Array<number>，避免 boxing 开销，提升直方图统计性能
+    const histogram = new Uint32Array(256)
 
-    // 统计灰度直方图
+    // 统计灰度直方图（每4字节取R通道，即灰度值）
     for (let i = 0; i < data.length; i += 4) {
       histogram[data[i]]++
     }