taro-bluetooth-print 2.8.4 → 2.9.1

package/src/core/di/Tokens.ts

@@ -0,0 +1,45 @@
+/**
+ * 服务标识符（Tokens）
+ * 用于依赖注入的常量定义
+ */
+
+// 适配器相关
+export const ADAPTER_TOKEN = Symbol.for('Adapter');
+export const ADAPTER_FACTORY_TOKEN = Symbol.for('AdapterFactory');
+
+// 驱动相关
+export const DRIVER_TOKEN = Symbol.for('Driver');
+export const DRIVER_FACTORY_TOKEN = Symbol.for('DriverFactory');
+
+// 服务相关
+export const DEVICE_MANAGER_TOKEN = Symbol.for('DeviceManager');
+export const CONNECTION_MANAGER_TOKEN = Symbol.for('ConnectionManager');
+export const PRINT_JOB_MANAGER_TOKEN = Symbol.for('PrintJobManager');
+export const PRINT_QUEUE_TOKEN = Symbol.for('PrintQueue');
+export const OFFLINE_CACHE_TOKEN = Symbol.for('OfflineCache');
+export const CONFIG_MANAGER_TOKEN = Symbol.for('ConfigManager');
+
+// 新增服务令牌
+export const COMMAND_BUILDER_TOKEN = Symbol.for('CommandBuilder');
+export const PRINTER_STATUS_TOKEN = Symbol.for('PrinterStatus');
+export const PRINT_HISTORY_TOKEN = Symbol.for('PrintHistory');
+export const PRINT_STATISTICS_TOKEN = Symbol.for('PrintStatistics');
+export const CLOUD_PRINT_MANAGER_TOKEN = Symbol.for('CloudPrintManager');
+export const SCHEDULED_RETRY_MANAGER_TOKEN = Symbol.for('ScheduledRetryManager');
+export const BATCH_PRINT_MANAGER_TOKEN = Symbol.for('BatchPrintManager');
+
+// 工具服务
+export const LOGGER_TOKEN = Symbol.for('Logger');
+export const ENCODING_SERVICE_TOKEN = Symbol.for('EncodingService');
+export const IMAGE_PROCESSING_TOKEN = Symbol.for('ImageProcessing');
+export const BARCODE_GENERATOR_TOKEN = Symbol.for('BarcodeGenerator');
+export const TEMPLATE_ENGINE_TOKEN = Symbol.for('TemplateEngine');
+
+// 事件系统
+export const EVENT_BUS_TOKEN = Symbol.for('EventBus');
+
+// 插件系统
+export const PLUGIN_MANAGER_TOKEN = Symbol.for('PluginManager');
+
+// 性能监控
+export const PERFORMANCE_MONITOR_TOKEN = Symbol.for('PerformanceMonitor');

package/src/core/di/index.ts

@@ -0,0 +1,3 @@
+export { Container, rootContainer, injectable, inject } from './Container';
+export type { ServiceProviderConfig, RegistrationOptions } from './Container';
+export * from './Tokens';

package/src/core/event/EventBus.ts

