taro-bluetooth-print 2.2.1 → 2.3.1

package/src/encoding/gbk-table.ts

@@ -1,98 +1,120 @@
 /**
- * GBK Encoding Table
+ * GBK Encoding Table - 懒加载版本
  *
- * This module provides character mapping tables for GBK, GB2312, and Big5 encodings.
- * GBK is a superset of GB2312 and covers most Chinese characters used in simplified Chinese.
- * Big5 is used for traditional Chinese characters.
+ * 优化策略：
+ * 1. 默认使用精简版编码表 (gbk-lite.ts，约 3500 常用字)
+ * 2. 遇到非常用字时动态加载完整编码表
+ * 3. 二分查找代替 Map，大幅减少内存占用
  *
- * GBK encoding uses double-byte encoding for Chinese characters:
- * - First byte: 0x81-0xFE
- * - Second byte: 0x40-0xFE (excluding 0x7F)
- *
- * 映射数据存储在 gbk-data.ts 中，运行时解码为 Map。
  * GBK: 23940 个字符映射
  * Big5: 13911 个字符映射
  */
 
-import { GBK_DATA, BIG5_DATA } from './gbk-data';
+import { binarySearchGbk, isInCommonRange } from './gbk-lite';
 
-/**
- * Unicode to GBK mapping table
- * Maps Unicode code points to GBK byte pairs
- */
+// 懒加载完整编码数据
+let GBK_DATA: number[] | null = null;
+let BIG5_DATA: number[] | null = null;
+
+function loadFullData() {
+  if (!GBK_DATA) {
+    const data = require('./gbk-data');
+    GBK_DATA = data.GBK_DATA;
+    BIG5_DATA = data.BIG5_DATA;
+  }
+  return { GBK_DATA: GBK_DATA!, BIG5_DATA: BIG5_DATA! };
+}
+
+// Unicode to GBK mapping table
 export const unicodeToGbk: Map<number, number> = new Map();
 
-/**
- * GBK to Unicode mapping table
- * Maps GBK byte pairs to Unicode code points
- */
+// GBK to Unicode mapping table  
 export const gbkToUnicode: Map<number, number> = new Map();
 
-/**
- * Unicode to Big5 mapping table
- */
+// Unicode to Big5 mapping table
 export const unicodeToBig5: Map<number, number> = new Map();
 
-/**
- * Big5 to Unicode mapping table
- */
+// Big5 to Unicode mapping table
 export const big5ToUnicode: Map<number, number> = new Map();
 
