taro-bluetooth-print 2.2.0 → 2.3.0

package/src/plugins/PluginManager.ts

@@ -0,0 +1,193 @@
+/**
+ * Plugin Manager
+ * Manages plugin lifecycle and hook execution
+ */
+
+import { Plugin, PluginHooks, PluginOptions } from './types';
+import { BluetoothPrintError, ErrorCode } from '@/errors/BluetoothError';
+import { PrinterState } from '@/types';
+import { Logger } from '@/utils/logger';
+
+/**
+ * Manages plugins for BluetoothPrinter
+ */
+export class PluginManager {
+  private plugins: Map<string, Plugin> = new Map();
+  private readonly logger = Logger.scope('PluginManager');
+
+  /**
+   * Register a plugin
+   * @param plugin - Plugin to register
+   * @param options - Plugin options
+   * @throws {BluetoothPrintError} If plugin with same name already exists
+   */
+  async register(plugin: Plugin, options?: PluginOptions): Promise<void> {
+    if (this.plugins.has(plugin.name)) {
+      throw new BluetoothPrintError(
+        ErrorCode.INVALID_CONFIGURATION,
+        `Plugin "${plugin.name}" is already registered`
+      );
+    }
+
+    this.logger.info(`Registering plugin: ${plugin.name}${plugin.version ? ` v${plugin.version}` : ''}`);
+
+    if (plugin.init) {
+      await plugin.init(options);
+    }
+
+    this.plugins.set(plugin.name, plugin);
+    this.logger.debug(`Plugin registered: ${plugin.name}`);
+  }
+
+  /**
+   * Unregister a plugin
+   * @param name - Plugin name to unregister
+   */
+  async unregister(name: string): Promise<void> {
+    const plugin = this.plugins.get(name);
+    if (!plugin) {
+      this.logger.warn(`Plugin not found: ${name}`);
+      return;
+    }
+
+    if (plugin.destroy) {
+      await plugin.destroy();
+    }
+
+    this.plugins.delete(name);
+    this.logger.info(`Plugin unregistered: ${name}`);
+  }
+
+  /**
+   * Get a registered plugin
+   * @param name - Plugin name
+   * @returns Plugin instance or undefined
+   */
+  get(name: string): Plugin | undefined {
+    return this.plugins.get(name);
+  }
+
+  /**
+   * Get all registered plugin names
+   * @returns Array of plugin names
+   */
+  getNames(): string[] {
+    return Array.from(this.plugins.keys());
+  }
+
+  /**
+   * Check if a plugin is registered
+   * @param name - Plugin name
+   * @returns True if registered
+   */
+  has(name: string): boolean {
+    return this.plugins.has(name);
+  }
+
+  /**
+   * 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)
+   */
+  async executeHook<K extends keyof PluginHooks>(
+    hookName: K,
+    ...args: Parameters<NonNullable<PluginHooks[K]>>
+  ): Promise<unknown> {
+    let result: unknown = undefined;
+
+    for (const [name, plugin] of this.plugins) {
+      const hook = plugin.hooks[hookName];
+      if (hook) {
+        try {
+          // @ts-expect-error - TypeScript can't infer the correct types here
+          const hookResult = await hook(...args);
+          if (hookResult !== undefined) {
+            result = hookResult;
+          }
+        } catch (error) {
+          this.logger.error(`Plugin "${name}" hook "${hookName}" failed:`, error);
+          // Continue to next plugin
+        }
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Execute beforeConnect hooks
+   */
+  async beforeConnect(deviceId: string): Promise<string> {
+    const result = await this.executeHook('beforeConnect', deviceId);
+    return (result as string) || deviceId;
+  }
+
+  /**
+   * Execute afterConnect hooks
+   */
+  async afterConnect(deviceId: string): Promise<void> {
+    await this.executeHook('afterConnect', deviceId);
+  }
+
+  /**
+   * Execute beforeDisconnect hooks
+   */
+  async beforeDisconnect(deviceId: string): Promise<void> {
+    await this.executeHook('beforeDisconnect', deviceId);
+  }
+
+  /**
+   * Execute afterDisconnect hooks
+   */
+  async afterDisconnect(deviceId: string): Promise<void> {
+    await this.executeHook('afterDisconnect', deviceId);
+  }
+
+  /**
+   * Execute beforePrint hooks
+   */
+  async beforePrint(buffer: Uint8Array): Promise<Uint8Array> {
+    const result = await this.executeHook('beforePrint', buffer);
+    return (result as Uint8Array) || buffer;
+  }
+
+  /**
+   * Execute afterPrint hooks
+   */
+  async afterPrint(bytesSent: number): Promise<void> {
+    await this.executeHook('afterPrint', bytesSent);
+  }
+
+  /**
+   * Execute onError hooks
+   * @returns True if error should be suppressed
+   */
+  async onError(error: BluetoothPrintError): Promise<boolean> {
+    const result = await this.executeHook('onError', error);
+    return result === true;
+  }
+
+  /**
+   * Execute onStateChange hooks
+   */
+  async onStateChange(state: PrinterState, previousState: PrinterState): Promise<void> {
+    await this.executeHook('onStateChange', state, previousState);
+  }
+
+  /**
+   * Execute onProgress hooks
+   */
+  async onProgress(sent: number, total: number): Promise<void> {
+    await this.executeHook('onProgress', sent, total);
+  }
+
+  /**
+   * Clear all plugins
+   */
+  async clear(): Promise<void> {
+    for (const name of this.plugins.keys()) {
+      await this.unregister(name);
+    }
+  }
+}

package/src/plugins/builtin/LoggingPlugin.ts

@@ -0,0 +1,97 @@
+/**
+ * Logging Plugin
+ * Provides detailed logging for printer operations
+ */
+
+import { Plugin, PluginFactory, PluginOptions } from '../types';
+import { Logger, 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 const createLoggingPlugin: PluginFactory = (options?: LoggingPluginOptions): Plugin => {
+  const opts: Required<LoggingPluginOptions> = {
+    level: options?.level ?? LogLevel.DEBUG,
+    timestamps: options?.timestamps ?? true,
+    logProgress: options?.logProgress ?? false,
+  };
+
+  const logger = Logger.scope('PrinterLog');
+  let startTime: number;
+
+  const formatTime = (): string => {
+    if (!opts.timestamps) return '';
+    return `[${new Date().toISOString()}] `;
+  };
+
+  return {
+    name: 'logging',
+    version: '1.0.0',
+    description: 'Detailed logging for printer operations',
+
+    hooks: {
+      beforeConnect: (deviceId: string) => {
+        startTime = Date.now();
+        logger.info(`${formatTime()}Connecting to device: ${deviceId}`);
+      },
+
+      afterConnect: (deviceId: string) => {
+        const elapsed = Date.now() - startTime;
+        logger.info(`${formatTime()}Connected to ${deviceId} (${elapsed}ms)`);
+      },
+
+      beforeDisconnect: (deviceId: string) => {
+        logger.info(`${formatTime()}Disconnecting from: ${deviceId}`);
+      },
+
+      afterDisconnect: (deviceId: string) => {
+        logger.info(`${formatTime()}Disconnected from: ${deviceId}`);
+      },
+
+      beforePrint: (buffer: Uint8Array) => {
+        startTime = Date.now();
+        logger.info(`${formatTime()}Starting print job: ${buffer.length} bytes`);
+      },
+
+      afterPrint: (bytesSent: number) => {
+        const elapsed = Date.now() - startTime;
+        const speed = ((bytesSent / elapsed) * 1000).toFixed(2);
+        logger.info(`${formatTime()}Print complete: ${bytesSent} bytes in ${elapsed}ms (${speed} B/s)`);
+      },
+
+      onError: (error) => {
+        logger.error(`${formatTime()}Error [${error.code}]: ${error.message}`);
+        return false; // Don't suppress the error
+      },
+
+      onStateChange: (state, previousState) => {
+        logger.debug(`${formatTime()}State: ${previousState} → ${state}`);
+      },
+
+      onProgress: (sent, total) => {
+        if (opts.logProgress) {
+          const percent = ((sent / total) * 100).toFixed(1);
+          logger.debug(`${formatTime()}Progress: ${sent}/${total} (${percent}%)`);
+        }
+      },
+    },
+
+    init: () => {
+      Logger.setLevel(opts.level);
+      logger.info('Logging plugin initialized');
+    },
+
+    destroy: () => {
+      logger.info('Logging plugin destroyed');
+    },
+  };
+};

package/src/plugins/builtin/RetryPlugin.ts

@@ -0,0 +1,109 @@
+/**
+ * Retry Plugin
+ * Provides automatic retry with exponential backoff for failed operations
+ */
+
+import { Plugin, PluginFactory, PluginOptions } from '../types';
+import { Logger } from '@/utils/logger';
+import { BluetoothPrintError, 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 const createRetryPlugin: PluginFactory = (options?: RetryPluginOptions): Plugin => {
+  const opts: Required<RetryPluginOptions> = {
+    maxRetries: options?.maxRetries ?? 3,
+    initialDelay: options?.initialDelay ?? 1000,
+    maxDelay: options?.maxDelay ?? 10000,
+    backoffMultiplier: options?.backoffMultiplier ?? 2,
+    retryableErrors: options?.retryableErrors ?? [
+      ErrorCode.CONNECTION_FAILED,
+      ErrorCode.CONNECTION_TIMEOUT,
+      ErrorCode.WRITE_FAILED,
+      ErrorCode.WRITE_TIMEOUT,
+    ],
+  };
+
+  const logger = Logger.scope('RetryPlugin');
+  let retryCount = 0;
+  let currentDelay = opts.initialDelay;
+
+  const shouldRetry = (error: BluetoothPrintError): boolean => {
+    return (
+      retryCount < opts.maxRetries &&
+      opts.retryableErrors.includes(error.code)
+    );
+  };
+
+  const sleep = (ms: number): Promise<void> => {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  };
+
+  return {
+    name: 'retry',
+    version: '1.0.0',
+    description: 'Automatic retry with exponential backoff',
+
+    hooks: {
+      beforeConnect: () => {
+        // Reset retry state on new connection attempt
+        retryCount = 0;
+        currentDelay = opts.initialDelay;
+      },
+
+      beforePrint: () => {
+        // Reset retry state on new print job
+        retryCount = 0;
+        currentDelay = opts.initialDelay;
+      },
+
+      onError: async (error: BluetoothPrintError) => {
+        if (shouldRetry(error)) {
+          retryCount++;
+          logger.warn(
+            `Retryable error occurred (attempt ${retryCount}/${opts.maxRetries}): ${error.code}`
+          );
+          logger.info(`Waiting ${currentDelay}ms before retry...`);
+          
+          await sleep(currentDelay);
+          
+          // Exponential backoff
+          currentDelay = Math.min(
+            currentDelay * opts.backoffMultiplier,
+            opts.maxDelay
+          );
+
+          // Note: Returning false means error is not suppressed
+          // The actual retry logic would need to be implemented in the printer
+          // This plugin mainly provides the delay and logging
+          return false;
+        }
+
+        if (retryCount > 0) {
+          logger.error(
+            `Failed after ${retryCount} retries: ${error.code} - ${error.message}`
+          );
+        }
+
+        return false;
+      },
+    },
+
+    init: () => {
+      logger.info(`Retry plugin initialized (max: ${opts.maxRetries}, delay: ${opts.initialDelay}ms)`);
+    },
+  };
+};

package/src/plugins/index.ts

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

package/src/plugins/types.ts

@@ -0,0 +1,119 @@
+/**
+ * Plugin System Types
+ * Defines interfaces for extending BluetoothPrinter functionality
+ */
+
+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/src/preview/PreviewRenderer.ts

@@ -236,7 +236,13 @@ export class PreviewRenderer implements IPreviewRenderer {
           case 0x61: // ESC a - Alignment
             flushText();
             if (i + 2 < commands.length) {
-              state.alignment = commands[i + 2] as Alignment;
+              const alignValue = commands[i + 2];
+              state.alignment =
+                alignValue === Alignment.LEFT ||
+                alignValue === Alignment.CENTER ||
+                alignValue === Alignment.RIGHT
+                  ? alignValue
+                  : Alignment.LEFT;
             }
             i += 3;
             break;

package/src/queue/PrintQueue.ts

@@ -385,12 +385,16 @@ export class PrintQueue implements IPrintQueue {
       if (!job || job.status !== PrintJobStatus.PENDING) continue;
 
       this.activeJobs++;
-      void this.executeJob(job).finally(() => {
-        this.activeJobs--;
-        if (!this.isPaused) {
-          this.processQueue();
-        }
-      });
+      this.executeJob(job)
+        .catch(error => {
+          this.logger.error(`Unhandled error in job execution for ${job.id}:`, error);
+        })
+        .finally(() => {
+          this.activeJobs--;
+          if (!this.isPaused) {
+            this.processQueue();
+          }
+        });
     }
 
     this.isProcessing = false;