id-scanner-lib 1.3.3 → 1.6.2

package/src/types/tesseract.d.ts

@@ -2,36 +2,279 @@
  * Type definitions for tesseract.js
  */
 
-declare module 'tesseract.js' {
+declare module "tesseract.js" {
+  // Based on https://github.com/naptha/tesseract.js/blob/master/src/index.d.ts
+  // and https://github.com/naptha/tesseract.js/blob/master/docs/api.md
+
+  export interface Point {
+    x: number
+    y: number
+  }
+
+  export interface Bbox {
+    x0: number
+    y0: number
+    x1: number
+    y1: number
+  }
+
+  export interface Baseline {
+    x0: number
+    y0: number
+    x1: number
+    y1: number
+    has_descenders: boolean
+    has_ascenders: boolean
+  }
+
+  export interface Word {
+    symbols: Symbol[]
+    choices: Choice[]
+    text: string
+    confidence: number
+    baseline: Baseline
+    bbox: Bbox
+    is_numeric: boolean
+    in_dictionary: boolean
+    direction: string
+    language: string
+    is_from_dictionary: boolean
+    is_fuzzy: boolean
+    is_certain: boolean
+    is_bold: boolean
+    is_italic: boolean
+    is_underlined: boolean
+    is_monospace: boolean
+    is_serif: boolean
+    is_smallcaps: boolean
+    font_id: number
+    font_size: number
+    font_name: string
+  }
+
+  export interface Symbol {
+    choices: Choice[]
+    image: null | HTMLImageElement // Or string if it's a path/URL
+    text: string
+    confidence: number
+    baseline: Baseline
+    bbox: Bbox
+    is_superscript: boolean
+    is_subscript: boolean
+    is_dropcap: boolean
+  }
+
+  export interface Choice {
+    text: string
+    confidence: number
+  }
+
+  export interface Line {
+    words: Word[]
+    text: string
+    confidence: number
+    baseline: Baseline
+    bbox: Bbox
+  }
+
+  export interface Paragraph {
+    lines: Line[]
+    text: string
+    confidence: number
+    baseline: Baseline
+    bbox: Bbox
+    is_ltr: boolean
+  }
+
+  export interface Block {
+    paragraphs: Paragraph[]
+    lines: Line[]
+    words: Word[]
+    text: string
+    confidence: number
+    baseline: Baseline
+    bbox: Bbox
+    blocktype: string
+    polygon: Point[]
+  }
+
+  export interface Page {
+    blocks: Block[]
+    confidence: number
+    html: string // HTML representation of the page
+    jobId?: string
+    text: string
+    lines: Line[]
+    oem: string
+    operator: string
+    paragraphs: Paragraph[]
+    psm: string
+    symbols: Symbol[]
+    version: string
+    words: Word[]
+    hocr?: string // hOCR output
+    tsv?: string // TSV output
+  }
+
+  export interface LoggerMessage {
+    jobId?: string
+    workerId?: string
+    status: string
+    progress: number
+    userfriendlyText?: string
+  }
+
   export interface WorkerOptions {
-    langPath?: string;
-    corePath?: string;
-    workerPath?: string;
-    logger?: (message: any) => void;
-    errorHandler?: (error: Error) => void;
+    langPath?: string
+    corePath?: string
+    workerPath?: string
+    logger?: (message: LoggerMessage) => void // More specific type for logger message <mcreference index="1" link="https://github.com/naptha/tesseract.js/blob/master/docs/api.md"></mcreference>
+    errorHandler?: (error: Error) => void
+    // Add other options based on documentation if needed
+    [key: string]: any // For other less common or dynamic options
   }
 
   export interface RecognizeResult {
+    data: Page // Use the detailed Page interface
+  }
+
+  export interface DetectResult {
     data: {
-      text: string;
-      hocr: string;
-      tsv: string;
-      confidence: number;
-      blocks: any[];
-      lines: any[];
-      words: any[];
-      symbols: any[];
-    };
+      tesseract_script_id: number | null
+      script: string | null
+      script_confidence: number | null
+      orientation_degrees: number | null
+      orientation_confidence: number | null
+    }
+    jobId?: string
+  }
+
+  export interface ConfigResult {
+    data: null
+    jobId?: string
   }
 
+  export type ImageLike =
+    | HTMLImageElement
+    | HTMLCanvasElement
+    | File
+    | string
+    | Buffer
+    | ImageData // Common image types
+
   export interface Worker {
-    load(): Promise<any>;
-    loadLanguage(lang: string): Promise<any>;
-    initialize(lang: string): Promise<any>;
-    setParameters(params: Record<string, any>): Promise<any>;
-    recognize(image: HTMLCanvasElement | ImageData | Buffer | string): Promise<RecognizeResult>;
-    terminate(): Promise<any>;
+    load(jobId?: string): Promise<ConfigResult> // <mcreference index="4" link="https://github.com/naptha/tesseract.js/blob/master/src/index.d.ts"></mcreference>
+    loadLanguage(
+      langs?: string | string[],
+      jobId?: string
+    ): Promise<ConfigResult> // <mcreference index="4" link="https://github.com/naptha/tesseract.js/blob/master/src/index.d.ts"></mcreference>
+    initialize(
+      langs?: string | string[],
+      oem?: OEM,
+      config?: string | Partial<InitOptions>,
+      jobId?: string
+    ): Promise<ConfigResult> // <mcreference index="4" link="https://github.com/naptha/tesseract.js/blob/master/src/index.d.ts"></mcreference>
+    setParameters(
+      params: Partial<Parameters>,
+      jobId?: string
+    ): Promise<ConfigResult> // <mcreference index="4" link="https://github.com/naptha/tesseract.js/blob/master/src/index.d.ts"></mcreference>
+    recognize(
+      image: ImageLike,
+      options?: Partial<RecognizeOptions>,
+      output?: Partial<OutputFormats>,
+      jobId?: string
+    ): Promise<RecognizeResult> // <mcreference index="4" link="https://github.com/naptha/tesseract.js/blob/master/src/index.d.ts"></mcreference>
+    detect(
+      image: ImageLike,
+      options?: Partial<WorkerOptions>,
+      jobId?: string
+    ): Promise<DetectResult> // <mcreference index="4" link="https://github.com/naptha/tesseract.js/blob/master/src/index.d.ts"></mcreference>
+    terminate(jobId?: string): Promise<ConfigResult> // <mcreference index="4" link="https://github.com/naptha/tesseract.js/blob/master/src/index.d.ts"></mcreference>
+    // Add other worker methods if present in the version you are targeting
+    // Example from docs for other methods like FS operations:
+    writeText?(
+      path: string,
+      text: string,
+      jobId?: string
+    ): Promise<ConfigResult>
+    readText?(path: string, jobId?: string): Promise<ConfigResult>
+    removeFile?(path: string, jobId?: string): Promise<ConfigResult> // Assuming removeFile also returns ConfigResult or similar
+    FS?(method: string, args: any[], jobId?: string): Promise<any> // FS is more generic
+  }
+
+  // Based on Tesseract's OEM and PSM enums
+  export enum OEM {
+    TESSERACT_ONLY = 0,
+    LSTM_ONLY = 1,
+    TESSERACT_LSTM_COMBINED = 2,
+    DEFAULT = 3,
+  }
+
+  export enum PSM {
+    OSD_ONLY = 0,
+    AUTO_OSD = 1,
+    AUTO_ONLY = 2,
+    AUTO = 3,
+    SINGLE_COLUMN = 4,
+    SINGLE_BLOCK_VERT_TEXT = 5,
+    SINGLE_BLOCK = 6,
+    SINGLE_LINE = 7,
+    SINGLE_WORD = 8,
+    CIRCLE_WORD = 9,
+    SINGLE_CHAR = 10,
+    SPARSE_TEXT = 11,
+    SPARSE_TEXT_OSD = 12,
+    RAW_LINE = 13,
+  }
+
+  export interface Parameters {
+    tessedit_char_whitelist?: string
+    tessedit_pageseg_mode?: PSM
+    // Add other Tesseract parameters as needed
+    [key: string]: any // For flexibility with other parameters
+  }
+
+  export interface RecognizeOptions {
+    rectangle?: Bbox // For recognizing a specific region
+    rectangles?: Bbox[] // For recognizing multiple regions
+    // Add other recognize specific options
+    [key: string]: any
   }
 
-  export function createWorker(options?: WorkerOptions): Worker;
+  export interface OutputFormats {
+    text?: boolean
+    blocks?: boolean
+    hocr?: boolean
+    tsv?: boolean
+    pdf?: boolean // If PDF output is supported
+    // Add other output formats
+    [key: string]: any
+  }
+
+  export interface InitOptions {
+    load_system_dawg?: boolean
+    load_freq_dawg?: boolean
+    load_punc_dawg?: boolean
+    load_number_dawg?: boolean
+    load_unambig_dawg?: boolean
+    load_bigram_dawg?: boolean
+    load_fixed_length_dawgs?: boolean
+    // Add other init-only parameters
+    [key: string]: any
+  }
+
+  export function createWorker(options?: Partial<WorkerOptions>): Worker // 修正返回类型为 Worker 而非 Promise<Worker>
+  export function setLogging(logging: boolean): void
+  export function recognize(
+    image: ImageLike,
+    langs?: string | string[],
+    options?: Partial<RecognizeOptions & WorkerOptions>
+  ): Promise<RecognizeResult>
+  export function detect(
+    image: ImageLike,
+    options?: Partial<WorkerOptions>
+  ): Promise<DetectResult>
+
+  // 正确导出 OEM 和 PSM 枚举
+  export { OEM, PSM }
 }

