taro-bluetooth-print 2.8.4 → 2.9.1

package/src/errors/PrintJobError.ts

@@ -0,0 +1,75 @@
+/**
+ * Print Job Error
+ *
+ * Specialized error for print job failures
+ */
+
+import { BluetoothPrintError, ErrorCode } from './BluetoothError';
+
+/**
+ * Print job-related error codes
+ */
+export enum PrintJobErrorCode {
+  /** Print job failed */
+  FAILED = 'PRINT_JOB_FAILED',
+  /** Print job is already in progress */
+  IN_PROGRESS = 'PRINT_JOB_IN_PROGRESS',
+  /** Print job was cancelled */
+  CANCELLED = 'PRINT_JOB_CANCELLED',
+  /** Print data is invalid */
+  INVALID_DATA = 'INVALID_IMAGE_DATA',
+  /** Write operation failed */
+  WRITE_FAILED = 'WRITE_FAILED',
+  /** Write operation timed out */
+  WRITE_TIMEOUT = 'WRITE_TIMEOUT',
+}
+
+/**
+ * PrintJobError - Specialized error for print job failures
+ *
+ * @example
+ * ```typescript
+ * throw new PrintJobError(
+ *   PrintJobErrorCode.WRITE_FAILED,
+ *   'Failed to send data to printer',
+ *   originalError
+ * );
+ * ```
+ */
+export class PrintJobError extends BluetoothPrintError {
+  constructor(
+    public readonly jobErrorCode: PrintJobErrorCode,
+    message: string,
+    originalError?: Error
+  ) {
+    const baseCode = PrintJobError._toBaseCode(jobErrorCode);
+    super(baseCode, message, originalError);
+    this.name = 'PrintJobError';
+
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, PrintJobError);
+    }
+  }
+
+  /**
+   * Converts PrintJobErrorCode to base ErrorCode
+   */
+  private static _toBaseCode(code: PrintJobErrorCode): ErrorCode {
+    const mapping: Partial<Record<PrintJobErrorCode, ErrorCode>> = {
+      [PrintJobErrorCode.FAILED]: ErrorCode.PRINT_JOB_FAILED,
+      [PrintJobErrorCode.IN_PROGRESS]: ErrorCode.PRINT_JOB_IN_PROGRESS,
+      [PrintJobErrorCode.CANCELLED]: ErrorCode.PRINT_JOB_CANCELLED,
+      [PrintJobErrorCode.INVALID_DATA]: ErrorCode.INVALID_IMAGE_DATA,
+      [PrintJobErrorCode.WRITE_FAILED]: ErrorCode.WRITE_FAILED,
+      [PrintJobErrorCode.WRITE_TIMEOUT]: ErrorCode.WRITE_TIMEOUT,
+    };
+    return mapping[code] ?? ErrorCode.PRINT_JOB_FAILED;
+  }
+
+  /**
+   * Checks if an error is a print job error
+   */
+  static isPrintJobError(error: unknown): error is PrintJobError {
+    return error instanceof PrintJobError;
+  }
+}

package/src/errors/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Errors Module
+ *
+ * @packageDocumentation
+ */
+
+export { BluetoothPrintError, ErrorCode } from './BluetoothError';
+export { ConnectionError, ConnectionErrorCode } from './ConnectionError';
+export { PrintJobError, PrintJobErrorCode } from './PrintJobError';
+export { CommandBuildError, CommandBuildErrorCode } from './CommandBuildError';

package/src/factory/PrinterFactory.ts