-/**
- * Decode flat array mapping data into forward and reverse maps.
- * Array format: [unicode1, encoded1, unicode2, encoded2, ...]
- */
-function decodeMappings(
-  data: number[],
-  forwardMap: Map<number, number>,
-  reverseMap: Map<number, number>
-): void {
-  for (let i = 0; i < data.length; i += 2) {
-    const unicode = data[i]!;
-    const encoded = data[i + 1]!;
-    forwardMap.set(unicode, encoded);
-    reverseMap.set(encoded, unicode);
-  }
-}
-
-// Initialize mappings at module load time
-decodeMappings(GBK_DATA, unicodeToGbk, gbkToUnicode);
-decodeMappings(BIG5_DATA, unicodeToBig5, big5ToUnicode);
-
 /**
  * Get GBK bytes for a Unicode character
- * @param unicode - Unicode code point
- * @returns GBK byte pair [high, low] or null if not found
+ * 先查精简表，查不到再懒加载完整表
  */
 export function getGbkBytes(unicode: number): [number, number] | null {
-  const gbk = unicodeToGbk.get(unicode);
-  if (gbk !== undefined) {
+  // ASCII 直接返回
+  if (unicode >= 0x20 && unicode <= 0x7E) {
+    return [0, unicode];
+  }
+  
+  // 先查精简表
+  const gbk = binarySearchGbk(unicode);
+  if (gbk !== null) {
     return [(gbk >> 8) & 0xff, gbk & 0xff];
   }
+  
+  // 非常用字，懒加载完整表
+  if (isInCommonRange(unicode)) {
+    const { GBK_DATA } = loadFullData();
+    for (let i = 0; i < GBK_DATA.length; i += 2) {
+      if (GBK_DATA[i] === unicode) {
+        const gbkValue = GBK_DATA[i + 1];
+        if (gbkValue !== undefined) {
+          return [(gbkValue >> 8) & 0xff, gbkValue & 0xff];
+        }
+      }
+    }
+  }
+  
   return null;
 }
 
 /**
  * Get Unicode character from GBK bytes
- * @param high - High byte
- * @param low - Low byte
- * @returns Unicode code point or null if not found
+ * 懒加载完整表
  */
 export function getUnicodeFromGbk(high: number, low: number): number | null {
   const gbk = (high << 8) | low;
-  return gbkToUnicode.get(gbk) ?? null;
+  
+  // 先查缓存
+  const cached = gbkToUnicode.get(gbk);
+  if (cached !== undefined) return cached;
+  
+  // 懒加载完整表
+  const { GBK_DATA } = loadFullData();
+  for (let i = 0; i < GBK_DATA.length; i += 2) {
+    if (GBK_DATA[i + 1] === gbk) {
+      const result = GBK_DATA[i];
+      return result ?? null;
+    }
+  }
+  
+  return null;
 }
 
 /**
  * Get Big5 bytes for a Unicode character
- * @param unicode - Unicode code point
- * @returns Big5 byte pair or null if not found
+ * 懒加载完整表
  */
 export function getBig5Bytes(unicode: number): [number, number] | null {
-  const big5 = unicodeToBig5.get(unicode);
-  if (big5 !== undefined) {
-    return [(big5 >> 8) & 0xff, big5 & 0xff];
+  // 先查缓存
+  const cached = unicodeToBig5.get(unicode);
+  if (cached !== undefined) {
+    const cachedValue = cached;
+    return [(cachedValue >> 8) & 0xff, cachedValue & 0xff];
+  }
+  
+  // 懒加载完整表
+  const { BIG5_DATA } = loadFullData();
+  for (let i = 0; i < BIG5_DATA.length; i += 2) {
+    if (BIG5_DATA[i] === unicode) {
+      const big5 = BIG5_DATA[i + 1];
+      if (big5 !== undefined) {
+        return [(big5 >> 8) & 0xff, big5 & 0xff];
+      }
+    }
   }
+  
   return null;
 }
 

package/src/index.ts

@@ -1,6 +1,6 @@
 /**
  * Taro Bluetooth Print Library
- * A lightweight, high-performance Bluetooth printing library for Taro
+ * 轻量级、高性能的蓝牙打印库
  *
  * @packageDocumentation
  */
@@ -10,28 +10,27 @@ export { BluetoothPrinter } from './core/BluetoothPrinter';
 export type { PrinterEvents } from './core/BluetoothPrinter';
 export { EventEmitter } from './core/EventEmitter';
 
-// Drivers
-export { EscPos } from './drivers/EscPos';
+// Drivers - 打印机驱动
+export * from './drivers';
 
-// Adapters
+// Adapters - 平台适配器
 export { TaroAdapter } from './adapters/TaroAdapter';
+export { AlipayAdapter } from './adapters/AlipayAdapter';
+export { BaiduAdapter } from './adapters/BaiduAdapter';
+export { ByteDanceAdapter } from './adapters/ByteDanceAdapter';
+export { WebBluetoothAdapter } from './adapters/WebBluetoothAdapter';
 export { AdapterFactory } from './adapters/AdapterFactory';
 export { BaseAdapter } from './adapters/BaseAdapter';
-export { WebBluetoothAdapter } from './adapters/WebBluetoothAdapter';
 export type { WebBluetoothRequestOptions } from './adapters/WebBluetoothAdapter';
 
-// Services
-export { ConnectionManager } from './services/ConnectionManager';
-export type {
-  ConnectionManagerConfig,
-  ConnectionManagerEvents,
-} from './services/ConnectionManager';
+// Services - 服务层
+export * from './services';
 
-// Device Management
+// Device Management - 设备管理
 export { DeviceManager } from './device/DeviceManager';
 export type { BluetoothDevice, ScanOptions, DeviceManagerEvents } from './device/DeviceManager';
 
-// Print Queue
+// Print Queue - 打印队列
 export { PrintQueue } from './queue/PrintQueue';
 export type {
   PrintJob,
@@ -41,11 +40,11 @@ export type {
   PrintQueueEvents,
 } from './queue/PrintQueue';
 
-// Offline Cache
+// Offline Cache - 离线缓存
 export { OfflineCache } from './cache/OfflineCache';
 export type { CachedJob, CacheConfig, CacheStats } from './cache/OfflineCache';
 
-// Template Engine
+// Template Engine - 模板引擎
 export { TemplateEngine } from './template/TemplateEngine';
 export type {
   TemplateType,
@@ -56,32 +55,32 @@ export type {
   ValidationResult,
 } from './template/TemplateEngine';
 
-// Barcode Generator
+// Barcode Generator - 条码生成
 export { BarcodeGenerator, BarcodeFormat } from './barcode/BarcodeGenerator';
 export type { BarcodeOptions } from './barcode/BarcodeGenerator';
 
-// Text Formatter
+// Text Formatter - 文本格式化
 export { TextFormatter, TextAlign } from './formatter/TextFormatter';
 export type { TextStyle } from './formatter/TextFormatter';
 
-// Preview Renderer
+// Preview Renderer - 打印预览
 export { PreviewRenderer } from './preview/PreviewRenderer';
 export type { PreviewOptions, PreviewResult } from './preview/PreviewRenderer';
 
-// Encoding Service
+// Encoding - 编码服务
 export { EncodingService } from './encoding/EncodingService';
 export type { EncodingConfig } from './encoding/EncodingService';
 
-// Utilities
+// Utilities - 工具函数
 export { Logger, LogLevel } from './utils/logger';
 export { Encoding } from './utils/encoding';
 export { ImageProcessing } from './utils/image';
 export { PlatformType, detectPlatform, isPlatformSupported } from './utils/platform';
 
-// Error handling
+// Error handling - 错误处理
 export { BluetoothPrintError, ErrorCode } from './errors/BluetoothError';
 
-// Configuration
+// Configuration - 配置
 export { DEFAULT_CONFIG, mergeConfig } from './config/PrinterConfig';
 export type {
   PrinterConfig,
@@ -90,5 +89,10 @@ export type {
   LoggingConfig,
 } from './config/PrinterConfig';
 
-// Types
+// Plugin System - 插件系统
+export { PluginManager } from './plugins/PluginManager';
+export { createLoggingPlugin, createRetryPlugin } from './plugins';
+export type { Plugin, PluginHooks, PluginOptions, PluginFactory } from './plugins/types';
+
+// Types - 类型定义
 export * from './types';

package/src/plugins/PluginManager.ts

@@ -0,0 +1,195 @@
+/**
+ * Plugin Manager
+ * Manages plugin lifecycle and hook execution
+ */
+
+import { Plugin, PluginHooks, PluginOptions } from './types';
+import { BluetoothPrintError, ErrorCode } from '@/errors/BluetoothError';
+import { PrinterState } from '@/types';
+import { Logger } from '@/utils/logger';
+
+/**
+ * Manages plugins for BluetoothPrinter
+ */
+export class PluginManager {
+  private plugins: Map<string, Plugin> = new Map();
+  private readonly logger = Logger.scope('PluginManager');
+
+  /**
+   * Register a plugin
+   * @param plugin - Plugin to register
+   * @param options - Plugin options
+   * @throws {BluetoothPrintError} If plugin with same name already exists
+   */
+  async register(plugin: Plugin, options?: PluginOptions): Promise<void> {
+    if (this.plugins.has(plugin.name)) {
+      throw new BluetoothPrintError(
+        ErrorCode.INVALID_CONFIGURATION,
+        `Plugin "${plugin.name}" is already registered`
+      );
+    }
+
+    this.logger.info(
+      `Registering plugin: ${plugin.name}${plugin.version ? ` v${plugin.version}` : ''}`
+    );
+
+    if (plugin.init) {
+      await plugin.init(options);
+    }
+
+    this.plugins.set(plugin.name, plugin);
+    this.logger.debug(`Plugin registered: ${plugin.name}`);
+  }
+
+  /**
+   * Unregister a plugin
+   * @param name - Plugin name to unregister
+   */
+  async unregister(name: string): Promise<void> {
+    const plugin = this.plugins.get(name);
+    if (!plugin) {
+      this.logger.warn(`Plugin not found: ${name}`);
+      return;
+    }
+
+    if (plugin.destroy) {
+      await plugin.destroy();
+    }
+
+    this.plugins.delete(name);
+    this.logger.info(`Plugin unregistered: ${name}`);
+  }
+
+  /**
+   * Get a registered plugin
+   * @param name - Plugin name
+   * @returns Plugin instance or undefined
+   */
+  get(name: string): Plugin | undefined {
+    return this.plugins.get(name);
+  }
+
+  /**
+   * Get all registered plugin names
+   * @returns Array of plugin names
+   */
+  getNames(): string[] {
+    return Array.from(this.plugins.keys());
+  }
+
+  /**
+   * Check if a plugin is registered
+   * @param name - Plugin name
+   * @returns True if registered
+   */
+  has(name: string): boolean {
+    return this.plugins.has(name);
+  }
+
+  /**
+   * Execute a hook across all plugins
+   * @param hookName - Name of the hook to execute
+   * @param args - Arguments to pass to the hook
+   * @returns Result from hooks (last non-void result)
+   */
+  async executeHook<K extends keyof PluginHooks>(
+    hookName: K,
+    ...args: Parameters<NonNullable<PluginHooks[K]>>
+  ): Promise<unknown> {
+    let result: unknown = undefined;
+
+    for (const [name, plugin] of this.plugins) {
+      const hook = plugin.hooks[hookName];
+      if (hook) {
+        try {
+          // @ts-expect-error - TypeScript can't infer the correct types here
+          const hookResult = await hook(...args);
+          if (hookResult !== undefined) {
+            result = hookResult;
+          }
+        } catch (error) {
+          this.logger.error(`Plugin "${name}" hook "${hookName}" failed:`, error);
+          // Continue to next plugin
+        }
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Execute beforeConnect hooks
+   */
+  async beforeConnect(deviceId: string): Promise<string> {
+    const result = await this.executeHook('beforeConnect', deviceId);
+    return (result as string) || deviceId;
+  }
+
+  /**
+   * Execute afterConnect hooks
+   */
+  async afterConnect(deviceId: string): Promise<void> {
+    await this.executeHook('afterConnect', deviceId);
+  }
+
+  /**
+   * Execute beforeDisconnect hooks
+   */
+  async beforeDisconnect(deviceId: string): Promise<void> {
+    await this.executeHook('beforeDisconnect', deviceId);
+  }
+
+  /**
+   * Execute afterDisconnect hooks
+   */
+  async afterDisconnect(deviceId: string): Promise<void> {
+    await this.executeHook('afterDisconnect', deviceId);
+  }
+
+  /**
+   * Execute beforePrint hooks
+   */
+  async beforePrint(buffer: Uint8Array): Promise<Uint8Array> {
+    const result = await this.executeHook('beforePrint', buffer);
+    return (result as Uint8Array) || buffer;
+  }
+
+  /**
+   * Execute afterPrint hooks
+   */
+  async afterPrint(bytesSent: number): Promise<void> {
+    await this.executeHook('afterPrint', bytesSent);
+  }
+
+  /**
+   * Execute onError hooks
+   * @returns True if error should be suppressed
+   */
+  async onError(error: BluetoothPrintError): Promise<boolean> {
+    const result = await this.executeHook('onError', error);
+    return result === true;
+  }
+
+  /**
+   * Execute onStateChange hooks
+   */
+  async onStateChange(state: PrinterState, previousState: PrinterState): Promise<void> {
+    await this.executeHook('onStateChange', state, previousState);
+  }
+
+  /**
+   * Execute onProgress hooks
+   */
+  async onProgress(sent: number, total: number): Promise<void> {
+    await this.executeHook('onProgress', sent, total);
+  }
+
+  /**
+   * Clear all plugins
+   */
+  async clear(): Promise<void> {
+    for (const name of this.plugins.keys()) {
+      await this.unregister(name);
+    }
+  }
+}

package/src/plugins/builtin/LoggingPlugin.ts

@@ -0,0 +1,99 @@
+/**
+ * Logging Plugin
+ * Provides detailed logging for printer operations
+ */
+
+import { Plugin, PluginFactory, PluginOptions } from '../types';
+import { Logger, LogLevel } from '@/utils/logger';
+
+export interface LoggingPluginOptions extends PluginOptions {
+  /** Log level (default: DEBUG) */
+  level?: LogLevel;
+  /** Include timestamps (default: true) */
+  timestamps?: boolean;
+  /** Log progress updates (default: false, can be noisy) */
+  logProgress?: boolean;
+}
+
+/**
+ * Creates a logging plugin instance
+ */
+export const createLoggingPlugin: PluginFactory = (options?: LoggingPluginOptions): Plugin => {
+  const opts: Required<LoggingPluginOptions> = {
+    level: options?.level ?? LogLevel.DEBUG,
+    timestamps: options?.timestamps ?? true,
+    logProgress: options?.logProgress ?? false,
+  };
+
+  const logger = Logger.scope('PrinterLog');
+  let startTime: number;
+
+  const formatTime = (): string => {
+    if (!opts.timestamps) return '';
+    return `[${new Date().toISOString()}] `;
+  };
+
+  return {
+    name: 'logging',
+    version: '1.0.0',
+    description: 'Detailed logging for printer operations',
+
+    hooks: {
+      beforeConnect: (deviceId: string) => {
+        startTime = Date.now();
+        logger.info(`${formatTime()}Connecting to device: ${deviceId}`);
+      },
+
+      afterConnect: (deviceId: string) => {
+        const elapsed = Date.now() - startTime;
+        logger.info(`${formatTime()}Connected to ${deviceId} (${elapsed}ms)`);
+      },
+
+      beforeDisconnect: (deviceId: string) => {
+        logger.info(`${formatTime()}Disconnecting from: ${deviceId}`);
+      },
+
+      afterDisconnect: (deviceId: string) => {
+        logger.info(`${formatTime()}Disconnected from: ${deviceId}`);
+      },
+
+      beforePrint: (buffer: Uint8Array) => {
+        startTime = Date.now();
+        logger.info(`${formatTime()}Starting print job: ${buffer.length} bytes`);
+      },
+
+      afterPrint: (bytesSent: number) => {
+        const elapsed = Date.now() - startTime;
+        const speed = ((bytesSent / elapsed) * 1000).toFixed(2);
+        logger.info(
+          `${formatTime()}Print complete: ${bytesSent} bytes in ${elapsed}ms (${speed} B/s)`
+        );
+      },
+
+      onError: error => {
+        logger.error(`${formatTime()}Error [${error.code}]: ${error.message}`);
+        return false; // Don't suppress the error
+      },
+
+      onStateChange: (state, previousState) => {
+        logger.debug(`${formatTime()}State: ${previousState} → ${state}`);
+      },
+
+      onProgress: (sent, total) => {
+        if (opts.logProgress) {
+          const percent = ((sent / total) * 100).toFixed(1);
+          logger.debug(`${formatTime()}Progress: ${sent}/${total} (${percent}%)`);
+        }
+      },
+    },
+
+    init: () => {
+      Logger.setLevel(opts.level);
+      logger.info('Logging plugin initialized');
+    },
+
+    destroy: () => {
+      logger.info('Logging plugin destroyed');
+    },
+  };
+};

package/src/plugins/builtin/RetryPlugin.ts

@@ -0,0 +1,103 @@
+/**
+ * Retry Plugin
+ * Provides automatic retry with exponential backoff for failed operations
+ */
+
+import { Plugin, PluginFactory, PluginOptions } from '../types';
+import { Logger } from '@/utils/logger';
+import { BluetoothPrintError, ErrorCode } from '@/errors/BluetoothError';
+
+export interface RetryPluginOptions extends PluginOptions {
+  /** Maximum retry attempts (default: 3) */
+  maxRetries?: number;
+  /** Initial delay in ms (default: 1000) */
+  initialDelay?: number;
+  /** Maximum delay in ms (default: 10000) */
+  maxDelay?: number;
+  /** Backoff multiplier (default: 2) */
+  backoffMultiplier?: number;
+  /** Error codes that should trigger retry */
+  retryableErrors?: ErrorCode[];
+}
+
+/**
+ * Creates a retry plugin instance
+ */
+export const createRetryPlugin: PluginFactory = (options?: RetryPluginOptions): Plugin => {
+  const opts: Required<RetryPluginOptions> = {
+    maxRetries: options?.maxRetries ?? 3,
+    initialDelay: options?.initialDelay ?? 1000,
+    maxDelay: options?.maxDelay ?? 10000,
+    backoffMultiplier: options?.backoffMultiplier ?? 2,
+    retryableErrors: options?.retryableErrors ?? [
+      ErrorCode.CONNECTION_FAILED,
+      ErrorCode.CONNECTION_TIMEOUT,
+      ErrorCode.WRITE_FAILED,
+      ErrorCode.WRITE_TIMEOUT,
+    ],
+  };
+
+  const logger = Logger.scope('RetryPlugin');
+  let retryCount = 0;
+  let currentDelay = opts.initialDelay;
+
+  const shouldRetry = (error: BluetoothPrintError): boolean => {
+    return retryCount < opts.maxRetries && opts.retryableErrors.includes(error.code);
+  };
+
+  const sleep = (ms: number): Promise<void> => {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  };
+
+  return {
+    name: 'retry',
+    version: '1.0.0',
+    description: 'Automatic retry with exponential backoff',
+
+    hooks: {
+      beforeConnect: () => {
+        // Reset retry state on new connection attempt
+        retryCount = 0;
+        currentDelay = opts.initialDelay;
+      },
+
+      beforePrint: () => {
+        // Reset retry state on new print job
+        retryCount = 0;
+        currentDelay = opts.initialDelay;
+      },
+
+      onError: async (error: BluetoothPrintError) => {
+        if (shouldRetry(error)) {
+          retryCount++;
+          logger.warn(
+            `Retryable error occurred (attempt ${retryCount}/${opts.maxRetries}): ${error.code}`
+          );
+          logger.info(`Waiting ${currentDelay}ms before retry...`);
+
+          await sleep(currentDelay);
+
+          // Exponential backoff
+          currentDelay = Math.min(currentDelay * opts.backoffMultiplier, opts.maxDelay);
+
+          // Note: Returning false means error is not suppressed
+          // The actual retry logic would need to be implemented in the printer
+          // This plugin mainly provides the delay and logging
+          return false;
+        }
+
+        if (retryCount > 0) {
+          logger.error(`Failed after ${retryCount} retries: ${error.code} - ${error.message}`);
+        }
+
+        return false;
+      },
+    },
+
+    init: () => {
+      logger.info(
+        `Retry plugin initialized (max: ${opts.maxRetries}, delay: ${opts.initialDelay}ms)`
+      );
+    },
+  };
+};

package/src/plugins/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Plugin System Exports
+ */
+
+export { PluginManager } from './PluginManager';
+export type { Plugin, PluginHooks, PluginOptions, PluginFactory } from './types';
+
+// Built-in plugins
+export { createLoggingPlugin } from './builtin/LoggingPlugin';
+export { createRetryPlugin } from './builtin/RetryPlugin';