package/src/utils/camera.test.ts

@@ -0,0 +1,30 @@
+/**
+ * @file 摄像头工具测试
+ * @description 测试摄像头相关工具
+ */
+
+import { getMediaConstraints } from './index';
+
+describe('Camera Utils', () => {
+  describe('getMediaConstraints', () => {
+    it('should return default constraints', () => {
+      const constraints = getMediaConstraints();
+      
+      expect(constraints).toBeDefined();
+      expect(constraints.audio).toBe(false);
+      expect(constraints.video).toBeDefined();
+    });
+
+    it('should accept custom parameters', () => {
+      const constraints = getMediaConstraints(1920, 1080, 'user', 60);
+      
+      expect(constraints.video).toBeDefined();
+    });
+
+    it('should handle partial parameters', () => {
+      const constraints = getMediaConstraints(640);
+      
+      expect(constraints.video).toBeDefined();
+    });
+  });
+});

package/src/utils/camera.ts

@@ -4,6 +4,8 @@
  * @module Camera
  */
 
+import { Logger } from '../core/logger';
+
 /**
  * 相机配置选项接口
  * 
@@ -113,7 +115,8 @@ export class Camera {
         });
       }
     } catch (error) {
-      console.error('无法访问摄像头:', error);
+      const logger = Logger.getInstance();
+      logger.error('Camera', '无法访问摄像头', error instanceof Error ? error : undefined);
       throw new Error('无法访问摄像头。请确保已授予摄像头访问权限，并且摄像头未被其他应用程序占用。');
     }
   }

package/src/utils/error-handler.test.ts

@@ -0,0 +1,137 @@
+/**
+ * @file 错误处理工具测试
+ * @description 测试 ErrorHandler
+ */
+
+import { ErrorHandler, ErrorSeverity } from './error-handler';
+
+describe('ErrorHandler', () => {
+  // Mock Logger
+  const mockLogger = {
+    debug: jest.fn(),
+    info: jest.fn(),
+    warn: jest.fn(),
+    error: jest.fn()
+  };
+
+  beforeAll(() => {
+    // Replace logger with mock
+    (ErrorHandler as any).logger = mockLogger;
+  });
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it('should handle error with ERROR severity', () => {
+    ErrorHandler.handle('TestModule', 'Test error', new Error('test error'));
+    
+    expect(mockLogger.error).toHaveBeenCalledWith(
+      'TestModule',
+      'Test error',
+      expect.any(Error)
+    );
+  });
+
+  it('should handle error with WARN severity', () => {
+    ErrorHandler.handle('TestModule', 'Warning message', null, ErrorSeverity.WARN);
+    
+    expect(mockLogger.warn).toHaveBeenCalledWith(
+      'TestModule',
+      'Warning message',
+      undefined
+    );
+  });
+
+  it('should handle error with INFO severity', () => {
+    ErrorHandler.handle('TestModule', 'Info message', null, ErrorSeverity.INFO);
+    
+    expect(mockLogger.info).toHaveBeenCalledWith(
+      'TestModule',
+      'Info message',
+      undefined
+    );
+  });
+
+  it('should handle error with DEBUG severity', () => {
+    ErrorHandler.handle('TestModule', 'Debug message', null, ErrorSeverity.DEBUG);
+    
+    expect(mockLogger.debug).toHaveBeenCalledWith(
+      'TestModule',
+      'Debug message',
+      undefined
+    );
+  });
+
+  it('should convert string error to Error object', () => {
+    ErrorHandler.handle('TestModule', 'Test error', 'string error');
+    
+    expect(mockLogger.error).toHaveBeenCalledWith(
+      'TestModule',
+      'Test error',
+      expect.any(Error)
+    );
+  });
+
+  it('should convert unknown error to Error object', () => {
+    ErrorHandler.handle('TestModule', 'Test error', { code: 123 });
+    
+    expect(mockLogger.error).toHaveBeenCalledWith(
+      'TestModule',
+      'Test error',
+      expect.any(Error)
+    );
+  });
+
+  describe('asyncHandler', () => {
+    it('should create error handler function', () => {
+      const handler = ErrorHandler.asyncHandler('TestModule', 'Operation failed');
+      
+      handler(new Error('test'));
+      
+      expect(mockLogger.error).toHaveBeenCalledWith(
+        'TestModule',
+        'Operation failed',
+        expect.any(Error)
+      );
+    });
+  });
+
+  describe('safeExecute', () => {
+    it('should return result on success', async () => {
+      const fn = async () => 'success';
+      const result = await ErrorHandler.safeExecute(fn, 'TestModule', 'fallback');
+      
+      expect(result).toBe('success');
+    });
+
+    it('should return fallback on error', async () => {
+      const fn = async () => {
+        throw new Error('error');
+      };
+      const result = await ErrorHandler.safeExecute(fn, 'TestModule', 'fallback');
+      
+      expect(result).toBe('fallback');
+      expect(mockLogger.error).toHaveBeenCalled();
+    });
+  });
+
+  describe('safeExecuteSync', () => {
+    it('should return result on success', () => {
+      const fn = () => 'success';
+      const result = ErrorHandler.safeExecuteSync(fn, 'TestModule', 'fallback');
+      
+      expect(result).toBe('success');
+    });
+
+    it('should return fallback on error', () => {
+      const fn = () => {
+        throw new Error('error');
+      };
+      const result = ErrorHandler.safeExecuteSync(fn, 'TestModule', 'fallback');
+      
+      expect(result).toBe('fallback');
+      expect(mockLogger.error).toHaveBeenCalled();
+    });
+  });
+});

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