taro-bluetooth-print 2.2.1 → 2.3.0

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;