taro-bluetooth-print 2.10.2 → 2.11.0

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

@@ -75,6 +75,18 @@ export declare abstract class ChunkWriteStrategy<TOptions = void> {
      * Default: no-op. Override for platforms that support connection state polling.
      */
     protected checkConnection(_deviceId: string): Promise<void>;
+    /** Step size for increasing chunk size on success (bytes) */
+    private static readonly CHUNK_SIZE_STEP;
+    /** Delay backoff multiplier on failure */
+    private static readonly DELAY_BACKOFF_FACTOR;
+    /** Delay recovery divisor on success */
+    private static readonly DELAY_RECOVERY_FACTOR;
+    /** Timeout base (ms) for computeTimeoutMs */
+    private static readonly TIMEOUT_BASE_MS;
+    /** Timeout per-byte factor (ms) for computeTimeoutMs */
+    private static readonly TIMEOUT_PER_BYTE_MS;
+    /** Maximum timeout (ms) for computeTimeoutMs */
+    private static readonly TIMEOUT_MAX_MS;
     /**
      * Compute chunk write timeout based on chunk size.
      * Override to customize timeout formula per platform.

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

@@ -46,7 +46,7 @@ export declare class ReactNativeAdapter extends BaseAdapter implements IPrinterA
      *
      * @param options - Configuration options
      * @param options.bleManager - BLE Manager instance (e.g., from react-native-ble-plx)
-     * @throws {Error} If bleManager is not provided or not supported
+     * @throws {BluetoothPrintError} If bleManager is not provided or not supported
      */
     constructor(options: {
         bleManager: BLEManager;

package/dist/types/errors/baseError.d.ts

@@ -18,7 +18,10 @@ export declare enum ErrorCode {
     ENCODING_NOT_SUPPORTED = "ENCODING_NOT_SUPPORTED",
     INVALID_IMAGE_DATA = "INVALID_IMAGE_DATA",
     INVALID_QR_DATA = "INVALID_QR_DATA",
-    PLATFORM_NOT_SUPPORTED = "PLATFORM_NOT_SUPPORTED"
+    PLATFORM_NOT_SUPPORTED = "PLATFORM_NOT_SUPPORTED",
+    QUEUE_FULL = "QUEUE_FULL",
+    QUEUE_JOB_NOT_FOUND = "QUEUE_JOB_NOT_FOUND",
+    PREVIEW_FAILED = "PREVIEW_FAILED"
 }
 /**
  * Custom error class for Bluetooth printing operations

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

@@ -73,6 +73,8 @@ export declare class PrintHistory {
     private readonly logger;
     private readonly entries;
     private counter;
+    /** Default maximum number of history entries */
+    private static readonly DEFAULT_MAX_ENTRIES;
     private readonly maxEntries;
     /**
      * Creates a new PrintHistory instance

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

@@ -268,6 +268,8 @@ export declare class TemplateEngine implements ITemplateEngine {
     private readonly parser;
     private readonly renderer;
     private readonly templates;
+    /** Default paper width in characters (58mm paper ≈ 48 chars) */
+    private static readonly DEFAULT_PAPER_WIDTH;
     /**
      * Creates a new TemplateEngine instance
      */

package/dist/types/template/engines/TemplateRenderer.d.ts

@@ -11,6 +11,8 @@ export declare class TemplateRenderer {
     private readonly driver;
     private readonly parser;
     private readonly paperWidth;
+    /** Default paper width in characters (58mm paper ≈ 48 chars) */
+    private static readonly DEFAULT_PAPER_WIDTH;
     constructor(paperWidth?: number);
     /**
      * Render a receipt template

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taro-bluetooth-print",
-  "version": "2.10.2",
+  "version": "2.11.0",
   "description": "Taro 蓝牙打印库 v2.6 - 轻量级、高性能、跨平台支持微信、支付宝、百度、字节跳动小程序及H5 Web Bluetooth",
   "type": "module",
   "main": "dist/index.cjs.js",

package/src/adapters/ChunkWriteStrategy.ts

@@ -116,12 +116,31 @@ export abstract class ChunkWriteStrategy<TOptions = void> {
     // default: no connection check
   }
 
+  /** Step size for increasing chunk size on success (bytes) */
+  private static readonly CHUNK_SIZE_STEP = 5;
+  /** Delay backoff multiplier on failure */
+  private static readonly DELAY_BACKOFF_FACTOR = 1.5;
+  /** Delay recovery divisor on success */
+  private static readonly DELAY_RECOVERY_FACTOR = 1.2;
+  /** Timeout base (ms) for computeTimeoutMs */
+  private static readonly TIMEOUT_BASE_MS = 1000;
+  /** Timeout per-byte factor (ms) for computeTimeoutMs */
+  private static readonly TIMEOUT_PER_BYTE_MS = 5;
+  /** Maximum timeout (ms) for computeTimeoutMs */
+  private static readonly TIMEOUT_MAX_MS = 10000;
+
   /**
    * Compute chunk write timeout based on chunk size.
    * Override to customize timeout formula per platform.
    */
   protected computeTimeoutMs(chunkLength: number): number {
-    return Math.max(1000, Math.min(10000, 1000 + chunkLength * 5));
+    return Math.max(
+      ChunkWriteStrategy.TIMEOUT_BASE_MS,
+      Math.min(
+        ChunkWriteStrategy.TIMEOUT_MAX_MS,
+        ChunkWriteStrategy.TIMEOUT_BASE_MS + chunkLength * ChunkWriteStrategy.TIMEOUT_PER_BYTE_MS
+      )
+    );
   }
 
   /**
@@ -218,8 +237,11 @@ export abstract class ChunkWriteStrategy<TOptions = void> {
         consecutiveFailures = 0;
 
         if (successCount % successThreshold === 0 && currentChunkSize < maxChunkSize) {
-          currentChunkSize = Math.min(maxChunkSize, currentChunkSize + 5);
-          baseDelay = Math.max(baseDelay / 1.2, delay);
+          currentChunkSize = Math.min(
+            maxChunkSize,
+            currentChunkSize + ChunkWriteStrategy.CHUNK_SIZE_STEP
+          );
+          baseDelay = Math.max(baseDelay / ChunkWriteStrategy.DELAY_RECOVERY_FACTOR, delay);
           totalChunks =
             Math.ceil((data.length - i - currentChunkSize) / currentChunkSize) + chunkNum;
           this.logger.debug(`Increased chunk size to ${currentChunkSize}, delay to ${baseDelay}`);
@@ -228,8 +250,11 @@ export abstract class ChunkWriteStrategy<TOptions = void> {
         consecutiveFailures++;
 
         if (consecutiveFailures >= failureThreshold && currentChunkSize > minChunkSize) {
-          currentChunkSize = Math.max(minChunkSize, currentChunkSize - 5);
-          baseDelay = Math.min(baseDelay * 1.5, maxDelay);
+          currentChunkSize = Math.max(
+            minChunkSize,
+            currentChunkSize - ChunkWriteStrategy.CHUNK_SIZE_STEP
+          );
+          baseDelay = Math.min(baseDelay * ChunkWriteStrategy.DELAY_BACKOFF_FACTOR, maxDelay);
           totalChunks =
             Math.ceil((data.length - i - currentChunkSize) / currentChunkSize) + chunkNum;
           this.logger.debug(`Decreased chunk size to ${currentChunkSize}, delay to ${baseDelay}`);

package/src/adapters/ReactNativeAdapter.ts

@@ -193,13 +193,14 @@ export class ReactNativeAdapter extends BaseAdapter implements IPrinterAdapter {
    *
    * @param options - Configuration options
    * @param options.bleManager - BLE Manager instance (e.g., from react-native-ble-plx)
-   * @throws {Error} If bleManager is not provided or not supported
+   * @throws {BluetoothPrintError} If bleManager is not provided or not supported
    */
   constructor(options: { bleManager: BLEManager }) {
     super();
 
     if (!options?.bleManager) {
-      throw new Error(
+      throw new BluetoothPrintError(
+        ErrorCode.INVALID_CONFIGURATION,
         'ReactNativeAdapter requires a bleManager instance (e.g., react-native-ble-plx). ' +
           'Please pass { bleManager: yourBleManager } in the constructor.'
       );

package/src/config/PrinterConfigManager.ts

@@ -29,6 +29,7 @@
  */
 
 import { Logger } from '@/utils/logger';
+import { BluetoothPrintError, ErrorCode } from '@/errors/baseError';
 
 /**
  * Print configuration for a device
@@ -338,7 +339,7 @@ export class PrinterConfigManager {
   setDefaultPrinter(id: string): void {
     const printer = this.printers.get(id);
     if (!printer) {
-      throw new Error(`Printer not found: ${id}`);
+      throw new BluetoothPrintError(ErrorCode.DEVICE_NOT_FOUND, `Printer not found: ${id}`);
     }
 
     // Unset other defaults

package/src/device/DeviceManager.ts

@@ -13,6 +13,8 @@
  */
 
 import Taro from '@tarojs/taro';
+
+import { BluetoothPrintError, ErrorCode } from '@/errors/baseError';
 import { Logger } from '@/utils/logger';
 import { emitAndThrow } from '@/utils/normalizeError';
 import { EventEmitter } from '@/core/EventEmitter';
@@ -214,7 +216,7 @@ export class DeviceManager extends EventEmitter<DeviceManagerEvents> implements
       const services = servicesRes.services;
 
       if (services.length === 0) {
-        throw new Error('No services found on device');
+        throw new BluetoothPrintError(ErrorCode.SERVICE_NOT_FOUND, 'No services found on device');
       }
 
       let serviceId: string | undefined;
@@ -238,7 +240,10 @@ export class DeviceManager extends EventEmitter<DeviceManagerEvents> implements
       }
 
       if (!serviceId || !characteristicId) {
-        throw new Error('No writable characteristic found');
+        throw new BluetoothPrintError(
+          ErrorCode.CHARACTERISTIC_NOT_FOUND,
+          'No writable characteristic found'
+        );
       }
 
       const device = this.discoveredDevices.get(deviceId);

package/src/device/DiscoveryService.ts

@@ -1,4 +1,3 @@
-/* eslint-disable @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-call */
 /**
  * @fileoverview DiscoveryService uses dynamic adapter loading for platform-specific Bluetooth operations.
  * The platformAdapter field is typed as `BaseAdapter | undefined` because different adapters
@@ -216,9 +215,6 @@ export class DiscoveryService extends EventEmitter<DiscoveryEvents> {
     }
   }
 
-  // 监听 platform adapter 的设备发现回调（预留扩展点）
-  // private processDevice(deviceInfo: any): void { ... }
-
   /**
    * 获取过滤和排序后的设备列表
    */

package/src/errors/baseError.ts

@@ -32,6 +32,13 @@ export enum ErrorCode {
 
   // Platform errors
   PLATFORM_NOT_SUPPORTED = 'PLATFORM_NOT_SUPPORTED',
+
+  // Queue errors
+  QUEUE_FULL = 'QUEUE_FULL',
+  QUEUE_JOB_NOT_FOUND = 'QUEUE_JOB_NOT_FOUND',
+
+  // Preview errors
+  PREVIEW_FAILED = 'PREVIEW_FAILED',
 }
 
 /**

package/src/factory/PrinterFactory.ts

@@ -12,6 +12,7 @@ import { PrintJobManager } from '@/services/PrintJobManager';
 import { CommandBuilder } from '@/services/CommandBuilder';
 import type { IPrinterAdapter } from '@/types';
 import type { IConnectionManager, IPrintJobManager, ICommandBuilder } from '@/services/interfaces';
+import { BluetoothPrintError, ErrorCode } from '@/errors/baseError';
 
 /**
  * Options for creating a BluetoothPrinter via the factory
@@ -127,7 +128,8 @@ export async function createWebBluetoothPrinter(): Promise<BluetoothPrinter> {
     const adapter = new WebBluetoothAdapter();
     return createBluetoothPrinter({ adapter });
   } catch {
-    throw new Error(
+    throw new BluetoothPrintError(
+      ErrorCode.PLATFORM_NOT_SUPPORTED,
       'Failed to dynamically import WebBluetoothAdapter. ' +
         'This adapter is only available in browser environments that support the Web Bluetooth API.'
     );

package/src/preview/PreviewRenderer.ts

@@ -13,6 +13,7 @@
  */
 
 import { Logger } from '@/utils/logger';
+import { BluetoothPrintError, ErrorCode } from '@/errors/baseError';
 
 /**
  * Preview options
@@ -141,7 +142,7 @@ export class PreviewRenderer implements IPreviewRenderer {
 
       const ctx = canvas.getContext('2d');
       if (!ctx) {
-        throw new Error('Failed to get canvas context');
+        throw new BluetoothPrintError(ErrorCode.PREVIEW_FAILED, 'Failed to get canvas context');
       }
 
       this.drawToContext(ctx, lines, pixelWidth, estimatedHeight, opts);
@@ -415,7 +416,7 @@ export class PreviewRenderer implements IPreviewRenderer {
 
     const ctx = canvas.getContext('2d');
     if (!ctx) {
-      throw new Error('Failed to get canvas context');
+      throw new BluetoothPrintError(ErrorCode.PREVIEW_FAILED, 'Failed to get canvas context');
     }
 
     this.drawToContext(ctx, lines, width, height, opts);

package/src/queue/PrintQueue.ts

@@ -13,6 +13,7 @@
  */
 
 import { Logger } from '@/utils/logger';
+import { BluetoothPrintError, ErrorCode } from '@/errors/baseError';
 import { normalizeError } from '@/utils/normalizeError';
 import { EventEmitter } from '@/core/EventEmitter';
 
@@ -170,7 +171,7 @@ export class PrintQueue extends EventEmitter<PrintQueueEvents> implements IPrint
    */
   add(data: Uint8Array, options?: Partial<PrintJob>): string {
     if (this.jobs.size >= this.config.maxSize) {
-      throw new Error('Queue is full');
+      throw new BluetoothPrintError(ErrorCode.QUEUE_FULL, 'Queue is full');
     }
 
     const id = this.generateJobId();

package/src/services/CloudPrintManager.ts

@@ -12,6 +12,7 @@
 
 import { EventEmitter } from '@/core/EventEmitter';
 import { Logger } from '@/utils/logger';
+import { BluetoothPrintError, ErrorCode } from '@/errors/baseError';
 import { normalizeError } from '@/utils/normalizeError';
 
 export interface CloudPrintOptions {
@@ -233,7 +234,7 @@ export class CloudPrintManager extends EventEmitter<CloudPrintEvents> {
    */
   print(job: PrintJob): void {
     if (!this.isConnected || !this.ws || this.ws.readyState !== WebSocket.OPEN) {
-      throw new Error('Not connected to server');
+      throw new BluetoothPrintError(ErrorCode.DEVICE_DISCONNECTED, 'Not connected to server');
     }
 
     const message = {

package/src/services/PrintHistory.ts

@@ -92,13 +92,16 @@ export class PrintHistory {
   private readonly logger = Logger.scope('PrintHistory');
   private readonly entries: Map<string, PrintHistoryEntry> = new Map();
   private counter = 0;
+  /** Default maximum number of history entries */
+  private static readonly DEFAULT_MAX_ENTRIES = 1000;
+
   private readonly maxEntries: number;
 
   /**
    * Creates a new PrintHistory instance
    * @param maxEntries - Maximum number of entries to keep (default: 1000)
    */
-  constructor(maxEntries = 1000) {
+  constructor(maxEntries = PrintHistory.DEFAULT_MAX_ENTRIES) {
     this.maxEntries = maxEntries;
   }
 

package/src/services/PrintJobManager.ts

@@ -297,7 +297,10 @@ export class PrintJobManager implements IPrintJobManager {
           `Loaded job ${this.jobId}: offset=${this.jobOffset}/${this.jobBuffer.length}`
         );
       } else {
-        throw new Error(`Job state not found for ${jobId}`);
+        throw new BluetoothPrintError(
+          ErrorCode.QUEUE_JOB_NOT_FOUND,
+          `Job state not found for ${jobId}`
+        );
       }
     } catch (error) {
       this.logger.error(`Failed to load job state for ${jobId}:`, error);

package/src/services/PrintScheduler.ts

@@ -6,6 +6,7 @@
 import { EventEmitter } from '../core/EventEmitter';
 import { generateUUID } from '../utils/uuid';
 import { normalizeError } from '../utils/normalizeError';
+import { BluetoothPrintError, ErrorCode } from '@/errors/baseError';
 
 export interface ScheduledPrint {
   id: string;
@@ -57,7 +58,7 @@ export function parseCronExpression(cron: string): {
 } {
   const parts = cron.trim().split(/\s+/);
   if (parts.length !== 5) {
-    throw new Error('Invalid cron expression');
+    throw new BluetoothPrintError(ErrorCode.INVALID_CONFIGURATION, 'Invalid cron expression');
   }
 
   const [minPart, hourPart, dayPart, monthPart, dowPart] = parts as [
@@ -143,7 +144,10 @@ export function getNextCronRun(cron: string, fromTime: number = Date.now()): num
     date.setMinutes(date.getMinutes() + 1);
   }
 
-  throw new Error('Cannot find next run time within one year');
+  throw new BluetoothPrintError(
+    ErrorCode.INVALID_CONFIGURATION,
+    'Cannot find next run time within one year'
+  );
 }
 
 export function getNextIntervalRun(interval: number, fromTime: number = Date.now()): number {
@@ -173,7 +177,10 @@ export class PrintScheduler extends EventEmitter<ScheduleEvents> {
     const executeAt = onceAt instanceof Date ? onceAt.getTime() : onceAt;
 
     if (!executeAt || executeAt <= Date.now()) {
-      throw new Error('onceAt must be a future date');
+      throw new BluetoothPrintError(
+        ErrorCode.INVALID_CONFIGURATION,
+        'onceAt must be a future date'
+      );
     }
 
     const job: ScheduledPrint = {
@@ -198,7 +205,10 @@ export class PrintScheduler extends EventEmitter<ScheduleEvents> {
     const { cronExpression, repeatInterval, ...rest } = options;
 
     if (!cronExpression && !repeatInterval) {
-      throw new Error('Either cronExpression or repeatInterval is required');
+      throw new BluetoothPrintError(
+        ErrorCode.INVALID_CONFIGURATION,
+        'Either cronExpression or repeatInterval is required'
+      );
     }
 
     const job: ScheduledPrint = {

package/src/template/TemplateEngine.ts

@@ -293,10 +293,13 @@ export class TemplateEngine implements ITemplateEngine {
   private readonly renderer: TemplateRenderer;
   private readonly templates: Map<string, TemplateDefinition> = new Map();
 
+  /** Default paper width in characters (58mm paper ≈ 48 chars) */
+  private static readonly DEFAULT_PAPER_WIDTH = 48;
+
   /**
    * Creates a new TemplateEngine instance
    */
-  constructor(paperWidth = 48) {
+  constructor(paperWidth = TemplateEngine.DEFAULT_PAPER_WIDTH) {
     this.parser = new TemplateParser();
     this.renderer = new TemplateRenderer(paperWidth);
   }

package/src/template/engines/TemplateRenderer.ts

@@ -118,7 +118,10 @@ export class TemplateRenderer {
   private readonly parser: TemplateParser;
   private readonly paperWidth: number;
 
-  constructor(paperWidth = 48) {
+  /** Default paper width in characters (58mm paper ≈ 48 chars) */
+  private static readonly DEFAULT_PAPER_WIDTH = 48;
+
+  constructor(paperWidth = TemplateRenderer.DEFAULT_PAPER_WIDTH) {
     this.paperWidth = paperWidth;
     this.formatter = new TextFormatter();
     this.barcodeGenerator = new BarcodeGenerator();
@@ -363,21 +366,16 @@ export class TemplateRenderer {
     }
 
     for (let i = 0; i < items.length; i++) {
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-assignment
-      const itemData: any = items[i];
+      const itemData: Record<string, unknown> = items[i] as Record<string, unknown>;
 
       // Create iteration context with item and optionally index
       const context: Record<string, unknown> = {
         ...data,
-        /* eslint-disable @typescript-eslint/no-unsafe-assignment */
         [loop.itemVar]: itemData,
-        /* eslint-enable @typescript-eslint/no-unsafe-assignment */
       };
 
       if (loop.indexVar) {
-        /* eslint-disable @typescript-eslint/no-unsafe-assignment */
         context[loop.indexVar] = i;
-        /* eslint-enable @typescript-eslint/no-unsafe-assignment */
       }
 
       // Render each element in the loop

package/src/utils/image.ts

@@ -5,6 +5,8 @@
  * Supports multiple dithering algorithms and image preprocessing.
  */
 
+import { BluetoothPrintError, ErrorCode } from '@/errors/baseError';
+
 export class ImageProcessing {
   // Pre-computed Bayer matrices for ordered dithering
   private static readonly BAYER_MATRIX_2: ReadonlyArray<ReadonlyArray<number>> = [
@@ -84,7 +86,8 @@ export class ImageProcessing {
     }
 
     if (data.length !== width * height * 4) {
-      throw new Error(
+      throw new BluetoothPrintError(
+        ErrorCode.INVALID_IMAGE_DATA,
         `Invalid image data length: expected ${width * height * 4}, got ${data.length}`
       );
     }

package/src/utils/outputLimiter.ts

@@ -151,10 +151,13 @@ export async function batchProcess<T, R>(
       const batchResults = await processor(batch, batchIndex);
       results.push(...batchResults);
     } catch (error) {
-      // Log the error and continue processing subsequent batches
-      console.error(`[batchProcess] Error processing batch ${batchIndex}/${totalBatches}:`, error);
-      // Re-throw so the caller can handle the failure
-      throw error;
+      // Log the error and re-throw so the caller can handle the failure
+      const normalizedError = error instanceof Error ? error : new Error(String(error));
+      console.error(
+        `[batchProcess] Error processing batch ${batchIndex}/${totalBatches}:`,
+        normalizedError.message
+      );
+      throw normalizedError;
     }
 
     // 添加小延迟，避免阻塞