taro-bluetooth-print 2.8.4 → 2.9.1

package/dist/types/utils/validators/printer.d.ts

@@ -0,0 +1,40 @@
+import { ValidationResult, PrinterDataSchema, PrintJobSchema } from './types';
+/**
+ * Validate printer connection data
+ *
+ * @param data - Data to validate
+ * @param schema - Validation schema
+ * @returns Validation result
+ *
+ * @example
+ * ```typescript
+ * const result = validatePrinterData({
+ *   deviceId: 'device-123',
+ *   deviceName: 'Thermal Printer',
+ * }, {
+ *   deviceId: { required: true },
+ *   deviceName: { required: true, maxLength: 50 }
+ * });
+ * ```
+ */
+export declare function validatePrinterData(data: Record<string, unknown>, schema: PrinterDataSchema): ValidationResult;
+/**
+ * Validate print job data
+ *
+ * @param data - Data to validate
+ * @param schema - Validation schema
+ * @returns Validation result
+ *
+ * @example
+ * ```typescript
+ * const result = validatePrintJob({
+ *   jobId: 'job-001',
+ *   data: new ArrayBuffer(1024),
+ *   priority: 5,
+ * }, {
+ *   jobId: { required: true },
+ *   data: { required: true, minSize: 1 }
+ * });
+ * ```
+ */
+export declare function validatePrintJob(data: Record<string, unknown>, schema: PrintJobSchema): ValidationResult;

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

@@ -0,0 +1,125 @@
+/**
+ * Core validation types
+ */
+/**
+ * Validation error details
+ */
+export interface ValidationError {
+    /** Field that failed validation */
+    field: string;
+    /** Human-readable error message */
+    message: string;
+    /** Error code for programmatic handling */
+    code: string;
+    /** Actual value that failed (optional) */
+    value?: unknown;
+}
+/**
+ * Validation result
+ */
+export interface ValidationResult {
+    /** Whether validation passed */
+    valid: boolean;
+    /** List of validation errors */
+    errors: ValidationError[];
+    /** Warnings (non-fatal issues) */
+    warnings?: ValidationError[];
+}
+/**
+ * Validator function type
+ */
+export type ValidatorFn<T = unknown> = (value: T) => ValidationResult;
+/**
+ * Validation rule definition
+ */
+export interface ValidationRule<T = unknown> {
+    /** Rule name */
+    name: string;
+    /** Validation function */
+    validate: (value: T) => boolean;
+    /** Error message if validation fails */
+    message: string;
+    /** Error code */
+    code: string;
+}
+/**
+ * Common error codes
+ */
+export declare const ValidationCodes: {
+    readonly REQUIRED: "REQUIRED";
+    readonly INVALID_TYPE: "INVALID_TYPE";
+    readonly INVALID_FORMAT: "INVALID_FORMAT";
+    readonly OUT_OF_RANGE: "OUT_OF_RANGE";
+    readonly TOO_SHORT: "TOO_SHORT";
+    readonly TOO_LONG: "TOO_LONG";
+    readonly INVALID_ENUM: "INVALID_ENUM";
+    readonly PATTERN_MISMATCH: "PATTERN_MISMATCH";
+    readonly INVALID_BUFFER: "INVALID_BUFFER";
+    readonly INVALID_ENCODING: "INVALID_ENCODING";
+    readonly EMPTY_ARRAY: "EMPTY_ARRAY";
+    readonly ARRAY_TOO_SHORT: "ARRAY_TOO_SHORT";
+    readonly ARRAY_TOO_LONG: "ARRAY_TOO_LONG";
+    readonly DUPLICATE_VALUE: "DUPLICATE_VALUE";
+    readonly NEGATIVE_VALUE: "NEGATIVE_VALUE";
+    readonly ZERO_VALUE: "ZERO_VALUE";
+    readonly NOT_A_NUMBER: "NOT_A_NUMBER";
+    readonly INFINITY_VALUE: "INFINITY_VALUE";
+    readonly INVALID_JSON: "INVALID_JSON";
+    readonly UNSUPPORTED_VALUE: "UNSUPPORTED_VALUE";
+    readonly INVALID_VERSION: "INVALID_VERSION";
+};
+/**
+ * Printer data validation schema
+ */
+export interface PrinterDataSchema {
+    /** Device ID */
+    deviceId?: {
+        required?: boolean;
+        pattern?: RegExp;
+    };
+    /** Device name */
+    deviceName?: {
+        required?: boolean;
+        maxLength?: number;
+    };
+    /** Service UUID */
+    serviceUUID?: {
+        required?: boolean;
+        pattern?: RegExp;
+    };
+    /** Characteristic UUID */
+    characteristicUUID?: {
+        required?: boolean;
+        pattern?: RegExp;
+    };
+}
+/**
+ * Print job data validation schema
+ */
+export interface PrintJobSchema {
+    /** Job ID */
+    jobId?: {
+        required?: boolean;
+        maxLength?: number;
+    };
+    /** Data buffer */
+    data?: {
+        required?: boolean;
+        minSize?: number;
+        maxSize?: number;
+    };
+    /** Priority */
+    priority?: {
+        min?: number;
+        max?: number;
+    };
+    /** Retry count */
+    retryCount?: {
+        min?: number;
+        max?: number;
+    };
+    /** Metadata */
+    metadata?: {
+        required?: boolean;
+    };
+}