@@ -0,0 +1,139 @@
+/**
+ * Printer Factory
+ *
+ * Factory for creating properly configured BluetoothPrinter instances.
+ * This is the recommended way to create printer instances - avoid direct
+ * constructor calls unless you need custom dependency injection.
+ */
+
+import { BluetoothPrinter } from '@/core/BluetoothPrinter';
+import { ConnectionManager } from '@/services/ConnectionManager';
+import { PrintJobManager } from '@/services/PrintJobManager';
+import { CommandBuilder } from '@/services/CommandBuilder';
+import type { IPrinterAdapter } from '@/types';
+import type { IConnectionManager, IPrintJobManager, ICommandBuilder } from '@/services/interfaces';
+
+/**
+ * Options for creating a BluetoothPrinter via the factory
+ */
+export interface PrinterFactoryOptions {
+  /**
+   * Printer adapter to use for Bluetooth communication.
+   * Required if not providing custom connectionManager.
+   *
+   * Common adapters:
+   * - WebBluetoothAdapter (browser Web Bluetooth API)
+   * - TaroAdapter (Taro framework)
+   * - AlipayAdapter (Alipay mini-program)
+   * - ReactNativeAdapter (React Native)
+   *
+   * @example
+   * ```typescript
+   * import { WebBluetoothAdapter } from 'taro-bluetooth-print';
+   *
+   * const printer = createBluetoothPrinter({
+   *   adapter: new WebBluetoothAdapter()
+   * });
+   * ```
+   */
+  adapter?: IPrinterAdapter;
+
+  /**
+   * Custom connection manager instance.
+   * If provided, overrides the default ConnectionManager.
+   * Useful for testing or custom connection handling.
+   */
+  connectionManager?: IConnectionManager;
+
+  /**
+   * Custom print job manager instance.
+   * If provided, overrides the default PrintJobManager.
+   * Useful for custom job scheduling or queue management.
+   */
+  printJobManager?: IPrintJobManager;
+
+  /**
+   * Custom command builder instance.
+   * If provided, overrides the default CommandBuilder.
+   * Useful for custom command formatting or driver selection.
+   */
+  commandBuilder?: ICommandBuilder;
+}
+
+/**
+ * Creates a new BluetoothPrinter instance with properly configured services.
+ *
+ * This is the recommended factory function for creating printer instances.
+ * It handles dependency injection and ensures all services are properly wired.
+ *
+ * @param options - Factory options for configuring the printer
+ * @returns A fully configured BluetoothPrinter instance
+ *
+ * @example
+ * ```typescript
+ * // Basic usage with WebBluetooth
+ * import { createBluetoothPrinter, WebBluetoothAdapter } from 'taro-bluetooth-print';
+ *
+ * const printer = createBluetoothPrinter({
+ *   adapter: new WebBluetoothAdapter()
+ * });
+ *
+ * await printer.connect('device-id');
+ * await printer.text('Hello').feed(2).cut().print();
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Advanced usage with custom services
+ * import { createBluetoothPrinter, TaroAdapter } from 'taro-bluetooth-print';
+ *
+ * const printer = createBluetoothPrinter({
+ *   adapter: new TaroAdapter(),
+ *   printJobManager: customPrintJobManager,
+ * });
+ * ```
+ */
+export function createBluetoothPrinter(options: PrinterFactoryOptions = {}): BluetoothPrinter {
+  const { adapter, connectionManager, printJobManager, commandBuilder } = options;
+
+  // Build dependency chain: CommandBuilder -> PrintJobManager -> ConnectionManager -> Adapter
+  const finalConnectionManager = connectionManager ?? new ConnectionManager(adapter);
+  const finalPrintJobManager = printJobManager ?? new PrintJobManager(finalConnectionManager);
+  const finalCommandBuilder = commandBuilder ?? new CommandBuilder();
+
+  return new BluetoothPrinter(finalConnectionManager, finalPrintJobManager, finalCommandBuilder);
+}
+
+/**
+ * Creates a BluetoothPrinter instance for the Web Bluetooth API.
+ *
+ * This is a convenience function specifically for browser environments
+ * using the Web Bluetooth API.
+ *
+ * @param adapterOptions - Options to pass to the WebBluetoothAdapter
+ * @returns A BluetoothPrinter instance configured for Web Bluetooth
+ *
+ * @example
+ * ```typescript
+ * import { createWebBluetoothPrinter } from 'taro-bluetooth-print';
+ *
+ * const printer = createWebBluetoothPrinter();
+ * await printer.connect('device-id');
+ * ```
+ */
+export async function createWebBluetoothPrinter(): Promise<BluetoothPrinter> {
+  const { WebBluetoothAdapter } = await import('@/adapters/WebBluetoothAdapter');
+  const adapter = new WebBluetoothAdapter();
+  return createBluetoothPrinter({ adapter });
+}
+
+/**
+ * Default printer factory instance
+ *
+ * @deprecated Use the factory functions directly. This export exists
+ * for backward compatibility only.
+ */
+export const PrinterFactory = {
+  create: createBluetoothPrinter,
+  createWebBluetooth: createWebBluetoothPrinter,
+};

