taro-bluetooth-print 2.9.3 → 2.9.6

package/dist/types/adapters/BaseAdapter.d.ts

@@ -147,6 +147,11 @@ export declare abstract class BaseAdapter implements IPrinterAdapter {
      * @param deviceId - Device ID
      */
     protected cleanupDevice(deviceId: string): void;
+    /**
+     * Cleanup resources and destroy the adapter instance
+     * Removes all event listeners and releases resources
+     */
+    destroy(): void;
 }
 /**
  * Base adapter for mini-program platforms (Taro/WeChat, Alipay, Baidu, ByteDance).

package/dist/types/adapters/WebBluetoothAdapter.d.ts

@@ -173,4 +173,9 @@ export declare class WebBluetoothAdapter extends BaseAdapter {
      * Uses device name + first seen timestamp as identifier
      */
     private generateFallbackDeviceId;
+    /**
+     * Cleanup resources and destroy the adapter instance
+     * Removes all event listeners and releases resources
+     */
+    destroy(): void;
 }

package/dist/types/core/BluetoothPrinter.d.ts

@@ -338,4 +338,14 @@ export declare class BluetoothPrinter extends EventEmitter<PrinterEvents> {
      * @returns Command builder instance
      */
     getCommandBuilder(): ICommandBuilder;
+    /**
+     * Cleanup resources and destroy the printer instance
+     * Removes all event listeners and releases resources
+     *
+     * @example
+     * ```typescript
+     * printer.destroy();
+     * ```
+     */
+    destroy(): void;
 }

package/dist/types/drivers/CpclDriver.d.ts

@@ -264,12 +264,17 @@ export declare class CpclDriver {
      */
     logo(x: number, y: number, logoName: string): this;
     /**
-     * Download logo to printer (store in memory)
-     * Note: This is a placeholder for future implementation
+     * Download logo to printer memory (macro/form storage).
+     * Encodes bitmap using CPCL CG (Compressed Graphic) command.
+     * The bitmap should be 1-bit monochrome data.
      * @param logoName - Name to store logo as
-     * @param _bitmap - Logo bitmap data (placeholder)
+     * @param bitmap - 1-bit monochrome bitmap data (MSB first, row-major)
+     * @param options - Optional width and height (will be inferred from bitmap size if omitted)
      */
-    downloadLogo(logoName: string, _bitmap: Uint8Array): this;
+    downloadLogo(logoName: string, bitmap: Uint8Array, options?: {
+        width?: number;
+        height?: number;
+    }): this;
     /**
      * Print stored logo
      * @param logoName - Logo name

package/dist/types/drivers/ZplDriver.d.ts

@@ -267,15 +267,15 @@ export declare class ZplDriver {
      */
     ellipse(x: number, y: number, width: number, height: number, borderThickness?: number): this;
     /**
-     * Add image from raw bitmap
-     * Note: For best results, use pre-processed images. This is a placeholder for future implementation.
-     * @param _x - X position (placeholder)
-     * @param _y - Y position (placeholder)
-     * @param _width - Image width (placeholder)
-     * @param _height - Image height (placeholder)
-     * @param _bitmap - Binary bitmap data (placeholder)
-     */
-    image(_x: number, _y: number, _width: number, _height: number, _bitmap: Uint8Array): this;
+     * Add image from raw bitmap using ZPL ^GFA (Graphic Field) command.
+     * The bitmap should be 1-bit (monochrome) data where each bit represents a pixel.
+     * @param x - X position in dots
+     * @param y - Y position in dots
+     * @param width - Image width in pixels
+     * @param height - Image height in pixels
+     * @param bitmap - 1-bit monochrome bitmap data (MSB first, row-major)
+     */
+    image(x: number, y: number, width: number, height: number, bitmap: Uint8Array): this;
     /**
      * Set darkness/print density
      * @param value - Darkness value (0-30, default: 15)

package/dist/types/queue/PrintQueue.d.ts

@@ -127,6 +127,7 @@ export declare class PrintQueue implements IPrintQueue {
     private activeJobs;
     private jobCounter;
     private executor;
+    private retryTimerId;
     /**
      * Creates a new PrintQueue instance
      */

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

@@ -46,4 +46,9 @@ export interface IConnectionManager {
      * @returns IPrinterAdapter - Printer adapter
      */
     getAdapter(): IPrinterAdapter;
+    /**
+     * Cleanup resources and destroy the connection manager
+     * Stops heartbeat, clears timers, and removes event listeners
+     */
+    destroy(): void;
 }

package/dist/types/types.d.ts

@@ -67,6 +67,11 @@ export interface IPrinterAdapter {
      * @param callback - Function to call when the state changes
      */
     onStateChange?(callback: (state: PrinterState) => void): void;
+    /**
+     * Cleanup resources and destroy the adapter instance
+     * Removes all event listeners and releases resources
+     */
+    destroy?(): void;
 }
 /**
  * Interface for printer drivers

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taro-bluetooth-print",
-  "version": "2.9.3",
+  "version": "2.9.6",
   "description": "Taro 蓝牙打印库 v2.6 - 轻量级、高性能、跨平台支持微信、支付宝、百度、字节跳动小程序及H5 Web Bluetooth",
   "type": "module",
   "main": "dist/index.cjs.js",
@@ -88,5 +88,15 @@
     "vitepress": "^1.6.4",
     "vitest": "^4.0.18"
   },
-  "sideEffects": false
+  "sideEffects": false,
+  "pnpm": {
+    "overrides": {
+      "esbuild@<=0.24.2": ">=0.25.0",
+      "lodash-es@>=4.0.0 <=4.17.22": ">=4.17.23",
+      "lodash-es@>=4.0.0 <=4.17.23": ">=4.18.0",
+      "lodash-es@<=4.17.23": ">=4.18.0",
+      "vite@<=6.4.1": ">=6.4.2",
+      "postcss@<8.5.10": ">=8.5.10"
+    }
+  }
 }

package/src/adapters/BaseAdapter.ts

@@ -185,6 +185,16 @@ export abstract class BaseAdapter implements IPrinterAdapter {
   protected cleanupDevice(deviceId: string): void {
     this.serviceCache.delete(deviceId);
   }
+
+  /**
+   * Cleanup resources and destroy the adapter instance
+   * Removes all event listeners and releases resources
+   */
+  destroy(): void {
+    this.logger.debug('Destroying BaseAdapter');
+    this.serviceCache.clear();
+    this.stateCallback = undefined;
+  }
 }
 
 /**

package/src/adapters/WebBluetoothAdapter.ts

@@ -10,6 +10,14 @@ import { IAdapterOptions, PrinterState } from '@/types';
 import { BaseAdapter } from './BaseAdapter';
 import { BluetoothPrintError, ErrorCode } from '@/errors/BluetoothError';
 
+/**
+ * Extended Bluetooth device interface with RSSI support
+ * This is a vendor-specific extension not part of the standard Web Bluetooth API
+ */
+interface BluetoothDeviceWithRssi extends BluetoothDevice {
+  readRemoteRssi(): Promise<number>;
+}
+
 /**
  * Web Bluetooth device information
  */