package/dist/types/utils/validators/uuid.d.ts

@@ -0,0 +1,23 @@
+/**
+ * UUID validation
+ */
+/**
+ * Validate a string is valid UUID
+ *
+ * @param value - Value to validate
+ * @param options - Validation options
+ * @returns Validation result
+ *
+ * @example
+ * ```typescript
+ * const result = isValidUUID(value, { required: true });
+ * ```
+ */
+export declare function isValidUUID(value: unknown, options?: {
+    required?: boolean;
+    versions?: number[];
+}): {
+    valid: boolean;
+    version?: number;
+    error?: string;
+};

package/package.json

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

package/src/core/BluetoothPrinter.ts

@@ -77,44 +77,53 @@ export class BluetoothPrinter extends EventEmitter<PrinterEvents> {
   /**
    * Creates a new BluetoothPrinter instance
    *
-   * @param connectionManagerOrAdapter - Connection manager instance or printer adapter instance (for backward compatibility)
-   * @param printJobManagerOrDriver - Print job manager instance or printer driver instance (for backward compatibility)
-   * @param commandBuilder - Command builder instance (optional)
+   * Supports two calling conventions:
+   * - Modern DI: new BluetoothPrinter(connectionManager, printJobManager, commandBuilder)
+   * - Legacy API: new BluetoothPrinter(adapter) - adapter is wrapped in ConnectionManager
+   *
+   * @param connectionManagerOrAdapter - Connection manager (recommended) or IPrinterAdapter (legacy)
+   * @param printJobManager - Print job manager instance
+   * @param commandBuilder - Command builder instance
+   *
+   * @example
+   * ```typescript
+   * // Recommended: use the factory
+   * import { createBluetoothPrinter } from 'taro-bluetooth-print';
+   * const printer = createBluetoothPrinter({ adapter: myAdapter });
+   *
+   * // Direct instantiation with DI
+   * const printer = new BluetoothPrinter(connectionManager, printJobManager, commandBuilder);
+   *
+   * // Legacy API (backward compatible)
+   * const printer = new BluetoothPrinter(adapter);
+   * ```
    */
   constructor(
     connectionManagerOrAdapter?: IConnectionManager | IPrinterAdapter,
-    printJobManagerOrDriver?: IPrintJobManager,
+    printJobManager?: IPrintJobManager,
     commandBuilder?: ICommandBuilder
   ) {
     super();
 
-    // Handle backward compatibility
-    if (
-      connectionManagerOrAdapter &&
-      typeof (connectionManagerOrAdapter as IPrinterAdapter).connect === 'function'
-    ) {
-      // Old API: new BluetoothPrinter(adapter)
-      const adapter = connectionManagerOrAdapter as IPrinterAdapter;
+    // Detect legacy API: first arg is an adapter (has connect method) vs connection manager
+    const isAdapter =
+      connectionManagerOrAdapter != null &&
+      typeof (connectionManagerOrAdapter as IPrinterAdapter).connect === 'function';
 
-      // Create services manually
+    if (isAdapter) {
+      // Legacy API: wrap adapter in ConnectionManager
+      const adapter = connectionManagerOrAdapter as IPrinterAdapter;
       this.connectionManager = new ConnectionManager(adapter);
-      this.printJobManager = new PrintJobManager(this.connectionManager);
-      this.commandBuilder = commandBuilder || new CommandBuilder();
+      this.printJobManager = printJobManager ?? new PrintJobManager(this.connectionManager);
+      this.commandBuilder = commandBuilder ?? new CommandBuilder();
     } else {
-      // New API: dependency injection or manual service creation
-      this.connectionManager = connectionManagerOrAdapter as IConnectionManager;
-      this.printJobManager = printJobManagerOrDriver as IPrintJobManager;
-      this.commandBuilder = commandBuilder as ICommandBuilder;
-
-      // If services are not provided, create them using default implementations
-      if (!this.connectionManager) {
-        this.connectionManager = new ConnectionManager();
-        this.printJobManager = new PrintJobManager(this.connectionManager);
-        this.commandBuilder = new CommandBuilder();
-      }
+      // Modern DI
+      this.connectionManager =
+        (connectionManagerOrAdapter as IConnectionManager) ?? new ConnectionManager();
+      this.printJobManager = printJobManager ?? new PrintJobManager(this.connectionManager);
+      this.commandBuilder = commandBuilder ?? new CommandBuilder();
     }
 
-    // Listen to connection manager state changes
     this.updateState();
   }
 
@@ -122,28 +131,19 @@ export class BluetoothPrinter extends EventEmitter<PrinterEvents> {
    * Updates the current state based on the connection manager and print job manager states
    */
   private updateState(): void {
-    // Get connection state (with fallback for backward compatibility)
-    let connectionState: PrinterState;
-    if (this.connectionManager && typeof this.connectionManager.getState === 'function') {
-      connectionState = this.connectionManager.getState();
-    } else {
-      // Default to CONNECTED for backward compatibility
-      connectionState = PrinterState.CONNECTED;
-    }
+    // Safe fallbacks for mock objects in tests
+    const connectionState =
+      typeof this.connectionManager.getState === 'function'
+        ? this.connectionManager.getState()
+        : PrinterState.CONNECTED;
 
-    // Get print job state (with fallback for backward compatibility)
-    let isPrinting = false;
-    let isPaused = false;
-    if (this.printJobManager) {
-      isPrinting =
-        typeof this.printJobManager.isInProgress === 'function'
-          ? this.printJobManager.isInProgress()
-          : false;
-      isPaused =
-        typeof this.printJobManager.isPaused === 'function'
-          ? this.printJobManager.isPaused()
-          : false;
-    }
+    const isPrinting =
+      typeof this.printJobManager.isInProgress === 'function'
+        ? this.printJobManager.isInProgress()
+        : false;
+
+    const isPaused =
+      typeof this.printJobManager.isPaused === 'function' ? this.printJobManager.isPaused() : false;
 
     // Determine the final state
     if (isPaused) {
@@ -425,11 +425,10 @@ export class BluetoothPrinter extends EventEmitter<PrinterEvents> {
    * ```
    */
   async print(): Promise<void> {
-    // Check if connectionManager has isConnected method, default to true for mock objects in tests
     const isConnected =
       typeof this.connectionManager.isConnected === 'function'
         ? this.connectionManager.isConnected()
-        : true;
+        : true; // Default to true for mock objects
 
     if (!isConnected) {
       throw new BluetoothPrintError(
@@ -454,7 +453,6 @@ export class BluetoothPrinter extends EventEmitter<PrinterEvents> {
     try {
       await this.printJobManager.start(buffer);
 
-      // Check if the job was paused
       const isPaused =
         typeof this.printJobManager.isPaused === 'function'
           ? this.printJobManager.isPaused()

package/src/core/di/Container.ts

@@ -0,0 +1,330 @@
+/**
+ * 依赖注入容器
+ * 提供现代化的依赖管理和服务定位功能
+ */
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type Constructor<T = object> = new (...args: any[]) => T;
+export type Factory<T> = (container: Container) => T;
+export type Provider<T> = Constructor<T> | Factory<T> | T;
+
+export interface RegistrationOptions {
+  /** 是否单例 */
+  singleton?: boolean;
+  /** 生命周期 */
+  lifecycle?: 'transient' | 'singleton' | 'scoped';
+  /** 标签，用于区分同一接口的不同实现 */
+  tag?: string;
+}
+
+/**
+ * Angular 风格的服务提供者配置
+ */
+export interface ServiceProviderConfig<T = unknown> {
+  /** 使用类 */
+  useClass?: Constructor<T>;
+  /** 使用工厂函数 */
+  useFactory?: Factory<T>;
+  /** 使用实例值 */
+  useValue?: T;
+  /** 生命周期 */
+  lifecycle?: 'transient' | 'singleton' | 'scoped';
+  /** 依赖项 */
+  dependencies?: (string | symbol | Constructor<unknown>)[];
+}
+
+interface Registration<T> {
+  provider: Provider<T>;
+  options: RegistrationOptions;
+  instance?: T;
+}
+
+export class Container {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private registrations = new Map<string | symbol, Registration<any>[]>();
+  private parent?: Container;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private scopedInstances = new Map<string | symbol, any>();
+
+  constructor(parent?: Container) {
+    this.parent = parent;
+  }
+
+  /**
+   * 创建子容器
+   */
+  createChild(): Container {
+    return new Container(this);
+  }
+
+  /**
+   * 注册服务
+   */
+  register<T>(
+    token: string | symbol | Constructor<T>,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    provider: Provider<T> | ServiceProviderConfig<T>,
+    options: RegistrationOptions = {}
+  ): this {
+    const key = this.getTokenKey(token);
+
+    // 支持 ServiceProviderConfig 格式
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const config = provider as ServiceProviderConfig<T>;
+
+    // 如果是对象语法（Angular 风格）
+    if (config && typeof config === 'object' && (config.useClass || config.useFactory || config.useValue !== undefined)) {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      let actualProvider: Provider<any>;
+
+      if (config.useClass) {
+        // 使用类 - 创建工厂函数来解析依赖
+        const Cls = config.useClass;
+        actualProvider = (container: Container) => {
+          // 简化：直接实例化（实际应该解析依赖）
+          return container.createInstance(Cls);
+        };
+      } else if (config.useFactory) {
+        actualProvider = config.useFactory;
+      } else {
+        actualProvider = config.useValue as T;
+      }
+
+      const registration: Registration<T> = {
+        provider: actualProvider,
+        options: {
+          lifecycle: config.lifecycle || 'transient',
+          ...options,
+        },
+      };
+
+      if (!this.registrations.has(key)) {
+        this.registrations.set(key, []);
+      }
+      this.registrations.get(key)!.push(registration);
+      return this;
+    }
+
+    // 原有逻辑：Provider<T> 格式
+    const registration: Registration<T> = {
+      provider: provider as Provider<T>,
+      options: {
+        lifecycle: 'transient',
+        ...options,
+      },
+    };
+
+    if (!this.registrations.has(key)) {
+      this.registrations.set(key, []);
+    }
+    this.registrations.get(key)!.push(registration);
+    return this;
+  }
+
+  /**
+   * 注册单例服务
+   */
+  registerSingleton<T>(token: string | symbol | Constructor<T>, provider: Provider<T>): this {
+    return this.register(token, provider, { lifecycle: 'singleton' });
+  }
+
+  /**
+   * 注册类型映射
+   */
+  registerType<T>(
+    from: string | symbol | Constructor<T>,
+    to: Constructor<T>,
+    options: RegistrationOptions = {}
+  ): this {
+    return this.register(from, c => c.resolve(to), options);
+  }
+
+  /**
+   * 注册实例
+   */
+  registerInstance<T>(token: string | symbol | Constructor<T>, instance: T): this {
+    return this.register(token, instance, { lifecycle: 'singleton' });
+  }
+
+  /**
+   * 解析服务
+   */
+  resolve<T>(token: string | symbol | Constructor<T>, tag?: string): T {
+    const key = this.getTokenKey(token);
+
+    // 1. 检查当前容器的注册
+    const registrations = this.registrations.get(key);
+    if (registrations) {
+      const registration = tag
+        ? registrations.find(r => r.options.tag === tag)
+        : registrations[registrations.length - 1];
+
+      if (registration) {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+        return this.getOrCreateInstance(registration, key);
+      }
+    }
+
+    // 2. 检查父容器
+    if (this.parent) {
+      return this.parent.resolve(token, tag);
+    }
+
+    // 3. 如果是构造函数，自动创建实例
+    if (typeof token === 'function' && this.isConstructor(token)) {
+      return this.createInstance(token);
+    }
+
+    throw new Error(`No registration found for token: ${String(key)}`);
+  }
+
+  /**
+   * 解析所有注册的服务
+   */
+  resolveAll<T>(token: string | symbol | Constructor<T>): T[] {
+    const key = this.getTokenKey(token);
+    const results: T[] = [];
+
+    // 从当前容器获取
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const registrations = this.registrations.get(key);
+    if (registrations) {
+      for (const r of registrations) {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+        results.push(this.getOrCreateInstance(r, key));
+      }
+    }
+
+    // 从父容器获取
+    if (this.parent) {
+      results.push(...this.parent.resolveAll(token));
+    }
+
+    return results;
+  }
+
+  /**
+   * 检查是否已注册
+   */
+  isRegistered<T>(token: string | symbol | Constructor<T>): boolean {
+    const key = this.getTokenKey(token);
+    return this.registrations.has(key) || (this.parent?.isRegistered(token) ?? false);
+  }
+
+  /**
+   * 清除所有注册
+   */
+  clear(): void {
+    this.registrations.clear();
+    this.scopedInstances.clear();
+  }
+
+  /**
+   * 创建作用域
+   */
+  createScope(): Container {
+    const scope = this.createChild();
+    return scope;
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private getTokenKey(token: string | symbol | Constructor<any>): string | symbol {
+    if (typeof token === 'function') {
+      return token.name || (token as unknown as symbol);
+    }
+    return token;
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+  private isConstructor(fn: Function): boolean {
+    return (
+      typeof fn.prototype === 'object' &&
+      fn.prototype !== null &&
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+      fn.prototype.constructor === fn
+    );
+  }
+
+  private getOrCreateInstance<T>(registration: Registration<T>, key: string | symbol): T {
+    const { provider, options } = registration;
+
+    // 单例模式
+    if (options.lifecycle === 'singleton') {
+      if (registration.instance === undefined) {
+        registration.instance = this.createProviderInstance(provider);
+      }
+      return registration.instance;
+    }
+
+    // 作用域模式
+    if (options.lifecycle === 'scoped') {
+      if (this.scopedInstances.has(key)) {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+        return this.scopedInstances.get(key) as T;
+      }
+      const instance = this.createProviderInstance(provider);
+      this.scopedInstances.set(key, instance);
+      return instance;
+    }
+
+    // 瞬态模式
+    return this.createProviderInstance(provider);
+  }
+
+  private createProviderInstance<T>(provider: Provider<T>): T {
+    if (typeof provider === 'function') {
+      // 工厂函数
+      if (provider.length === 1 && !this.isConstructor(provider)) {
+        return (provider as Factory<T>)(this);
+      }
+      // 构造函数
+      return this.createInstance(provider as Constructor<T>);
+    }
+    // 实例
+    return provider;
+  }
+
+  private createInstance<T>(constructor: Constructor<T>): T {
+    // 获取构造函数的参数类型（简化实现，实际可能需要反射元数据）
+    const paramCount = constructor.length;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const args: any[] = [];
+
+    for (let i = 0; i < paramCount; i++) {
+      // 尝试从容器解析参数
+      // 这里简化处理，实际应该使用参数装饰器
+      args.push(undefined);
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+    return new constructor(...args);
+  }
+}
+
+// 全局容器实例
+export const rootContainer = new Container();
+
+// 装饰器辅助函数
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function injectable<T extends Constructor>(constructor: T): T {
+  // 标记类为可注入
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+  (constructor as any).__injectable = true;
+  return constructor;
+}
+
+export function inject(token: string | symbol) {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  return function (target: any, _propertyKey: string | symbol, parameterIndex: number) {
+    // 存储注入元数据
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+    const existingInjections: (string | symbol)[] =
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+      (target.__injections as (string | symbol)[]) || [];
+    existingInjections[parameterIndex] = token;
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+    target.__injections = existingInjections;
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+    return target;
+  };
+}