taro-bluetooth-print 2.2.1 → 2.3.1

package/dist/types/plugins/PluginManager.d.ts

@@ -0,0 +1,87 @@
+import { Plugin, PluginHooks, PluginOptions } from './types';
+import { BluetoothPrintError } from '../errors/BluetoothError';
+import { PrinterState } from '../types';
+/**
+ * Manages plugins for BluetoothPrinter
+ */
+export declare class PluginManager {
+    private plugins;
+    private readonly logger;
+    /**
+     * Register a plugin
+     * @param plugin - Plugin to register
+     * @param options - Plugin options
+     * @throws {BluetoothPrintError} If plugin with same name already exists
+     */
+    register(plugin: Plugin, options?: PluginOptions): Promise<void>;
+    /**
+     * Unregister a plugin
+     * @param name - Plugin name to unregister
+     */
+    unregister(name: string): Promise<void>;
+    /**
+     * Get a registered plugin
+     * @param name - Plugin name
+     * @returns Plugin instance or undefined
+     */
+    get(name: string): Plugin | undefined;
+    /**
+     * Get all registered plugin names
+     * @returns Array of plugin names
+     */
+    getNames(): string[];
+    /**
+     * Check if a plugin is registered
+     * @param name - Plugin name
+     * @returns True if registered
+     */
+    has(name: string): boolean;
+    /**
+     * 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)
+     */
+    executeHook<K extends keyof PluginHooks>(hookName: K, ...args: Parameters<NonNullable<PluginHooks[K]>>): Promise<unknown>;
+    /**
+     * Execute beforeConnect hooks
+     */
+    beforeConnect(deviceId: string): Promise<string>;
+    /**
+     * Execute afterConnect hooks
+     */
+    afterConnect(deviceId: string): Promise<void>;
+    /**
+     * Execute beforeDisconnect hooks
+     */
+    beforeDisconnect(deviceId: string): Promise<void>;
+    /**
+     * Execute afterDisconnect hooks
+     */
+    afterDisconnect(deviceId: string): Promise<void>;
+    /**
+     * Execute beforePrint hooks
+     */
+    beforePrint(buffer: Uint8Array): Promise<Uint8Array>;
+    /**
+     * Execute afterPrint hooks
+     */
+    afterPrint(bytesSent: number): Promise<void>;
+    /**
+     * Execute onError hooks
+     * @returns True if error should be suppressed
+     */
+    onError(error: BluetoothPrintError): Promise<boolean>;
+    /**
+     * Execute onStateChange hooks
+     */
+    onStateChange(state: PrinterState, previousState: PrinterState): Promise<void>;
+    /**
+     * Execute onProgress hooks
+     */
+    onProgress(sent: number, total: number): Promise<void>;
+    /**
+     * Clear all plugins
+     */
+    clear(): Promise<void>;
+}

package/dist/types/plugins/builtin/LoggingPlugin.d.ts