@@ -0,0 +1,251 @@
+/**
+ * 事件总线 - 提供强大的事件驱动能力
+ * 支持事件订阅、发布、一次性监听、异步处理等
+ */
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type EventHandler<T = any> = (payload: T) => void | Promise<void>;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type EventFilter<T = any> = (payload: T) => boolean;
+
+export interface EventSubscription {
+  unsubscribe(): void;
+}
+
+export interface EventOptions {
+  /** 优先级，数字越小优先级越高 */
+  priority?: number;
+  /** 过滤器 */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  filter?: EventFilter<any>;
+  /** 是否只监听一次 */
+  once?: boolean;
+  /** 超时时间（毫秒） */
+  timeout?: number;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+interface EventListener<T = any> {
+  handler: EventHandler<T>;
+  options: Required<Pick<EventOptions, 'priority'>> & Omit<EventOptions, 'priority'>;
+  id: string;
+}
+
+export class EventBus {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private listeners = new Map<string | symbol, EventListener<any>[]>();
+  private listenerIdCounter = 0;
+
+  /**
+   * 订阅事件
+   */
+  on<T>(
+    event: string | symbol,
+    handler: EventHandler<T>,
+    options: EventOptions = {}
+  ): EventSubscription {
+    const id = this.generateListenerId();
+    const listener: EventListener<T> = {
+      handler,
+      options: {
+        priority: options.priority ?? 100,
+        filter: options.filter,
+        once: options.once ?? false,
+        timeout: options.timeout,
+      },
+      id,
+    };
+
+    const eventKey = String(event);
+    if (!this.listeners.has(eventKey)) {
+      this.listeners.set(eventKey, []);
+    }
+
+    const listeners = this.listeners.get(eventKey)!;
+    listeners.push(listener);
+
+    // 按优先级排序
+    listeners.sort((a, b) => a.options.priority - b.options.priority);
+
+    return {
+      unsubscribe: () => {
+        this.off(event, handler);
+      },
+    };
+  }
+
+  /**
+   * 只监听一次
+   */
+  once<T>(
+    event: string | symbol,
+    handler: EventHandler<T>,
+    options: Omit<EventOptions, 'once'> = {}
+  ): EventSubscription {
+    return this.on(event, handler, { ...options, once: true });
+  }
+
+  /**
+   * 取消订阅
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  off<T>(event: string | symbol, handler: EventHandler<T>): void {
+    const eventKey = String(event);
+    const listeners = this.listeners.get(eventKey);
+    if (!listeners) return;
+
+    const index = listeners.findIndex(l => l.handler === handler);
+    if (index !== -1) {
+      listeners.splice(index, 1);
+    }
+
+    if (listeners.length === 0) {
+      this.listeners.delete(eventKey);
+    }
+  }
+
+  /**
+   * 发布事件
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  async emit<T>(event: string | symbol, payload: T): Promise<void> {
+    const eventKey = String(event);
+    const listeners = this.listeners.get(eventKey);
+    if (!listeners || listeners.length === 0) return;
+
+    const toRemove: number[] = [];
+
+    for (let i = 0; i < listeners.length; i++) {
+      const listener = listeners[i];
+      if (!listener) continue;
+
+      // 应用过滤器
+      if (listener.options.filter && !listener.options.filter(payload)) {
+        continue;
+      }
+
+      try {
+        if (listener.options.timeout) {
+          await this.executeWithTimeout(listener.handler, payload, listener.options.timeout);
+        } else {
+          await listener.handler(payload);
+        }
+      } catch (error) {
+        console.error(`Error in event handler for "${eventKey}":`, error);
+      }
+
+      // 标记一次性监听器
+      if (listener.options.once) {
+        toRemove.push(i);
+      }
+    }
+
+    // 移除一次性监听器
+    for (let i = toRemove.length - 1; i >= 0; i--) {
+      const index = toRemove[i];
+      if (index !== undefined) {
+        listeners.splice(index, 1);
+      }
+    }
+
+    if (listeners.length === 0) {
+      this.listeners.delete(eventKey);
+    }
+  }
+
+  /**
+   * 同步发布事件（不等待处理完成）
+   */
+  emitSync<T>(event: string | symbol, payload: T): void {
+    this.emit(event, payload).catch(error => {
+      console.error(`Error in async event handler for "${String(event)}":`, error);
+    });
+  }
+
+  /**
+   * 等待特定事件
+   */
+  waitFor<T>(
+    event: string | symbol,
+    timeout?: number,
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    _filter?: EventFilter<T>
+  ): Promise<T> {
+    return new Promise((resolve, reject) => {
+      const timer = timeout
+        ? setTimeout(() => {
+            subscription.unsubscribe();
+            reject(new Error(`Timeout waiting for event "${String(event)}"`));
+          }, timeout)
+        : null;
+
+      const subscription = this.once<T>(event, payload => {
+        if (timer) clearTimeout(timer);
+        resolve(payload);
+      });
+    });
+  }
+
+  /**
+   * 检查是否有监听器
+   */
+  hasListeners(event: string | symbol): boolean {
+    const listeners = this.listeners.get(String(event));
+    return !!listeners && listeners.length > 0;
+  }
+
+  /**
+   * 获取监听器数量
+   */
+  listenerCount(event: string | symbol): number {
+    const listeners = this.listeners.get(String(event));
+    return listeners?.length ?? 0;
+  }
+
+  /**
+   * 移除所有监听器
+   */
+  removeAllListeners(event?: string | symbol): void {
+    if (event) {
+      this.listeners.delete(String(event));
+    } else {
+      this.listeners.clear();
+    }
+  }
+
+  /**
+   * 获取所有事件名称
+   */
+  eventNames(): (string | symbol)[] {
+    return Array.from(this.listeners.keys());
+  }
+
+  private generateListenerId(): string {
+    return `listener_${++this.listenerIdCounter}`;
+  }
+
+  private executeWithTimeout<T>(
+    handler: EventHandler<T>,
+    payload: T,
+    timeout: number
+  ): Promise<void> {
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        reject(new Error(`Event handler timed out after ${timeout}ms`));
+      }, timeout);
+
+      Promise.resolve(handler(payload))
+        .then(() => {
+          clearTimeout(timer);
+          resolve();
+        })
+        .catch(error => {
+          clearTimeout(timer);
+          reject(error instanceof Error ? error : new Error(String(error)));
+        });
+    });
+  }
+}
+
+// 全局事件总线实例
+export const globalEventBus = new EventBus();