package/src/factory/di-factory.ts

@@ -0,0 +1,61 @@
+/**
+ * DI 版本的 BluetoothPrinter 工厂
+ *
+ * 使用依赖注入容器创建打印机实例
+ */
+
+import { BluetoothPrinter } from '@/core/BluetoothPrinter';
+import { createServiceProvider } from '@/providers';
+import type { ServiceProviderOptions } from '@/providers';
+import type { IConnectionManager, IPrintJobManager, ICommandBuilder } from '@/services/interfaces';
+
+/**
+ * 创建打印机实例的选项
+ */
+export interface CreatePrinterOptions extends ServiceProviderOptions {
+  /** 自定义连接管理器 */
+  connectionManager?: IConnectionManager;
+  /** 自定义打印任务管理器 */
+  printJobManager?: IPrintJobManager;
+  /** 自定义命令构建器 */
+  commandBuilder?: ICommandBuilder;
+}
+
+/**
+ * 使用依赖注入创建 BluetoothPrinter 实例
+ *
+ * @example
+ * ```typescript
+ * // 基本用法
+ * const printer = createPrinter();
+ *
+ * // 使用自定义配置
+ * const printer = createPrinter({
+ *   config: { debug: true },
+ *   useGlobalEventBus: true
+ * });
+ * ```
+ */
+export function createPrinter(options: CreatePrinterOptions = {}): BluetoothPrinter {
+  // 注册服务（如果尚未注册）
+  const provider = createServiceProvider(options);
+
+  // 使用提供的实例或从容器解析（需要类型断言）
+  const connectionManager =
+    options.connectionManager || (provider.getConnectionManager() as IConnectionManager);
+  const printJobManager =
+    options.printJobManager || (provider.getPrintJobManager() as IPrintJobManager);
+  const commandBuilder =
+    options.commandBuilder || (provider.getCommandBuilder() as ICommandBuilder);
+
+  return new BluetoothPrinter(connectionManager, printJobManager, commandBuilder);
+}
+
+/**
+ * 获取服务提供者（用于访问所有服务）
+ */
+export function getServiceProvider(options: ServiceProviderOptions = {}) {
+  return createServiceProvider(options);
+}
+
+export { createServiceProvider, ServiceProviderOptions };

package/src/factory/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Factory Module
+ *
+ * @packageDocumentation
+ */
+
+export {
+  createBluetoothPrinter,
+  createWebBluetoothPrinter,
+  PrinterFactory,
+  type PrinterFactoryOptions,
+} from './PrinterFactory';

package/src/index.ts

@@ -84,9 +84,70 @@ export { Logger, LogLevel } from './utils/logger';
 export { Encoding } from './utils/encoding';
 export { ImageProcessing } from './utils/image';
 export { PlatformType, detectPlatform, isPlatformSupported } from './utils/platform';
+export {
+  truncateString,
+  truncateForLog,
+  batchProcess,
+  createLimitedLogger,
+  generateSummary,
+} from './utils/outputLimiter';
+export type { TruncateOptions } from './utils/outputLimiter';
 
 // Error handling - 错误处理
 export { BluetoothPrintError, ErrorCode } from './errors/BluetoothError';