@@ -0,0 +1,14 @@
+import { PluginFactory, PluginOptions } from '../types';
+import { 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 declare const createLoggingPlugin: PluginFactory;

package/dist/types/plugins/builtin/RetryPlugin.d.ts

@@ -0,0 +1,18 @@
+import { PluginFactory, PluginOptions } from '../types';
+import { 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 declare const createRetryPlugin: PluginFactory;

package/dist/types/plugins/index.d.ts

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

package/dist/types/plugins/types.d.ts

@@ -0,0 +1,97 @@
+import { BluetoothPrintError } from '../errors/BluetoothError';
+import { PrinterState } from '../types';
+/**
+ * Plugin lifecycle hooks
+ */
+export interface PluginHooks {
+    /**
+     * Called before connecting to a device
+     * @param deviceId - Target device ID
+     * @returns Modified device ID or void
+     */
+    beforeConnect?: (deviceId: string) => string | void | Promise<string | void>;
+    /**
+     * Called after successful connection
+     * @param deviceId - Connected device ID
+     */
+    afterConnect?: (deviceId: string) => void | Promise<void>;
+    /**
+     * Called before disconnecting
+     * @param deviceId - Device ID to disconnect
+     */
+    beforeDisconnect?: (deviceId: string) => void | Promise<void>;
+    /**
+     * Called after disconnection
+     * @param deviceId - Disconnected device ID
+     */
+    afterDisconnect?: (deviceId: string) => void | Promise<void>;
+    /**
+     * Called before sending print data
+     * @param buffer - Data buffer to send
+     * @returns Modified buffer or void
+     */
+    beforePrint?: (buffer: Uint8Array) => Uint8Array | void | Promise<Uint8Array | void>;
+    /**
+     * Called after print job completes
+     * @param bytesSent - Total bytes sent
+     */
+    afterPrint?: (bytesSent: number) => void | Promise<void>;
+    /**
+     * Called when an error occurs
+     * @param error - The error that occurred
+     * @returns Whether to suppress the error (true = suppress)
+     */
+    onError?: (error: BluetoothPrintError) => boolean | void | Promise<boolean | void>;
+    /**
+     * Called when printer state changes
+     * @param state - New printer state
+     * @param previousState - Previous state
+     */
+    onStateChange?: (state: PrinterState, previousState: PrinterState) => void | Promise<void>;
+    /**
+     * Called during print progress
+     * @param sent - Bytes sent
+     * @param total - Total bytes
+     */
+    onProgress?: (sent: number, total: number) => void | Promise<void>;
+}
+/**
+ * Plugin configuration options
+ */
+export interface PluginOptions {
+    [key: string]: unknown;
+}
+/**
+ * Plugin interface
+ */
+export interface Plugin {
+    /**
+     * Unique plugin name
+     */
+    name: string;
+    /**
+     * Plugin version
+     */
+    version?: string;
+    /**
+     * Plugin description
+     */
+    description?: string;
+    /**
+     * Plugin hooks
+     */
+    hooks: PluginHooks;
+    /**
+     * Plugin initialization
+     * @param options - Plugin options
+     */
+    init?: (options?: PluginOptions) => void | Promise<void>;
+    /**
+     * Plugin cleanup
+     */
+    destroy?: () => void | Promise<void>;
+}
+/**
+ * Plugin factory function type
+ */
+export type PluginFactory = (options?: PluginOptions) => Plugin;

package/dist/types/services/CommandBuilder.d.ts

@@ -2,7 +2,6 @@ import { IPrinterDriver, IQrOptions } from '../types';
 import { ICommandBuilder } from './interfaces';
 import { TextAlign, TextStyle } from '../formatter';
 import { BarcodeOptions } from '../barcode';
-
 /**
  * Command Builder implementation
  */

package/dist/types/services/ConnectionManager.d.ts

@@ -2,7 +2,6 @@ import { IPrinterAdapter, PrinterState } from '../types';
 import { IConnectionManager } from './interfaces';
 import { BluetoothPrintError } from '../errors/BluetoothError';
 import { EventEmitter } from '../core/EventEmitter';
-
 /**
  * Connection manager configuration
  */
@@ -55,7 +54,7 @@ export declare class ConnectionManager extends EventEmitter<ConnectionManagerEve
     private adapter;
     private deviceId;
     private state;
-    private readonly logger;
+    private readonly connLogger;
     private readonly config;
     private heartbeatTimer;
     private reconnectAttempts;

package/dist/types/services/PrintJobManager.d.ts

@@ -1,6 +1,5 @@
 import { IAdapterOptions } from '../types';
 import { IPrintJobManager, IConnectionManager } from './interfaces';
-
 /**
  * Print Job Manager implementation
  */

package/dist/types/services/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Services Module
+ * 服务模块 - 提供连接管理、命令构建、任务管理等功能
+ */
+export { ConnectionManager, type ConnectionManagerConfig, type ConnectionManagerEvents, } from './ConnectionManager';
+export { CommandBuilder } from './CommandBuilder';
+export { PrintJobManager } from './PrintJobManager';
+export * from './interfaces';

package/dist/types/services/interfaces/index.d.ts

@@ -1,7 +1,6 @@
 import { IAdapterOptions, IQrOptions, PrinterState, IPrinterAdapter } from '../../types';
 import { TextAlign, TextStyle } from '../../formatter';
 import { BarcodeOptions } from '../../barcode';
-
 /**
  * Connection Manager Interface
  *

package/dist/types/template/TemplateEngine.d.ts

@@ -1,6 +1,5 @@
 import { TextAlign } from '../formatter';
 import { BarcodeFormat } from '../barcode';
-
 /**
  * Template type
  */

package/package.json

@@ -1,18 +1,30 @@
 {
   "name": "taro-bluetooth-print",
-  "version": "2.2.1",
-  "description": "Taro 蓝牙打印库 v2.2 - 轻量级、高性能、跨平台支持微信、支付宝、百度、字节跳动小程序及H5 Web Bluetooth",
+  "version": "2.3.1",
+  "description": "Taro 蓝牙打印库 v2.3 - 轻量级、高性能、跨平台支持微信、支付宝、百度、字节跳动小程序及H5 Web Bluetooth",
   "type": "module",
   "main": "dist/index.cjs.js",
   "module": "dist/index.es.js",
   "types": "dist/types/index.d.ts",
   "exports": {
     ".": {
+      "types": "./dist/types/index.d.ts",
       "import": "./dist/index.es.js",
       "require": "./dist/index.cjs.js",
-      "types": "./dist/types/index.d.ts",
       "default": "./dist/index.umd.js"
     },
+    "./core": {
+      "types": "./dist/types/core/index.d.ts",
+      "import": "./dist/core/index.es.js"
+    },
+    "./drivers": {
+      "types": "./dist/types/drivers/index.d.ts",
+      "import": "./dist/drivers/index.es.js"
+    },
+    "./adapters": {
+      "types": "./dist/types/adapters/index.d.ts",
+      "import": "./dist/adapters/index.es.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -34,9 +46,9 @@
     "format:check": "prettier --check \"src/**/*.{ts,tsx,json,md}\"",
     "type-check": "tsc --noEmit",
     "prepublishOnly": "npm run build",
-    "test": "jest",
-    "test:watch": "jest --watch",
-    "test:coverage": "jest --coverage"
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
   },
   "keywords": [
     "taro",
@@ -49,28 +61,32 @@
   ],
   "author": "Agions",
   "license": "MIT",
-  "dependencies": {
-    "@tarojs/taro": "^3.6.0"
+  "peerDependencies": {
+    "@tarojs/taro": "^3.6.22"
+  },
+  "peerDependenciesMeta": {
+    "@tarojs/taro": {
+      "optional": true
+    }
   },
   "devDependencies": {
-    "@types/jest": "^29.5.11",
     "@types/node": "^20.14.8",
-    "@typescript-eslint/eslint-plugin": "^6.19.0",
-    "@typescript-eslint/parser": "^6.19.0",
+    "@types/web-bluetooth": "^0.0.21",
+    "@typescript-eslint/eslint-plugin": "^8.57.1",
+    "@typescript-eslint/parser": "^8.57.1",
+    "@vitest/coverage-v8": "^4.0.18",
     "eslint": "^8.56.0",
     "eslint-config-prettier": "^9.1.0",
     "eslint-plugin-prettier": "^5.1.3",
     "fast-check": "^4.5.3",
-    "jest": "^29.7.0",
-    "jest-environment-jsdom": "^29.7.0",
-    "prettier": "^3.2.4",
-    "rimraf": "^5.0.0",
-    "terser": "^5.24.0",
-    "ts-jest": "^29.1.1",
+    "prettier": "^3.8.1",
+    "rimraf": "^6.1.2",
+    "terser": "^5.46.0",
     "typescript": "^5.9.3",
-    "vite": "^5.0.0",
-    "vite-plugin-dts": "^3.9.1",
-    "vitepress": "^1.0.0"
+    "vite": "^7.3.1",
+    "vite-plugin-dts": "^4.5.4",
+    "vitepress": "^1.6.4",
+    "vitest": "^4.0.18"
   },
   "sideEffects": false
 }

package/src/adapters/BaseAdapter.ts

@@ -242,15 +242,13 @@ export abstract class MiniProgramAdapter extends BaseAdapter {
       this.logger.info('Device connected successfully');
 
       // Listen for connection state changes
-      this.getApi().onBLEConnectionStateChange(
-        (res: { deviceId: string; connected: boolean }) => {
-          if (res.deviceId === deviceId && !res.connected) {
-            this.logger.warn('Device disconnected unexpectedly');
-            this.updateState(PrinterState.DISCONNECTED);
-            this.cleanupDevice(deviceId);
-          }
+      this.getApi().onBLEConnectionStateChange((res: { deviceId: string; connected: boolean }) => {
+        if (res.deviceId === deviceId && !res.connected) {
+          this.logger.warn('Device disconnected unexpectedly');
+          this.updateState(PrinterState.DISCONNECTED);
+          this.cleanupDevice(deviceId);
         }
-      );
+      });
     } catch (error) {
       this.updateState(PrinterState.DISCONNECTED);
       this.logger.error('Connection failed:', error);

package/src/core/BluetoothPrinter.ts

@@ -60,7 +60,7 @@ export interface PrinterEvents {
  * ```
  */
 export class BluetoothPrinter extends EventEmitter<PrinterEvents> {
-  private readonly logger = Logger.scope('BluetoothPrinter');
+  private readonly printerLogger = Logger.scope('BluetoothPrinter');
 
   /** Current printer state */
   public state: PrinterState = PrinterState.DISCONNECTED;
@@ -155,7 +155,7 @@ export class BluetoothPrinter extends EventEmitter<PrinterEvents> {
     }
 
     this.emit('state-change', this.state);
-    this.logger.debug('State updated:', this.state);
+    this.printerLogger.debug('State updated:', this.state);
   }
 
   /**
@@ -171,13 +171,13 @@ export class BluetoothPrinter extends EventEmitter<PrinterEvents> {
    * ```
    */
   async connect(deviceId: string): Promise<this> {
-    this.logger.info('Connecting to device:', deviceId);
+    this.printerLogger.info('Connecting to device:', deviceId);
 
     try {
       await this.connectionManager.connect(deviceId);
       this.updateState();
       this.emit('connected', deviceId);
-      this.logger.info('Connected successfully');
+      this.printerLogger.info('Connected successfully');
 
       return this;
     } catch (error) {
@@ -208,18 +208,18 @@ export class BluetoothPrinter extends EventEmitter<PrinterEvents> {
   async disconnect(): Promise<void> {
     const deviceId = this.connectionManager.getDeviceId();
     if (!deviceId) {
-      this.logger.warn('Disconnect called but no device connected');
+      this.printerLogger.warn('Disconnect called but no device connected');
       return;
     }
 
-    this.logger.info('Disconnecting from device:', deviceId);
+    this.printerLogger.info('Disconnecting from device:', deviceId);
 
     try {
       await this.connectionManager.disconnect();
       this.printJobManager.cancel();
       this.updateState();
       this.emit('disconnected', deviceId);
-      this.logger.info('Disconnected successfully');
+      this.printerLogger.info('Disconnected successfully');
     } catch (error) {
       const printError = new BluetoothPrintError(
         ErrorCode.DEVICE_DISCONNECTED,
@@ -346,7 +346,7 @@ export class BluetoothPrinter extends EventEmitter<PrinterEvents> {
   pause(): void {
     this.printJobManager.pause();
     this.updateState();
-    this.logger.info('Print job paused');
+    this.printerLogger.info('Print job paused');
   }
 
   /**
@@ -360,12 +360,12 @@ export class BluetoothPrinter extends EventEmitter<PrinterEvents> {
    * ```
    */
   async resume(): Promise<void> {
-    this.logger.info('Resuming print job');
+    this.printerLogger.info('Resuming print job');
 
     try {
       await this.printJobManager.resume();
       this.updateState();
-      this.logger.info('Print job resumed');
+      this.printerLogger.info('Print job resumed');
     } catch (error) {
       const printError = new BluetoothPrintError(
         ErrorCode.PRINT_JOB_FAILED,
@@ -390,7 +390,7 @@ export class BluetoothPrinter extends EventEmitter<PrinterEvents> {
     this.printJobManager.cancel();
     this.commandBuilder.clear();
     this.updateState();
-    this.logger.info('Print job cancelled');
+    this.printerLogger.info('Print job cancelled');
   }
 
   /**
@@ -439,7 +439,7 @@ export class BluetoothPrinter extends EventEmitter<PrinterEvents> {
     }
 
     const buffer = this.commandBuilder.getBuffer();
-    this.logger.info(`Starting print job: ${buffer.length} bytes`);
+    this.printerLogger.info(`Starting print job: ${buffer.length} bytes`);
 
     // Clear the command buffer after getting the buffer for printing
     this.commandBuilder.clear();
@@ -462,14 +462,14 @@ export class BluetoothPrinter extends EventEmitter<PrinterEvents> {
 
       if (isPaused) {
         // Print job was paused
-        this.logger.info('Print job paused');
+        this.printerLogger.info('Print job paused');
       } else {
         // Print job completed successfully
         this.emit('print-complete');
-        this.logger.info('Print job completed successfully');
+        this.printerLogger.info('Print job completed successfully');
       }
     } catch (error) {
-      this.logger.error('Print job failed with error:', error);
+      this.printerLogger.error('Print job failed with error:', error);
       const printError =
         error instanceof BluetoothPrintError
           ? error

package/src/core/EventEmitter.ts

@@ -24,12 +24,12 @@
  * });
  * ```
  */
+import { Logger } from '@/utils/logger';
+
 export class EventEmitter<T> {
-  // 使用Map存储事件监听器，Set确保每个监听器唯一
   private listeners: Map<keyof T, Set<(data: T[keyof T]) => void>> = new Map();
-
-  // Debug mode flag
   private debugMode = false;
+  protected readonly logger = Logger.scope('EventEmitter');
 
   /**
    * Subscribe to an event
@@ -45,7 +45,7 @@ export class EventEmitter<T> {
     this.listeners.get(event)!.add(handler as (data: T[keyof T]) => void);
 
     if (this.debugMode) {
-      console.debug(`EventEmitter: Added listener for "${String(event)}"`, {
+      this.logger.debug(`EventEmitter: Added listener for "${String(event)}"`, {
         listenerCount: this.listenerCount(event),
       });
     }
@@ -90,7 +90,7 @@ export class EventEmitter<T> {
     this.listeners.set(event, newHandlers);
 
     if (this.debugMode) {
-      console.debug(`EventEmitter: Prepend listener for "${String(event)}"`, {
+      this.logger.debug(`EventEmitter: Prepend listener for "${String(event)}"`, {
         listenerCount: this.listenerCount(event),
       });
     }
@@ -125,7 +125,7 @@ export class EventEmitter<T> {
       handlers.delete(handler as (data: T[keyof T]) => void);
 
       if (this.debugMode) {
-        console.debug(`EventEmitter: Removed listener for "${String(event)}"`, {
+        this.logger.debug(`EventEmitter: Removed listener for "${String(event)}"`, {
           listenerCount: handlers.size,
         });
       }
@@ -135,7 +135,7 @@ export class EventEmitter<T> {
         this.listeners.delete(event);
 
         if (this.debugMode) {
-          console.debug(`EventEmitter: Removed event "${String(event)}" (no more listeners)`);
+          this.logger.debug(`EventEmitter: Removed event "${String(event)}" (no more listeners)`);
         }
       }
     }
@@ -154,7 +154,7 @@ export class EventEmitter<T> {
     const data = args[0] as T[K];
 
     if (this.debugMode) {
-      console.debug(`EventEmitter: Emitting "${String(event)}"`, {
+      this.logger.debug(`EventEmitter: Emitting "${String(event)}"`, {
         data,
         listenerCount: this.listenerCount(event),
       });
@@ -184,7 +184,7 @@ export class EventEmitter<T> {
           }
         } catch (error) {
           // 捕获并处理事件处理程序中的错误，避免影响其他监听器
-          console.error(`Error in event handler for "${String(event)}":`, error);
+          this.logger.error(`Error in event handler for "${String(event)}":`, error);
         }
       }
     }
@@ -204,7 +204,7 @@ export class EventEmitter<T> {
     const data = args[0] as T[K];
 
     if (this.debugMode) {
-      console.debug(`EventEmitter: Emitting async "${String(event)}"`, {
+      this.logger.debug(`EventEmitter: Emitting async "${String(event)}"`, {
         data,
         listenerCount: this.listenerCount(event),
       });
@@ -238,7 +238,7 @@ export class EventEmitter<T> {
             }
           } catch (error) {
             // 捕获并处理事件处理程序中的错误，避免影响其他监听器
-            console.error(`Error in event handler for "${String(event)}":`, error);
+            this.logger.error(`Error in event handler for "${String(event)}":`, error);
           }
         })()
       );
@@ -247,7 +247,7 @@ export class EventEmitter<T> {
     await Promise.all(promises);
 
     if (this.debugMode) {
-      console.debug(`EventEmitter: Finished emitting async "${String(event)}"`);
+      this.logger.debug(`EventEmitter: Finished emitting async "${String(event)}"`);
     }
   }
 
@@ -262,7 +262,7 @@ export class EventEmitter<T> {
       this.listeners.delete(event);
 
       if (this.debugMode) {
-        console.debug(
+        this.logger.debug(
           `EventEmitter: Removed all ${listenerCount} listeners for "${String(event)}"`
         );
       }
@@ -272,7 +272,7 @@ export class EventEmitter<T> {
       this.listeners.clear();
 
       if (this.debugMode) {
-        console.debug(`EventEmitter: Removed all ${eventCount} events and their listeners`);
+        this.logger.debug(`EventEmitter: Removed all ${eventCount} events and their listeners`);
       }
     }
   }
@@ -327,7 +327,7 @@ export class EventEmitter<T> {
    */
   setDebugMode(enabled: boolean): void {
     this.debugMode = enabled;
-    console.debug(`EventEmitter: Debug mode ${enabled ? 'enabled' : 'disabled'}`);
+    this.logger.debug(`EventEmitter: Debug mode ${enabled ? 'enabled' : 'disabled'}`);
   }
 
   /**

package/src/core/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Core Module - 核心模块
+ */
+
+export { BluetoothPrinter } from './BluetoothPrinter';
+export type { PrinterEvents } from './BluetoothPrinter';
+export { EventEmitter } from './EventEmitter';