package/src/core/event/index.ts

@@ -0,0 +1,2 @@
+export { EventBus, globalEventBus } from './EventBus';
+export type { EventHandler, EventFilter, EventSubscription, EventOptions } from './EventBus';

package/src/core/index.ts

@@ -1,7 +1,13 @@
 /**
- * Core Module - 核心模块
+ * 核心架构模块
+ * 提供依赖注入、事件总线、插件管理等核心能力
  */
 
-export { BluetoothPrinter } from './BluetoothPrinter';
-export type { PrinterEvents } from './BluetoothPrinter';
-export { EventEmitter } from './EventEmitter';
+// 依赖注入
+export * from './di';
+
+// 事件总线
+export * from './event';
+
+// 插件管理
+export * from './plugin';

package/src/core/plugin/PluginManager.ts

@@ -0,0 +1,161 @@
+import type { EventBus } from '../event/EventBus';
+import type { Container } from '../di/Container';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export interface PluginContext {
+  /** 事件总线 */
+  eventBus: EventBus;
+  /** DI容器 */
+  container: Container;
+  /** 配置 */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  config: Record<string, unknown>;
+}
+
+export interface Plugin {
+  /** 插件名称 */
+  name: string;
+  /** 插件版本 */
+  version: string;
+  /** 插件依赖 */
+  dependencies?: string[];
+  /** 安装插件 */
+  install(context: PluginContext): void | Promise<void>;
+  /** 卸载插件 */
+  uninstall?(context: PluginContext): void | Promise<void>;
+}
+
+export interface PluginRegistration {
+  plugin: Plugin;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  config: Record<string, unknown>;
+  installed: boolean;
+}
+
+export class PluginManager {
+  private plugins = new Map<string, PluginRegistration>();
+  private context: PluginContext;
+
+  constructor(context: PluginContext) {
+    this.context = context;
+  }
+
+  /**
+   * 注册插件
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  register(plugin: Plugin, config: Record<string, unknown> = {}): void {
+    if (this.plugins.has(plugin.name)) {
+      throw new Error(`Plugin "${plugin.name}" is already registered`);
+    }
+
+    this.plugins.set(plugin.name, {
+      plugin,
+      config,
+      installed: false,
+    });
+  }
+
+  /**
+   * 安装插件
+   */
+  async install(pluginName: string): Promise<void> {
+    const registration = this.plugins.get(pluginName);
+    if (!registration) {
+      throw new Error(`Plugin "${pluginName}" not found`);
+    }
+
+    if (registration.installed) {
+      return;
+    }
+
+    // 检查依赖
+    if (registration.plugin.dependencies) {
+      for (const dep of registration.plugin.dependencies) {
+        if (!this.plugins.has(dep)) {
+          throw new Error(`Plugin "${pluginName}" depends on "${dep}" which is not registered`);
+        }
+        await this.install(dep);
+      }
+    }
+
+    // 安装插件
+    const context: PluginContext = {
+      ...this.context,
+      config: { ...this.context.config, ...registration.config },
+    };
+
+    await registration.plugin.install(context);
+    registration.installed = true;
+
+    // 发布插件安装事件
+    await this.context.eventBus.emit('plugin:installed', {
+      name: pluginName,
+      version: registration.plugin.version,
+    });
+  }
+
+  /**
+   * 卸载插件
+   */
+  async uninstall(pluginName: string): Promise<void> {
+    const registration = this.plugins.get(pluginName);
+    if (!registration || !registration.installed) {
+      return;
+    }
+
+    // 检查是否有其他插件依赖此插件
+    for (const [name, reg] of this.plugins) {
+      if (reg.installed && reg.plugin.dependencies?.includes(pluginName)) {
+        throw new Error(`Cannot uninstall "${pluginName}" because "${name}" depends on it`);
+      }
+    }
+
+    if (registration.plugin.uninstall) {
+      await registration.plugin.uninstall(this.context);
+    }
+
+    registration.installed = false;
+
+    await this.context.eventBus.emit('plugin:uninstalled', { name: pluginName });
+  }
+
+  /**
+   * 批量安装插件
+   */
+  async installAll(): Promise<void> {
+    for (const [name] of this.plugins) {
+      await this.install(name);
+    }
+  }
+
+  /**
+   * 获取插件
+   */
+  getPlugin(name: string): Plugin | undefined {
+    return this.plugins.get(name)?.plugin;
+  }
+
+  /**
+   * 检查插件是否已安装
+   */
+  isInstalled(name: string): boolean {
+    return this.plugins.get(name)?.installed ?? false;
+  }
+
+  /**
+   * 获取所有已安装的插件
+   */
+  getInstalledPlugins(): Plugin[] {
+    return Array.from(this.plugins.values())
+      .filter(r => r.installed)
+      .map(r => r.plugin);
+  }
+
+  /**
+   * 获取所有已注册的插件
+   */
+  getRegisteredPlugins(): Plugin[] {
+    return Array.from(this.plugins.values()).map(r => r.plugin);
+  }
+}