@@ -210,10 +218,12 @@ export class WebBluetoothAdapter extends BaseAdapter {
       // Get RSSI if available (may not be available on all devices)
       let rssi: number | undefined;
       try {
-        if ('readRemoteRssi' in characteristic.service.device) {
-          /* eslint-disable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-assignment */
-          rssi = await (characteristic.service.device as any).readRemoteRssi();
-          /* eslint-enable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-assignment */
+        const deviceWithRssi = characteristic.service.device as unknown as BluetoothDeviceWithRssi;
+        if (
+          'readRemoteRssi' in deviceWithRssi &&
+          typeof deviceWithRssi.readRemoteRssi === 'function'
+        ) {
+          rssi = await deviceWithRssi.readRemoteRssi();
         }
       } catch {
         this.logger.debug('RSSI reading not supported on this device');
@@ -681,4 +691,38 @@ export class WebBluetoothAdapter extends BaseAdapter {
     const timestamp = Date.now().toString(36);
     return `fallback_${name}_${timestamp}`;
   }
+
+  /**
+   * Cleanup resources and destroy the adapter instance
+   * Removes all event listeners and releases resources
+   */
+  destroy(): void {
+    this.logger.debug('Destroying WebBluetoothAdapter');
+
+    // Clear any pending connection cleanup timeout
+    if (this.connectionCleanupTimeout) {
+      clearTimeout(this.connectionCleanupTimeout);
+      this.connectionCleanupTimeout = null;
+    }
+
+    // Disconnect all devices
+    for (const [deviceId, deviceInfo] of this.devices) {
+      try {
+        if (deviceInfo.server.connected) {
+          deviceInfo.server.disconnect();
+        }
+      } catch (error) {
+        this.logger.warn(`Error disconnecting device ${deviceId}:`, error);
+      }
+    }
+
+    // Clear all device caches
+    this.devices.clear();
+    this.discoveredDevices.clear();
+
+    // Call parent destroy
+    super.destroy();
+
+    this.logger.info('WebBluetoothAdapter destroyed');
+  }
 }

package/src/core/BluetoothPrinter.ts

@@ -131,19 +131,12 @@ export class BluetoothPrinter extends EventEmitter<PrinterEvents> {
    * Updates the current state based on the connection manager and print job manager states
    */
   private updateState(): void {
-    // Safe fallbacks for mock objects in tests
-    const connectionState =
-      typeof this.connectionManager.getState === 'function'
-        ? this.connectionManager.getState()
-        : PrinterState.CONNECTED;
+    // All interface methods are guaranteed to exist
+    const connectionState = this.connectionManager.getState();
 
-    const isPrinting =
-      typeof this.printJobManager.isInProgress === 'function'
-        ? this.printJobManager.isInProgress()
-        : false;
+    const isPrinting = this.printJobManager.isInProgress();
 
-    const isPaused =
-      typeof this.printJobManager.isPaused === 'function' ? this.printJobManager.isPaused() : false;
+    const isPaused = this.printJobManager.isPaused();
 
     // Determine the final state
     if (isPaused) {
@@ -425,10 +418,7 @@ export class BluetoothPrinter extends EventEmitter<PrinterEvents> {
    * ```
    */
   async print(): Promise<void> {
-    const isConnected =
-      typeof this.connectionManager.isConnected === 'function'
-        ? this.connectionManager.isConnected()
-        : true; // Default to true for mock objects
+    const isConnected = this.connectionManager.isConnected();
 
     if (!isConnected) {
       throw new BluetoothPrintError(
@@ -453,10 +443,7 @@ export class BluetoothPrinter extends EventEmitter<PrinterEvents> {
     try {
       await this.printJobManager.start(buffer);
 
-      const isPaused =
-        typeof this.printJobManager.isPaused === 'function'
-          ? this.printJobManager.isPaused()
-          : false;
+      const isPaused = this.printJobManager.isPaused();
 
       if (isPaused) {
         // Print job was paused
@@ -607,4 +594,38 @@ export class BluetoothPrinter extends EventEmitter<PrinterEvents> {
   getCommandBuilder(): ICommandBuilder {
     return this.commandBuilder;
   }
+
+  /**
+   * Cleanup resources and destroy the printer instance
+   * Removes all event listeners and releases resources
+   *
+   * @example
+   * ```typescript
+   * printer.destroy();
+   * ```
+   */
+  destroy(): void {
+    this.printerLogger.info('Destroying BluetoothPrinter instance');
+
+    // Cancel any pending print job
+    this.printJobManager.cancel();
+
+    // Clear command buffer
+    this.commandBuilder.clear();
+
+    // Disconnect if connected
+    if (this.connectionManager.isConnected()) {
+      this.connectionManager.disconnect().catch(error => {
+        this.printerLogger.warn('Error during disconnect in destroy:', error);
+      });
+    }
+
+    // Cleanup connection manager resources (IConnectionManager now has destroy())
+    this.connectionManager.destroy();
+
+    // Remove all event listeners
+    this.removeAllListeners();
+
+    this.printerLogger.info('BluetoothPrinter instance destroyed');
+  }
 }

package/src/drivers/CpclDriver.ts

@@ -478,16 +478,43 @@ export class CpclDriver {
   }
 
   /**
-   * Download logo to printer (store in memory)
-   * Note: This is a placeholder for future implementation
+   * Download logo to printer memory (macro/form storage).
+   * Encodes bitmap using CPCL CG (Compressed Graphic) command.
+   * The bitmap should be 1-bit monochrome data.
    * @param logoName - Name to store logo as
-   * @param _bitmap - Logo bitmap data (placeholder)
-   */
-  downloadLogo(logoName: string, _bitmap: Uint8Array): this {
+   * @param bitmap - 1-bit monochrome bitmap data (MSB first, row-major)
+   * @param options - Optional width and height (will be inferred from bitmap size if omitted)
+   */
+  downloadLogo(
+    logoName: string,
+    bitmap: Uint8Array,
+    options?: { width?: number; height?: number }
+  ): this {
+    const width = options?.width ?? 100;
+    const bytesPerRow = Math.ceil(width / 8);
+    const height = options?.height ?? Math.max(1, Math.floor(bitmap.length / bytesPerRow));
+    const totalBytes = bytesPerRow * height;
+
+    // Validate bitmap size
+    if (bitmap.length < totalBytes) {
+      this.logger.warn(
+        `CPCL logo bitmap size mismatch: expected ${totalBytes}, got ${bitmap.length}`
+      );
+    }
+
+    // Convert bitmap bytes to hex string (uppercase)
+    const hexData: string[] = [];
+    const limit = Math.min(bitmap.length, totalBytes);
+    for (let i = 0; i < limit; i++) {
+      const byte = bitmap[i]!;
+      hexData.push(byte.toString(16).padStart(2, '0').toUpperCase());
+    }
+
+    // CPCL macro definition with graphic data
     this.commands.push(`! DF ${logoName}`);
-    // TODO: Encode bitmap to CPCL format
-    this.logger.debug('CPCL logo download not fully implemented');
+    this.commands.push(`CG ${totalBytes} ${bytesPerRow} ${height} ${hexData.join('')}`);
     this.commands.push(`! DF`);
+    this.logger.debug(`CPCL logo downloaded: ${logoName} (${width}x${height})`);
     return this;
   }
 

package/src/drivers/ZplDriver.ts

@@ -428,18 +428,37 @@ export class ZplDriver {
   }
 
   /**
-   * Add image from raw bitmap
-   * Note: For best results, use pre-processed images. This is a placeholder for future implementation.
-   * @param _x - X position (placeholder)
-   * @param _y - Y position (placeholder)
-   * @param _width - Image width (placeholder)
-   * @param _height - Image height (placeholder)
-   * @param _bitmap - Binary bitmap data (placeholder)
-   */
-  image(_x: number, _y: number, _width: number, _height: number, _bitmap: Uint8Array): this {
-    // TODO: Implement proper ZPL image encoding using ^GFA or ^XG commands
-    // For now, this is a placeholder
-    this.logger.debug('ZPL image encoding not fully implemented');
+   * Add image from raw bitmap using ZPL ^GFA (Graphic Field) command.
+   * The bitmap should be 1-bit (monochrome) data where each bit represents a pixel.
+   * @param x - X position in dots
+   * @param y - Y position in dots
+   * @param width - Image width in pixels
+   * @param height - Image height in pixels
+   * @param bitmap - 1-bit monochrome bitmap data (MSB first, row-major)
+   */
+  image(x: number, y: number, width: number, height: number, bitmap: Uint8Array): this {
+    const bytesPerRow = Math.ceil(width / 8);
+    const totalBytes = bytesPerRow * height;
+
+    // Validate bitmap size
+    if (bitmap.length < totalBytes) {
+      this.logger.warn(
+        `ZPL image bitmap size mismatch: expected ${totalBytes}, got ${bitmap.length}`
+      );
+    }
+
+    // Convert bitmap bytes to hex string (uppercase)
+    const hexData: string[] = [];
+    const limit = Math.min(bitmap.length, totalBytes);
+    for (let i = 0; i < limit; i++) {
+      const byte = bitmap[i]!;
+      hexData.push(byte.toString(16).padStart(2, '0').toUpperCase());
+    }
+
+    this.commands.push(`^FO${x},${y}`);
+    this.commands.push(`^GFA,${totalBytes},${totalBytes},${bytesPerRow},${hexData.join('')}`);
+    this.commands.push('^FS');
+    this.logger.debug(`ZPL image encoded: ${width}x${height} at (${x},${y})`);
     return this;
   }
 

package/src/queue/PrintQueue.ts

@@ -149,6 +149,7 @@ export class PrintQueue implements IPrintQueue {
   private activeJobs = 0;
   private jobCounter = 0;
   private executor: JobExecutor | null = null;
+  private retryTimerId: ReturnType<typeof setTimeout> | null = null;
 
   /**
    * Creates a new PrintQueue instance
@@ -257,6 +258,12 @@ export class PrintQueue implements IPrintQueue {
    * Clear all pending jobs
    */
   clear(): void {
+    // Cancel pending retry timer if one is active
+    if (this.retryTimerId !== null) {
+      clearTimeout(this.retryTimerId);
+      this.retryTimerId = null;
+    }
+
     const pendingJobs = [...this.pendingQueue];
     for (const jobId of pendingJobs) {
       const job = this.jobs.get(jobId);
@@ -430,13 +437,14 @@ export class PrintQueue implements IPrintQueue {
         job.status = PrintJobStatus.PENDING;
 
         // Re-add to queue after delay
-        setTimeout(() => {
+        this.retryTimerId = setTimeout(() => {
           if (job.status === PrintJobStatus.PENDING) {
             this.insertByPriority(job.id, job.priority);
             if (this.config.autoProcess && !this.isPaused) {
               this.processQueue();
             }
           }
+          this.retryTimerId = null;
         }, this.config.retryDelay);
       } else {
         job.status = PrintJobStatus.FAILED;

package/src/services/ConnectionManager.ts

@@ -144,8 +144,9 @@ export class ConnectionManager
         this.emit('state-change', PrinterState.CONNECTING);
 
         const connectPromise = this.adapter.connect(deviceId);
+        let timeoutId: ReturnType<typeof setTimeout> | null = null;
         const timeoutPromise = new Promise<void>((_, reject) => {
-          setTimeout(() => {
+          timeoutId = setTimeout(() => {
             reject(
               new BluetoothPrintError(
                 ErrorCode.CONNECTION_TIMEOUT,
@@ -156,6 +157,9 @@ export class ConnectionManager
         });
 
         await Promise.race([connectPromise, timeoutPromise]);
+        if (timeoutId !== null) {
+          clearTimeout(timeoutId);
+        }
         this.state = PrinterState.CONNECTED;
         this.emit('state-change', PrinterState.CONNECTED);
         this.emit('connected', deviceId);
@@ -304,13 +308,13 @@ export class ConnectionManager
 
     this.isReconnecting = true;
     this.reconnectAttempts = 0;
-    this.attemptReconnect();
+    void this.attemptReconnect();
   }
 
   /**
    * Attempt to reconnect
    */
-  private attemptReconnect(): void {
+  private async attemptReconnect(): Promise<void> {
     if (!this.deviceId) {
       this.isReconnecting = false;
       return;
@@ -345,27 +349,25 @@ export class ConnectionManager
     this.state = PrinterState.CONNECTING;
     this.emit('state-change', PrinterState.CONNECTING);
 
-    this.adapter
-      .connect(deviceId)
-      .then(() => {
-        this.connLogger.info('Reconnected successfully');
-        this.isReconnecting = false;
-        this.reconnectAttempts = 0;
-        this.state = PrinterState.CONNECTED;
-        this.emit('state-change', PrinterState.CONNECTED);
-        this.emit('reconnected', deviceId);
+    try {
+      await this.adapter.connect(deviceId);
+      this.connLogger.info('Reconnected successfully');
+      this.isReconnecting = false;
+      this.reconnectAttempts = 0;
+      this.state = PrinterState.CONNECTED;
+      this.emit('state-change', PrinterState.CONNECTED);
+      this.emit('reconnected', deviceId);
 
-        if (this.config.heartbeatEnabled) {
-          this.startHeartbeat();
-        }
-      })
-      .catch(error => {
-        this.connLogger.warn(`Reconnect attempt ${this.reconnectAttempts} failed:`, error);
+      if (this.config.heartbeatEnabled) {
+        this.startHeartbeat();
+      }
+    } catch (error) {
+      this.connLogger.warn(`Reconnect attempt ${this.reconnectAttempts} failed:`, error);
 
-        this.reconnectTimer = setTimeout(() => {
-          this.attemptReconnect();
-        }, this.config.reconnectInterval);
-      });
+      this.reconnectTimer = setTimeout(() => {
+        void this.attemptReconnect();
+      }, this.config.reconnectInterval);
+    }
   }
 
   /**

package/src/services/PrinterStatus.ts

@@ -107,14 +107,18 @@ export class PrinterStatus {
       await writeFunc(queryCmd.buffer);
 
       // Set up timeout promise
+      let timeoutId: ReturnType<typeof setTimeout> | null = null;
       const timeoutPromise = new Promise<ArrayBuffer>((_, reject) => {
-        setTimeout(() => {
+        timeoutId = setTimeout(() => {
           reject(new BluetoothPrintError(ErrorCode.CONNECTION_TIMEOUT, 'Status query timed out'));
         }, timeout);
       });
 
       // Read response with timeout
       const response = await Promise.race([readFunc(), timeoutPromise]);
+      if (timeoutId !== null) {
+        clearTimeout(timeoutId);
+      }
 
       return this.parseStatus(new Uint8Array(response), includeRaw);
     } catch (error) {

package/src/services/interfaces/IConnectionManager.ts

@@ -55,4 +55,10 @@ export interface IConnectionManager {
    * @returns IPrinterAdapter - Printer adapter
    */
   getAdapter(): IPrinterAdapter;
+
+  /**
+   * Cleanup resources and destroy the connection manager
+   * Stops heartbeat, clears timers, and removes event listeners
+   */
+  destroy(): void;
 }

package/src/types.ts

@@ -75,6 +75,12 @@ export interface IPrinterAdapter {
    * @param callback - Function to call when the state changes
    */
   onStateChange?(callback: (state: PrinterState) => void): void;
+
+  /**
+   * Cleanup resources and destroy the adapter instance
+   * Removes all event listeners and releases resources
+   */
+  destroy?(): void;
 }
 
 /**