taro-bluetooth-print 2.8.4 → 2.9.0

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/index.ts

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

package/src/index.ts

@@ -87,6 +87,17 @@ export { PlatformType, detectPlatform, isPlatformSupported } from './utils/platf
 
 // 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';
 
 // Configuration - 配置
 export { DEFAULT_CONFIG, mergeConfig } from './config/PrinterConfig';

package/src/services/interfaces/ICommandBuilder.ts

@@ -0,0 +1,145 @@
+/**
+ * Command Builder Interface
+ *
+ * Builds print commands using the printer driver
+ */
+
+import { IQrOptions } from '@/types';
+import { TextAlign, TextStyle } from '@/formatter';
+import { BarcodeOptions } from '@/barcode';
+
+/**
+ * Command Builder Interface
+ *
+ * Builds print commands using the printer driver
+ */
+export interface ICommandBuilder {
+  /**
+   * Adds text to the print queue
+   *
+   * @param content - Text content
+   * @param encoding - Text encoding
+   * @returns this - For method chaining
+   */
+  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
+   */
+  clear(): this;
+
+  /**
+   * Sets text alignment
+   *
+   * @param alignment - Text alignment (left, center, right)
+   * @returns this - For method chaining
+   */
+  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
+   */
+  setSize(width: number, height: number): this;
+
+  /**
+   * Sets bold text mode
+   *
+   * @param enabled - Enable or disable bold
+   * @returns this - For method chaining
+   */
+  setBold(enabled: boolean): this;
+
+  /**
+   * Sets underline text mode
+   *
+   * @param enabled - Enable or disable underline
+   * @returns this - For method chaining
+   */
+  setUnderline(enabled: boolean): this;
+
+  /**
+   * Sets inverse printing mode (white on black)
+   *
+   * @param enabled - Enable or disable inverse
+   * @returns this - For method chaining
+   */
+  setInverse(enabled: boolean): this;
+
+  /**
+   * Sets multiple text style properties at once
+   *
+   * @param style - Text style configuration
+   * @returns this - For method chaining
+   */
+  setStyle(style: TextStyle): this;
+
+  /**
+   * Resets all text formatting to default
+   *
+   * @returns this - For method chaining
+   */
+  resetStyle(): this;
+
+  /**
+   * Adds a 1D barcode to the print queue
+   *
+   * @param content - Barcode content/data
+   * @param options - Barcode options
+   * @returns this - For method chaining
+   */
+  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/src/services/interfaces/IConnectionManager.ts

@@ -0,0 +1,58 @@
+/**
+ * Connection Manager Interface
+ *
+ * Manages Bluetooth device connections
+ */
+
+import { PrinterState, IPrinterAdapter } from '@/types';
+
+/**
+ * Connection Manager Interface
+ *
+ * Manages Bluetooth device connections
+ */
+export interface IConnectionManager {
+  /**
+   * Connects to a Bluetooth device
+   *
+   * @param deviceId - Bluetooth device ID
+   * @param options - Connection options
+   * @returns Promise<void>
+   */
+  connect(deviceId: string, options?: { retries?: number; timeout?: number }): Promise<void>;
+
+  /**
+   * Disconnects from the current device
+   *
+   * @returns Promise<void>
+   */
+  disconnect(): Promise<void>;
+
+  /**
+   * Checks if a device is connected
+   *
+   * @returns boolean - True if connected, false otherwise
+   */
+  isConnected(): boolean;
+
+  /**
+   * Gets the current device ID
+   *
+   * @returns string | null - Device ID or null if not connected
+   */
+  getDeviceId(): string | null;
+
+  /**
+   * Gets the current connection state
+   *
+   * @returns PrinterState - Current state
+   */
+  getState(): PrinterState;
+
+  /**
+   * Gets the printer adapter instance
+   *
+   * @returns IPrinterAdapter - Printer adapter
+   */
+  getAdapter(): IPrinterAdapter;
+}

package/src/services/interfaces/IPrintJobManager.ts

@@ -0,0 +1,83 @@
+/**
+ * Print Job Manager Interface
+ *
+ * Manages print jobs, including pause/resume/cancel functionality
+ */
+
+import { IAdapterOptions } from '@/types';
+
+/**
+ * Print Job Manager Interface
+ *
+ * Manages print jobs, including pause/resume/cancel functionality
+ */
+export interface IPrintJobManager {
+  /**
+   * Starts a print job
+   *
+   * @param buffer - Print data buffer
+   * @returns Promise<void>
+   */
+  start(buffer: Uint8Array, options?: { jobId?: string }): Promise<void>;
+
+  /**
+   * Pauses the current print job
+   */
+  pause(): void;
+
+  /**
+   * Resumes a paused print job
+   *
+   * @returns Promise<void>
+   */
+  resume(jobId?: string): Promise<void>;
+
+  /**
+   * Cancels the current print job
+   */
+  cancel(): 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;
+
+  /**
+   * 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;
+}