package/src/core/plugin/index.ts

@@ -0,0 +1,2 @@
+export { PluginManager } from './PluginManager';
+export type { Plugin, PluginContext, PluginRegistration } from './PluginManager';

package/src/device/MultiPrinterManager.ts

@@ -44,6 +44,8 @@ export interface PrinterConnection {
   connectedAt: number;
   /** Last activity timestamp */
   lastActivity?: number;
+  /** Error handler reference (for cleanup) */
+  errorHandler?: (error: Error) => void;
 }
 
 /**
@@ -200,14 +202,15 @@ export class MultiPrinterManager {
     try {
       const printer = new BluetoothPrinter();
 
-      // Set up error handler
-      printer.on('error', error => {
-        this.emit('printer-error', { printerId, error });
-      });
-
-      // Connect
+      // Connect first so we know it works before storing
       await printer.connect(actualDeviceId);
 
+      // Set up error handler and store reference for cleanup
+      const errorHandler = (error: Error) => {
+        this.emit('printer-error', { printerId, error });
+      };
+      printer.on('error', errorHandler);
+
       const connection: PrinterConnection = {
         printerId,
         deviceId: actualDeviceId,
@@ -215,6 +218,7 @@ export class MultiPrinterManager {
         printer,
         connectedAt: Date.now(),
         lastActivity: Date.now(),
+        errorHandler,
       };
 
       this.printers.set(printerId, connection);
@@ -242,6 +246,11 @@ export class MultiPrinterManager {
 
     this.logger.info(`Disconnecting printer "${printerId}"`);
 
+    // Remove error handler to prevent memory leak
+    if (connection.errorHandler) {
+      connection.printer.off('error', connection.errorHandler);
+    }
+
     try {
       await connection.printer.disconnect();
     } catch (error) {

package/src/errors/CommandBuildError.ts

@@ -0,0 +1,72 @@
+/**
+ * Command Build Error
+ *
+ * Specialized error for command building failures
+ */
+
+import { BluetoothPrintError, ErrorCode } from './BluetoothError';
+
+/**
+ * Command building error codes
+ */
+export enum CommandBuildErrorCode {
+  /** Invalid configuration */
+  INVALID_CONFIG = 'INVALID_CONFIGURATION',
+  /** Encoding not supported */
+  ENCODING_NOT_SUPPORTED = 'ENCODING_NOT_SUPPORTED',
+  /** Invalid image data */
+  INVALID_IMAGE = 'INVALID_IMAGE_DATA',
+  /** Invalid QR code data */
+  INVALID_QR = 'INVALID_QR_DATA',
+  /** Driver error */
+  DRIVER_ERROR = 'DRIVER_ERROR',
+}
+
+/**
+ * CommandBuildError - Specialized error for command building failures
+ *
+ * @example
+ * ```typescript
+ * throw new CommandBuildError(
+ *   CommandBuildErrorCode.ENCODING_NOT_SUPPORTED,
+ *   'Encoding "EUC-JP" is not supported',
+ *   originalError
+ * );
+ * ```
+ */
+export class CommandBuildError extends BluetoothPrintError {
+  constructor(
+    public readonly buildErrorCode: CommandBuildErrorCode,
+    message: string,
+    originalError?: Error
+  ) {
+    const baseCode = CommandBuildError._toBaseCode(buildErrorCode);
+    super(baseCode, message, originalError);
+    this.name = 'CommandBuildError';
+
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, CommandBuildError);
+    }
+  }
+
+  /**
+   * Converts CommandBuildErrorCode to base ErrorCode
+   */
+  private static _toBaseCode(code: CommandBuildErrorCode): ErrorCode {
+    const mapping: Partial<Record<CommandBuildErrorCode, ErrorCode>> = {
+      [CommandBuildErrorCode.INVALID_CONFIG]: ErrorCode.INVALID_CONFIGURATION,
+      [CommandBuildErrorCode.ENCODING_NOT_SUPPORTED]: ErrorCode.ENCODING_NOT_SUPPORTED,
+      [CommandBuildErrorCode.INVALID_IMAGE]: ErrorCode.INVALID_IMAGE_DATA,
+      [CommandBuildErrorCode.INVALID_QR]: ErrorCode.INVALID_QR_DATA,
+      [CommandBuildErrorCode.DRIVER_ERROR]: ErrorCode.PRINT_JOB_FAILED,
+    };
+    return mapping[code] ?? ErrorCode.INVALID_CONFIGURATION;
+  }
+
+  /**
+   * Checks if an error is a command build error
+   */
+  static isCommandBuildError(error: unknown): error is CommandBuildError {
+    return error instanceof CommandBuildError;
+  }
+}