+export { ConnectionError, ConnectionErrorCode } from './errors/ConnectionError';
+export { PrintJobError, PrintJobErrorCode } from './errors/PrintJobError';
+export { CommandBuildError, CommandBuildErrorCode } from './errors/CommandBuildError';
+
+// Factory - 工厂模式
+export {
+  createBluetoothPrinter,
+  createWebBluetoothPrinter,
+  PrinterFactory,
+  type PrinterFactoryOptions,
+} from './factory';
+
+// DI Factory - 依赖注入工厂
+export {
+  createPrinter,
+  getServiceProvider,
+  createServiceProvider,
+  type CreatePrinterOptions,
+  type ServiceProviderOptions,
+} from './factory/di-factory';
+
+// Core Architecture - 核心架构
+export {
+  Container,
+  rootContainer,
+  injectable,
+  inject,
+  EventBus,
+  globalEventBus,
+  PluginManager,
+} from './core';
+
+export {
+  ADAPTER_TOKEN,
+  DRIVER_TOKEN,
+  DEVICE_MANAGER_TOKEN,
+  CONNECTION_MANAGER_TOKEN,
+  PRINT_JOB_MANAGER_TOKEN,
+  PRINT_QUEUE_TOKEN,
+  OFFLINE_CACHE_TOKEN,
+  CONFIG_MANAGER_TOKEN,
+  LOGGER_TOKEN,
+  EVENT_BUS_TOKEN,
+  PLUGIN_MANAGER_TOKEN,
+  PERFORMANCE_MONITOR_TOKEN,
+  COMMAND_BUILDER_TOKEN,
+  PRINTER_STATUS_TOKEN,
+  PRINT_HISTORY_TOKEN,
+  PRINT_STATISTICS_TOKEN,
+  CLOUD_PRINT_MANAGER_TOKEN,
+  SCHEDULED_RETRY_MANAGER_TOKEN,
+  BATCH_PRINT_MANAGER_TOKEN,
+} from './core';
 
 // Configuration - 配置
 export { DEFAULT_CONFIG, mergeConfig } from './config/PrinterConfig';
@@ -101,7 +162,6 @@ export { PrinterConfigManager, printerConfigManager } from './config/PrinterConf
 export type { SavedPrinter, GlobalConfig, IConfigStorage } from './config/PrinterConfigManager';
 
 // Plugin System - 插件系统
-export { PluginManager } from './plugins/PluginManager';
 export { createLoggingPlugin, createRetryPlugin } from './plugins';
 export type { Plugin, PluginHooks, PluginOptions, PluginFactory } from './plugins/types';
 

package/src/providers/ServiceProvider.ts

