taro-bluetooth-print 2.13.0 → 2.15.0

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

@@ -1,23 +1,14 @@
-import { BluetoothPrintError } from './baseError';
-/**
- * Print job-related error codes
- */
+import { BluetoothPrintError } from './BaseError';
 export declare 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
+ * PrintJobError - Specialized error for print job failures.
  *
  * @example
  * ```typescript
@@ -31,12 +22,5 @@ export declare enum PrintJobErrorCode {
 export declare class PrintJobError extends BluetoothPrintError {
     readonly jobErrorCode: PrintJobErrorCode;
     constructor(jobErrorCode: PrintJobErrorCode, message: string, originalError?: Error);
-    /**
-     * Converts PrintJobErrorCode to base ErrorCode
-     */
-    private static _toBaseCode;
-    /**
-     * Checks if an error is a print job error
-     */
     static isPrintJobError(error: unknown): error is PrintJobError;
 }

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

@@ -3,7 +3,7 @@
  *
  * @packageDocumentation
  */
-export { BluetoothPrintError, ErrorCode } from './baseError';
+export { BluetoothPrintError, ErrorCode } from './BaseError';
 export { ConnectionError, ConnectionErrorCode } from './ConnectionError';
 export { PrintJobError, PrintJobErrorCode } from './PrintJobError';
 export { CommandBuildError, CommandBuildErrorCode } from './CommandBuildError';

package/dist/types/index.d.ts

@@ -12,6 +12,7 @@ export { TaroAdapter } from './adapters/TaroAdapter';
 export { AlipayAdapter } from './adapters/AlipayAdapter';
 export { BaiduAdapter } from './adapters/BaiduAdapter';
 export { ByteDanceAdapter } from './adapters/ByteDanceAdapter';
+export { QQAdapter } from './adapters/QQAdapter';
 export { WebBluetoothAdapter } from './adapters/WebBluetoothAdapter';
 export { AdapterFactory } from './adapters/AdapterFactory';
 export { BaseAdapter } from './adapters/BaseAdapter';
@@ -41,7 +42,7 @@ 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';
-export { BluetoothPrintError, ErrorCode } from './errors/baseError';
+export { BluetoothPrintError, ErrorCode } from './errors/BaseError';
 export { ConnectionError, ConnectionErrorCode } from './errors/ConnectionError';
 export { PrintJobError, PrintJobErrorCode } from './errors/PrintJobError';
 export { CommandBuildError, CommandBuildErrorCode } from './errors/CommandBuildError';
@@ -51,5 +52,5 @@ export type { PrinterConfig, AdapterConfig, DriverConfig, LoggingConfig, } from
 export { PrinterConfigManager, printerConfigManager } from './config/PrinterConfigManager';
 export type { SavedPrinter, GlobalConfig, IConfigStorage } from './config/PrinterConfigManager';
 export { createLoggingPlugin, createRetryPlugin } from './plugins';
-export type { Plugin, PluginHooks, PluginOptions, PluginFactory } from './plugins/types';
+export type { Plugin, PluginHooks, PluginOptions, PluginFactory } from './plugins/PluginTypes';
 export * from './types';

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

@@ -1,5 +1,5 @@
-import { Plugin, PluginHooks, PluginOptions } from './types';
-import { BluetoothPrintError } from '../errors/baseError';
+import { Plugin, PluginHooks, PluginOptions } from './PluginTypes';
+import { BluetoothPrintError } from '../errors/BaseError';
 import { PrinterState } from '../types';
 /**
  * Manages plugins for BluetoothPrinter

package/dist/types/plugins/{types.d.ts → PluginTypes.d.ts}

@@ -1,4 +1,4 @@
-import { BluetoothPrintError } from '../errors/baseError';
+import { BluetoothPrintError } from '../errors/BaseError';
 import { PrinterState } from '../types';
 /**
  * Plugin lifecycle hooks

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

@@ -1,4 +1,4 @@
-import { PluginFactory, PluginOptions } from '../types';
+import { PluginFactory, PluginOptions } from '../PluginTypes';
 import { LogLevel } from '../../utils/logger';
 export interface LoggingPluginOptions extends PluginOptions {
     /** Log level (default: DEBUG) */

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

@@ -1,5 +1,5 @@
-import { PluginFactory, PluginOptions } from '../types';
-import { ErrorCode } from '../../errors/baseError';
+import { PluginFactory, PluginOptions } from '../PluginTypes';
+import { ErrorCode } from '../../errors/BaseError';
 export interface RetryPluginOptions extends PluginOptions {
     /** Maximum retry attempts (default: 3) */
     maxRetries?: number;

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

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

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

@@ -6,178 +6,35 @@ import { BarcodeOptions } from '../barcode';
  * Command Builder implementation
  */
 export declare class CommandBuilder implements ICommandBuilder {
-    private driver;
-    private buffer;
-    private _cachedBuffer;
-    private readonly logger;
+    private readonly driver;
     private readonly formatter;
     private readonly barcodeGenerator;
-    /**
-     * Creates a new CommandBuilder instance
-     *
-     * @param driver - Printer driver instance
-     */
+    private readonly logger;
+    private buffer;
+    private cachedBuffer;
     constructor(driver?: IPrinterDriver);
     /**
-     * Invalidates the cached combined buffer.
-     * Must be called whenever the internal buffer array is modified.
-     */
-    private invalidateCache;
-    /**
-     * Adds text to the print queue
-     *
-     * @param content - Text content
-     * @param encoding - Text encoding
-     * @returns this - For method chaining
+     * Push pre-built command chunks and invalidate the concat cache.
+     * Centralizes what was previously duplicated in every mutating method.
      */
+    private pushCommands;
     text(content: string, encoding?: string): this;
-    /**
-     * Adds line feeds to the print queue
-     *
-     * @param lines - Number of lines to feed
-     * @returns this - For method chaining
-     */
     feed(lines?: number): this;
-    /**
-     * Adds a paper cut command to the print queue
-     *
-     * @returns this - For method chaining
-     */
     cut(): this;
-    /**
-     * Adds an image to the print queue
-     *
-     * @param data - Image data as Uint8Array
-     * @param width - Image width
-     * @param height - Image height
-     * @returns this - For method chaining
-     */
     image(data: Uint8Array, width: number, height: number): this;
-    /**
-     * Adds a QR code to the print queue
-     *
-     * @param content - QR code content
-     * @param options - QR code options
-     * @returns this - For method chaining
-     */
     qr(content: string, options?: IQrOptions): this;
     /**
-     * Clears the print queue
-     *
-     * @returns this - For method chaining
+     * Clears the print queue and re-initializes the printer.
      */
     clear(): this;
-    /**
-     * Sets text alignment
-     *
-     * @param alignment - Text alignment (left, center, right)
-     * @returns this - For method chaining
-     *
-     * @example
-     * ```typescript
-     * builder.align(TextAlign.CENTER).text('Centered Text');
-     * ```
-     */
     align(alignment: TextAlign): this;
-    /**
-     * Sets character size (width and height scale)
-     *
-     * @param width - Width scale factor (1-8)
-     * @param height - Height scale factor (1-8)
-     * @returns this - For method chaining
-     *
-     * @example
-     * ```typescript
-     * builder.setSize(2, 2).text('Double Size');
-     * ```
-     */
     setSize(width: number, height: number): this;
-    /**
-     * Sets bold text mode
-     *
-     * @param enabled - Enable or disable bold
-     * @returns this - For method chaining
-     *
-     * @example
-     * ```typescript
-     * builder.setBold(true).text('Bold Text').setBold(false);
-     * ```
-     */
     setBold(enabled: boolean): this;
-    /**
-     * Sets underline text mode
-     *
-     * @param enabled - Enable or disable underline
-     * @returns this - For method chaining
-     *
-     * @example
-     * ```typescript
-     * builder.setUnderline(true).text('Underlined').setUnderline(false);
-     * ```
-     */
     setUnderline(enabled: boolean): this;
-    /**
-     * Sets inverse printing mode (white on black)
-     *
-     * @param enabled - Enable or disable inverse
-     * @returns this - For method chaining
-     *
-     * @example
-     * ```typescript
-     * builder.setInverse(true).text('Inverse Text').setInverse(false);
-     * ```
-     */
     setInverse(enabled: boolean): this;
-    /**
-     * Sets multiple text style properties at once
-     *
-     * @param style - Text style configuration
-     * @returns this - For method chaining
-     *
-     * @example
-     * ```typescript
-     * builder.setStyle({ align: TextAlign.CENTER, bold: true, heightScale: 2 });
-     * ```
-     */
     setStyle(style: TextStyle): this;
-    /**
-     * Resets all text formatting to default
-     *
-     * @returns this - For method chaining
-     *
-     * @example
-     * ```typescript
-     * builder.resetStyle().text('Normal Text');
-     * ```
-     */
     resetStyle(): this;
-    /**
-     * Adds a 1D barcode to the print queue
-     *
-     * @param content - Barcode content/data
-     * @param options - Barcode options (format, height, width, showText, textPosition)
-     * @returns this - For method chaining
-     *
-     * @example
-     * ```typescript
-     * builder.barcode('1234567890128', {
-     *   format: BarcodeFormat.EAN13,
-     *   height: 80,
-     *   showText: true
-     * });
-     * ```
-     */
     barcode(content: string, options: BarcodeOptions): this;
-    /**
-     * Gets the current buffer
-     *
-     * @returns Uint8Array - Current print buffer
-     */
     getBuffer(): Uint8Array;
-    /**
-     * Gets the total number of bytes in the buffer
-     *
-     * @returns number - Total bytes
-     */
     getTotalBytes(): number;
 }

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

@@ -1,6 +1,6 @@
 import { IPrinterAdapter, PrinterState } from '../types';
 import { IConnectionManager } from './interfaces';
-import { BluetoothPrintError } from '../errors/baseError';
+import { BluetoothPrintError } from '../errors/BaseError';
 import { EventEmitter } from '../core/EventEmitter';
 /**
  * Connection manager configuration
@@ -75,6 +75,11 @@ export declare class ConnectionManager extends EventEmitter<ConnectionManagerEve
         retries?: number;
         timeout?: number;
     }): Promise<void>;
+    /**
+     * Map a raw connect error to a typed BluetoothPrintError, distinguishing
+     * timeouts from generic failures.
+     */
+    private classifyConnectError;
     /**
      * Disconnects from the current device
      */

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

@@ -42,23 +42,23 @@ export interface PrintHistoryStats {
     failed: number;
     /** Cancelled jobs */
     cancelled: number;
-    /** Average duration in ms */
+    /** Average duration in milliseconds */
     avgDuration: number;
-    /** Total bytes printed */
+    /** Total bytes */
     totalBytes: number;
-    /** Success rate */
+    /** Success rate (0-100) */
     successRate: number;
 }
 /**
- * Query options for history
+ * History query options
  */
 export interface HistoryQueryOptions {
     /** Start date filter */
     startDate?: number;
     /** End date filter */
     endDate?: number;
-    /** Status filter */
-    status?: PrintJobStatus | PrintJobStatus[];
+    /** Status filter (single or array) */
+    status?: PrintJobStatus | 'unknown' | Array<PrintJobStatus | 'unknown'>;
     /** Device ID filter */
     deviceId?: string;
     /** Limit results */
@@ -67,17 +67,17 @@ export interface HistoryQueryOptions {
     offset?: number;
 }
 /**
- * Print History Service
+ * Print History Service.
+ *
+ * Backed by a {@link BoundedOrderedMap} that automatically evicts the oldest
+ * entries once capacity is exceeded.
  */
 export declare class PrintHistory {
     private readonly logger;
-    private readonly entries;
+    private readonly store;
     private counter;
     /** Default maximum number of history entries */
     private static readonly DEFAULT_MAX_ENTRIES;
-    private readonly maxEntries;
-    /** Ordered index of entry IDs by createdAt (ascending) for fast pruning */
-    private readonly orderedIds;
     /**
      * Creates a new PrintHistory instance
      * @param maxEntries - Maximum number of entries to keep (default: 1000)
@@ -131,27 +131,14 @@ export declare class PrintHistory {
      */
     export(): string;
     /**
-     * Import history from JSON
+     * Import history from JSON. Rebuilds the underlying ordered index after bulk insert.
      */
     import(json: string): number;
+    /** Total number of entries currently retained (≤ maxEntries). */
+    get size(): number;
     /**
      * Generate unique ID
      */
     private generateId;
-    /**
-     * Enforce maximum entries limit using the ordered index.
-     * Instead of full-sorting, we use the pre-sorted index to find and remove the oldest entries.
-     */
-    private enforceMaxEntries;
-    /**
-     * Binary search to find the insertion position for a given timestamp
-     * in the orderedIds array (ascending order).
-     */
-    private findInsertPosition;
-    /**
-     * Rebuild the ordered index from the entries map.
-     * Used after bulk operations like import.
-     */
-    private rebuildIndex;
 }
 export declare const printHistory: PrintHistory;

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

@@ -1,169 +1,53 @@
 import { IAdapterOptions } from '../types';
 import { IPrintJobManager, IConnectionManager } from './interfaces';
-/**
- * Print Job Manager implementation
- */
+export type JobState = 'in-progress' | 'paused' | 'completed' | 'cancelled';
 export declare class PrintJobManager implements IPrintJobManager {
-    /** Instance-level job state storage (per-printer support) */
-    private instanceJobStateStore;
-    /** Static job state store for backward compatibility */
-    private static _jobStateStore;
-    /** Auto-cleanup timer for expired job states */
-    private static _cleanupTimer;
-    private static readonly CLEANUP_INTERVAL_MS;
-    private static readonly DEFAULT_EXPIRY_MS;
-    /** Start the auto-cleanup timer if not already running */
-    private static ensureCleanupTimer;
-    /**
-     * Get the static job state store (for backward compatibility)
-     * @deprecated Use instance-level store instead for multi-printer support
-     */
-    private static get jobStateStore();
-    private adapter;
-    private connectionManager;
+    private readonly instanceJobStateStore;
+    private static staticJobStateStore;
+    private static cleanupTimer;
+    private readonly connectionManager;
+    private readonly adapter;
     private jobBuffer;
     private jobOffset;
-    private _isPaused;
-    private _isInProgress;
+    private paused;
+    private inProgress;
     private adapterOptions;
-    private readonly logger;
-    private onProgress?;
     private jobId;
+    private onProgress?;
     private onJobStateChange?;
-    /**
-     * Sets the progress callback
-     *
-     * @param callback - Progress callback function
-     */
-    setProgressCallback(callback?: (sent: number, total: number) => void): void;
-    /**
-     * Sets the job state change callback
-     *
-     * @param callback - Job state change callback function
-     */
-    setJobStateCallback(callback?: (state: 'in-progress' | 'paused' | 'completed' | 'cancelled') => void): void;
-    /**
-     * Creates a new PrintJobManager instance
-     *
-     * @param connectionManager - Connection manager instance
-     */
+    private readonly logger;
     constructor(connectionManager: IConnectionManager);
+    setProgressCallback(callback?: (sent: number, total: number) => void): void;
+    setJobStateCallback(callback?: (state: JobState) => void): void;
     /**
-     * Starts a print job
-     *
-     * @param buffer - Print data buffer
-     * @param options - Print job options
-     * @returns Promise<void>
+     * Wraps a raw error as BluetoothPrintError if it isn't already one.
      */
+    private wrapError;
     start(buffer: Uint8Array, options?: {
         jobId?: string;
     }): Promise<void>;
-    /**
-     * Resumes a paused print job
-     *
-     * @param jobId - Job ID to resume (optional)
-     * @returns Promise<void>
-     */
     resume(jobId?: string): Promise<void>;
-    /**
-     * Cancels the current print job
-     */
     cancel(): void;
-    /**
-     * Generates a unique job ID
-     *
-     * @returns string - Unique job ID
-     */
+    pause(): void;
+    isPaused(): boolean;
+    isInProgress(): boolean;
+    remaining(): number;
+    setOptions(options: IAdapterOptions): void;
+    destroy(): void;
     private generateJobId;
-    /**
-     * Saves the current job state for resume later.
-     *
-     * Uses instance-level storage by default. Falls back to static store
-     * for backward compatibility.
-     */
     private saveJobState;
-    /**
-     * Loads a saved job state
-     *
-     * @param jobId - Job ID to load
-     */
     private loadJobState;
-    /**
-     * Clears the current job state
-     */
     private clearJobState;
     /**
-     * Cleanup resources and clear all job state.
-     * Call this when the printer is no longer needed.
-     */
-    destroy(): void;
-    /**
-     * Clean up expired job states from static store.
-     * Call this periodically to prevent memory leaks.
-     *
-     * @param maxAge - Maximum age in ms (default: 1 hour)
+     * Lazily start the auto-cleanup timer for the static store. The Node.js
+     * `unref()` call lets the process exit even if the timer is still scheduled.
      */
+    private static ensureCleanupTimer;
     static cleanupExpiredJobs(maxAge?: number): number;
-    /**
-     * Stop the auto-cleanup timer. Useful for test teardown.
-     */
     static stopCleanupTimer(): void;
-    /**
-     * Get count of pending job states in static store.
-     * Useful for debugging memory usage.
-     */
     static getStaticStoreSize(): number;
-    /**
-     * Emits job state change event
-     *
-     * @param state - New job state
-     */
-    private emitJobState;
-    /**
-     * Handles job completion: logs, resets state, and emits event.
-     * Shared by start() and resume() code paths.
-     */
     private completeJob;
-    /**
-     * Pauses the current print job
-     */
-    pause(): void;
-    /**
-     * Gets the number of bytes remaining to print
-     *
-     * @returns number - Bytes remaining
-     */
-    remaining(): number;
-    /**
-     * Checks if the print job is paused
-     *
-     * @returns boolean - True if paused, false otherwise
-     */
-    isPaused(): boolean;
-    /**
-     * Checks if a print job is in progress
-     *
-     * @returns boolean - True if in progress, false otherwise
-     */
-    isInProgress(): boolean;
-    /**
-     * Sets adapter options for write operations
-     *
-     * @param options - Adapter options
-     */
-    setOptions(options: IAdapterOptions): void;
-    /**
-     * Processes the print job in chunks
-     * Supports pause/resume functionality
-     *
-     * @returns Promise<void>
-     */
+    private emitJobState;
     private processJob;
-    /**
-     * Gets the current device ID from the connection manager
-     *
-     * @returns string - Device ID
-     * @throws BluetoothPrintError if no device is connected
-     */
     private getDeviceId;
 }

package/dist/types/utils/BoundedOrderedMap.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Bounded Ordered Map
+ *
+ * A `Map<K, V>` that enforces a maximum size, evicting the oldest entries
+ * (by `value.createdAt`) when capacity is exceeded. The underlying ordered
+ * index enables O(log n) insertion position lookup (binary search) and
+ * O(k) eviction of the k oldest entries.
+ *
+ * @typeParam K - Key type
+ * @typeParam V - Value type (must carry a `createdAt: number` for ordering)
+ *
+ * @example
+ * ```typescript
+ * const map = new BoundedOrderedMap<string, PrintHistoryEntry>(1000);
+ * map.set('id-1', { id: 'id-1', createdAt: Date.now(), ... });
+ * const entry = map.get('id-1');
+ * map.size; // current entry count
+ * ```
+ */
+export declare class BoundedOrderedMap<K, V extends {
+    createdAt: number;
+}> {
+    private readonly maxEntries;
+    private readonly entries;
+    private readonly orderedIds;
+    constructor(maxEntries: number);
+    /** Insert or update an entry. Triggers eviction if size exceeds maxEntries. */
+    set(id: K, value: V): void;
+    get(id: K): V | undefined;
+    has(id: K): boolean;
+    delete(id: K): boolean;
+    clear(): void;
+    get size(): number;
+    get maxSize(): number;
+    values(): IterableIterator<V>;
+    keys(): IterableIterator<K>;
+    entriesIter(): IterableIterator<[K, V]>;
+    /**
+     * Re-sort the ordered index from the underlying entries. Call after bulk
+     * mutations that bypass `set()` (e.g. restoring from persistence).
+     */
+    rebuildIndex(): void;
+    /** Trim oldest entries until size <= maxEntries. */
+    private enforceMaxEntries;
+    /** Binary search for the insertion position to keep orderedIds ascending. */
+    private findInsertPosition;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taro-bluetooth-print",
-  "version": "2.13.0",
+  "version": "2.15.0",
   "description": "Taro 蓝牙打印库 v2.6 - 轻量级、高性能、跨平台支持微信、支付宝、百度、字节跳动小程序及H5 Web Bluetooth",
   "type": "module",
   "main": "dist/index.cjs.js",
@@ -99,5 +99,7 @@
       "vite@<=6.4.1": ">=6.4.2",
       "postcss@<8.5.10": ">=8.5.10"
     }
-  }
+  },
+  "homepage": "https://agions.github.io/taro-bluetooth-print/",
+  "documentation": "https://agions.github.io/taro-bluetooth-print/"
 }

package/src/adapters/AdapterFactory.ts

@@ -12,7 +12,7 @@ import { ByteDanceAdapter } from './ByteDanceAdapter';
 import { QQAdapter } from './QQAdapter';
 import { WebBluetoothAdapter } from './WebBluetoothAdapter';
 import { PlatformType, detectPlatform } from '@/utils/platform';
-import { BluetoothPrintError, ErrorCode } from '@/errors/baseError';
+import { BluetoothPrintError, ErrorCode } from '@/errors/BaseError';
 
 /**
  * Adapter factory class