package/src/errors/ConnectionError.ts

@@ -0,0 +1,78 @@
+/**
+ * Connection Error
+ *
+ * Specialized error for connection-related failures
+ */
+
+import { BluetoothPrintError, ErrorCode } from './BluetoothError';
+
+/**
+ * Connection-related error codes
+ */
+export enum ConnectionErrorCode {
+  /** Failed to establish connection */
+  FAILED = 'CONNECTION_FAILED',
+  /** Connection attempt timed out */
+  TIMEOUT = 'CONNECTION_TIMEOUT',
+  /** Device not found during discovery */
+  NOT_FOUND = 'DEVICE_NOT_FOUND',
+  /** Device disconnected unexpectedly */
+  DISCONNECTED = 'DEVICE_DISCONNECTED',
+  /** Bluetooth service not found on device */
+  SERVICE_NOT_FOUND = 'SERVICE_NOT_FOUND',
+  /** Bluetooth characteristic not found */
+  CHARACTERISTIC_NOT_FOUND = 'CHARACTERISTIC_NOT_FOUND',
+  /** Service discovery failed */
+  DISCOVERY_FAILED = 'SERVICE_DISCOVERY_FAILED',
+  /** Platform doesn't support Bluetooth */
+  PLATFORM_UNSUPPORTED = 'PLATFORM_NOT_SUPPORTED',
+}
+
+/**
+ * ConnectionError - Specialized error for connection-related failures
+ *
+ * @example
+ * ```typescript
+ * throw new ConnectionError(
+ *   ConnectionErrorCode.TIMEOUT,
+ *   'Connection timed out after 30s',
+ *   originalError
+ * );
+ * ```
+ */
+export class ConnectionError extends BluetoothPrintError {
+  constructor(code: ConnectionErrorCode, message: string, originalError?: Error) {
+    // Map our codes to the base ErrorCode enum
+    const baseCode = ConnectionError._toBaseCode(code);
+    super(baseCode, message, originalError);
+    this.name = 'ConnectionError';
+
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, ConnectionError);
+    }
+  }
+
+  /**
+   * Converts ConnectionErrorCode to base ErrorCode
+   */
+  private static _toBaseCode(code: ConnectionErrorCode): ErrorCode {
+    const mapping: Partial<Record<ConnectionErrorCode, ErrorCode>> = {
+      [ConnectionErrorCode.FAILED]: ErrorCode.CONNECTION_FAILED,
+      [ConnectionErrorCode.TIMEOUT]: ErrorCode.CONNECTION_TIMEOUT,
+      [ConnectionErrorCode.NOT_FOUND]: ErrorCode.DEVICE_NOT_FOUND,
+      [ConnectionErrorCode.DISCONNECTED]: ErrorCode.DEVICE_DISCONNECTED,
+      [ConnectionErrorCode.SERVICE_NOT_FOUND]: ErrorCode.SERVICE_NOT_FOUND,
+      [ConnectionErrorCode.CHARACTERISTIC_NOT_FOUND]: ErrorCode.CHARACTERISTIC_NOT_FOUND,
+      [ConnectionErrorCode.DISCOVERY_FAILED]: ErrorCode.SERVICE_DISCOVERY_FAILED,
+      [ConnectionErrorCode.PLATFORM_UNSUPPORTED]: ErrorCode.PLATFORM_NOT_SUPPORTED,
+    };
+    return mapping[code] ?? ErrorCode.CONNECTION_FAILED;
+  }
+
+  /**
+   * Checks if an error is a connection-related error
+   */
+  static isConnectionError(error: unknown): error is ConnectionError {
+    return error instanceof ConnectionError;
+  }
+}