@@ -0,0 +1,213 @@
+/**
+ * Service Provider Module
+ *
+ * 将现有服务层注册到 DI 容器
+ */
+
+import {
+  rootContainer,
+  CONNECTION_MANAGER_TOKEN,
+  PRINT_JOB_MANAGER_TOKEN,
+  COMMAND_BUILDER_TOKEN,
+  DEVICE_MANAGER_TOKEN,
+  PRINT_QUEUE_TOKEN,
+  OFFLINE_CACHE_TOKEN,
+  CONFIG_MANAGER_TOKEN,
+  PRINTER_STATUS_TOKEN,
+  PRINT_HISTORY_TOKEN,
+  PRINT_STATISTICS_TOKEN,
+  CLOUD_PRINT_MANAGER_TOKEN,
+  SCHEDULED_RETRY_MANAGER_TOKEN,
+  BATCH_PRINT_MANAGER_TOKEN,
+  EVENT_BUS_TOKEN,
+  PLUGIN_MANAGER_TOKEN,
+  ADAPTER_TOKEN,
+} from '@/core';
+
+import { ConnectionManager } from '@/services/ConnectionManager';
+import { PrintJobManager } from '@/services/PrintJobManager';
+import { CommandBuilder } from '@/services/CommandBuilder';
+import { DeviceManager } from '@/device/DeviceManager';
+import { PrintQueue } from '@/queue/PrintQueue';
+import { OfflineCache } from '@/cache/OfflineCache';
+import { PrinterConfigManager } from '@/config/PrinterConfigManager';
+import { PrinterStatus } from '@/services/PrinterStatus';
+import { PrintHistory } from '@/services/PrintHistory';
+import { PrintStatistics } from '@/services/PrintStatistics';
+import { CloudPrintManager } from '@/services/CloudPrintManager';
+import { ScheduledRetryManager } from '@/services/ScheduledRetryManager';
+import { BatchPrintManager } from '@/services/BatchPrintManager';
+import { globalEventBus, EventBus } from '@/core/event/EventBus';
+import { PluginManager } from '@/core/plugin/PluginManager';
+import { AdapterFactory } from '@/adapters/AdapterFactory';
+import type { Container } from '@/core/di/Container';
+
+/**
+ * 服务提供者配置选项
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export interface ServiceProviderOptions {
+  /** 是否启用全局事件总线 */
+  useGlobalEventBus?: boolean;
+  /** 自定义配置 */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  config?: Record<string, unknown>;
+}
+
+/**
+ * 注册所有服务到 DI 容器
+ */
+export function registerServices(options: ServiceProviderOptions = {}): void {
+  const { useGlobalEventBus = true } = options;
+
+  // 1. 注册事件总线（全局或新建）
+  rootContainer.register(EVENT_BUS_TOKEN, {
+    useValue: useGlobalEventBus ? globalEventBus : new EventBus(),
+    lifecycle: 'singleton',
+  });
+
+  // 2. 注册适配器（工厂模式）
+  rootContainer.register(ADAPTER_TOKEN, {
+    useFactory: () => AdapterFactory.create(),
+    lifecycle: 'singleton',
+  });
+
+  // 3. 注册连接管理器
+  rootContainer.register(CONNECTION_MANAGER_TOKEN, {
+    useClass: ConnectionManager,
+    lifecycle: 'singleton',
+  });
+
+  // 4. 注册打印任务管理器
+  rootContainer.register(PRINT_JOB_MANAGER_TOKEN, {
+    useClass: PrintJobManager,
+    lifecycle: 'singleton',
+  });
+
+  // 5. 注册命令构建器
+  rootContainer.register(COMMAND_BUILDER_TOKEN, {
+    useClass: CommandBuilder,
+    lifecycle: 'transient',
+  });
+
+  // 6. 注册设备管理器
+  rootContainer.register(DEVICE_MANAGER_TOKEN, {
+    useClass: DeviceManager,
+    lifecycle: 'singleton',
+  });
+
+  // 7. 注册打印队列
+  rootContainer.register(PRINT_QUEUE_TOKEN, {
+    useClass: PrintQueue,
+    lifecycle: 'singleton',
+  });
+
+  // 8. 注册离线缓存
+  rootContainer.register(OFFLINE_CACHE_TOKEN, {
+    useClass: OfflineCache,
+    lifecycle: 'singleton',
+  });
+
+  // 9. 注册配置管理器
+  rootContainer.register(CONFIG_MANAGER_TOKEN, {
+    useClass: PrinterConfigManager,
+    lifecycle: 'singleton',
+  });
+
+  // 10. 注册打印机状态服务
+  rootContainer.register(PRINTER_STATUS_TOKEN, {
+    useClass: PrinterStatus,
+    lifecycle: 'singleton',
+  });
+
+  // 11. 注册打印历史服务
+  rootContainer.register(PRINT_HISTORY_TOKEN, {
+    useClass: PrintHistory,
+    lifecycle: 'singleton',
+  });
+
+  // 12. 注册打印统计服务
+  rootContainer.register(PRINT_STATISTICS_TOKEN, {
+    useClass: PrintStatistics,
+    lifecycle: 'singleton',
+  });
+
+  // 13. 注册云打印管理器
+  rootContainer.register(CLOUD_PRINT_MANAGER_TOKEN, {
+    useClass: CloudPrintManager,
+    lifecycle: 'singleton',
+  });
+
+  // 14. 注册定时重试管理器
+  rootContainer.register(SCHEDULED_RETRY_MANAGER_TOKEN, {
+    useClass: ScheduledRetryManager,
+    lifecycle: 'singleton',
+  });
+
+  // 15. 注册批量打印管理器
+  rootContainer.register(BATCH_PRINT_MANAGER_TOKEN, {
+    useClass: BatchPrintManager,
+    lifecycle: 'singleton',
+  });
+
+  // 16. 注册插件管理器
+  rootContainer.register(PLUGIN_MANAGER_TOKEN, {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any,@typescript-eslint/no-unnecessary-type-assertion
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion
+    useFactory: (container: Container) => {
+      // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion
+      const eventBus = container.resolve(EVENT_BUS_TOKEN) as EventBus;
+      return new PluginManager({
+        eventBus,
+        container,
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        config: (options.config || {}) as Record<string, any>,
+      });
+    },
+    lifecycle: 'singleton',
+  });
+}
+
+/**
+ * 创建配置好的服务提供者
+ */
+export function createServiceProvider(options: ServiceProviderOptions = {}) {
+  registerServices(options);
+
+  return {
+    /** 获取连接管理器 */
+    getConnectionManager: () => rootContainer.resolve(CONNECTION_MANAGER_TOKEN),
+    /** 获取打印任务管理器 */
+    getPrintJobManager: () => rootContainer.resolve(PRINT_JOB_MANAGER_TOKEN),
+    /** 获取命令构建器 */
+    getCommandBuilder: () => rootContainer.resolve(COMMAND_BUILDER_TOKEN),
+    /** 获取设备管理器 */
+    getDeviceManager: () => rootContainer.resolve(DEVICE_MANAGER_TOKEN),
+    /** 获取打印队列 */
+    getPrintQueue: () => rootContainer.resolve(PRINT_QUEUE_TOKEN),
+    /** 获取离线缓存 */
+    getOfflineCache: () => rootContainer.resolve(OFFLINE_CACHE_TOKEN),
+    /** 获取配置管理器 */
+    getConfigManager: () => rootContainer.resolve(CONFIG_MANAGER_TOKEN),
+    /** 获取打印机状态服务 */
+    getPrinterStatus: () => rootContainer.resolve(PRINTER_STATUS_TOKEN),
+    /** 获取打印历史服务 */
+    getPrintHistory: () => rootContainer.resolve(PRINT_HISTORY_TOKEN),
+    /** 获取打印统计服务 */
+    getPrintStatistics: () => rootContainer.resolve(PRINT_STATISTICS_TOKEN),
+    /** 获取云打印管理器 */
+    getCloudPrintManager: () => rootContainer.resolve(CLOUD_PRINT_MANAGER_TOKEN),
+    /** 获取定时重试管理器 */
+    getScheduledRetryManager: () => rootContainer.resolve(SCHEDULED_RETRY_MANAGER_TOKEN),
+    /** 获取批量打印管理器 */
+    getBatchPrintManager: () => rootContainer.resolve(BATCH_PRINT_MANAGER_TOKEN),
+    /** 获取事件总线 */
+    getEventBus: () => rootContainer.resolve(EVENT_BUS_TOKEN),
+    /** 获取插件管理器 */
+    getPluginManager: () => rootContainer.resolve(PLUGIN_MANAGER_TOKEN),
+    /** 获取适配器 */
+    getAdapter: () => rootContainer.resolve(ADAPTER_TOKEN),
+  };
+}
+
+export type ServiceProvider = ReturnType<typeof createServiceProvider>;

package/src/providers/index.ts

@@ -0,0 +1,2 @@
+export { registerServices, createServiceProvider } from './ServiceProvider';
+export type { ServiceProviderOptions, ServiceProvider } from './ServiceProvider';