taro-bluetooth-print 2.4.0 → 2.5.0

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

@@ -2,10 +2,11 @@
  * Batch Print Manager
  *
  * Optimizes printing multiple jobs by:
- * - Merging small jobs into larger chunks
- * - Reducing Bluetooth communication overhead
+ * - Merging consecutive small jobs (combining jobs < 50 bytes for efficiency)
+ * - Reducing Bluetooth communication overhead via batching
  * - Prioritizing urgent jobs
- * - Batching similar content for efficiency
+ * - Auto-flush on task interval timeout
+ * - Batch merge with unified cut commands
  *
  * @example
  * ```typescript
@@ -48,6 +49,12 @@ export interface BatchConfig {
     enableMerging: boolean;
     /** Auto-process interval in ms (0 = disabled) */
     autoProcessInterval: number;
+    /** Small job size threshold for merging (bytes, default: 50) */
+    smallJobThreshold: number;
+    /** Interval timeout for auto-flush in ms (0 = disabled) */
+    flushIntervalTimeout: number;
+    /** Unified cut command appended after batch merge (default: ESC d 4) */
+    unifiedCutCommand?: Uint8Array;
 }
 /**
  * Batch statistics
@@ -61,8 +68,12 @@ export interface BatchStats {
     batchesProcessed: number;
     /** Average batch size */
     avgBatchSize: number;
-    /** Merged jobs count */
+    /** Merged jobs count (small jobs combined) */
     mergedJobs: number;
+    /** Auto-flush triggered count */
+    autoFlushCount: number;
+    /** Unified cuts applied */
+    unifiedCutsApplied: number;
 }
 /**
  * Batch events
@@ -77,12 +88,25 @@ export interface BatchEvents {
     'job-rejected': (data: {
         reason: string;
     }) => void;
+    'auto-flush': (data: {
+        jobCount: number;
+        bytes: number;
+    }) => void;
+    'jobs-merged': (data: {
+        fromCount: number;
+        toCount: number;
+        savedBytes: number;
+    }) => void;
 }
 /**
  * Batch Print Manager
  *
  * Collects print jobs and processes them in optimized batches.
- * Reduces Bluetooth communication overhead by combining small jobs.
+ * Features:
+ * - Small job merging: consecutive jobs < smallJobThreshold bytes are combined
+ * - Interval timeout auto-flush: flushes pending jobs if no new jobs arrive within timeout
+ * - Unified cut: optionally appends a single cut command after batch merge
+ * - Priority sorting: higher priority jobs are processed first
  */
 export declare class BatchPrintManager {
     private readonly logger;
@@ -92,17 +116,30 @@ export declare class BatchPrintManager {
     private isProcessing;
     private waitTimer;
     private autoProcessTimer;
+    private flushTimer;
     private stats;
+    /**
+     * Last job timestamp for interval timeout tracking
+     */
+    private lastJobAt;
     /**
      * Creates a new BatchPrintManager instance
+     *
+     * @param config - Optional configuration overrides
      */
     constructor(config?: Partial<BatchConfig>);
     /**
      * Register event listener
+     *
+     * @param event - Event name
+     * @param callback - Event handler
      */
     on<K extends keyof BatchEvents>(event: K, callback: BatchEvents[K]): void;
     /**
      * Remove event listener
+     *
+     * @param event - Event name
+     * @param callback - Event handler to remove
      */
     off<K extends keyof BatchEvents>(event: K, callback: BatchEvents[K]): void;
     /**
@@ -120,6 +157,9 @@ export declare class BatchPrintManager {
     addJob(data: Uint8Array, priority?: number, metadata?: Record<string, unknown>): string;
     /**
      * Add multiple jobs at once
+     *
+     * @param jobs - Array of job data with optional priority and metadata
+     * @returns Array of job IDs
      */
     addJobs(jobs: Array<{
         data: Uint8Array;
@@ -128,6 +168,9 @@ export declare class BatchPrintManager {
     }>): string[];
     /**
      * Cancel a job by ID
+     *
+     * @param id - Job ID to cancel
+     * @returns true if cancelled, false if not found
      */
     cancelJob(id: string): boolean;
     /**
@@ -140,14 +183,20 @@ export declare class BatchPrintManager {
     get pendingCount(): number;
     /**
      * Get pending jobs
+     *
+     * @returns Copy of pending jobs array
      */
     getPendingJobs(): BatchJob[];
     /**
      * Get current statistics
+     *
+     * @returns Copy of current stats
      */
     getStats(): BatchStats;
     /**
      * Update configuration
+     *
+     * @param updates - Configuration fields to update
      */
     updateConfig(updates: Partial<BatchConfig>): void;
     /**
@@ -163,8 +212,41 @@ export declare class BatchPrintManager {
     private prepareBatch;
     /**
      * Merge multiple jobs into a single buffer
+     *
+     * Features:
+     * - Consecutive small jobs (< smallJobThreshold bytes) are combined into a single job
+     * - Applies unified cut command after all jobs if configured
+     *
+     * @param jobs - Jobs to merge
+     * @returns Merged data with metadata about the merge operation
      */
     private mergeJobs;
+    /**
+     * Merge consecutive small jobs (< smallJobThreshold bytes) into combined buffers
+     *
+     * Small jobs that arrive consecutively are combined to reduce Bluetooth overhead.
+     * The merge preserves job boundaries conceptually but sends as a single chunk.
+     *
+     * @param jobs - Input jobs
+     * @returns Jobs after merging consecutive small ones
+     */
+    private mergeConsecutiveSmallJobs;
+    /**
+     * Create a merged job from multiple small buffers
+     *
+     * @param buffers - Array of small buffers to combine
+     * @param priority - Priority of the merged job
+     * @param addedAt - Timestamp of the first job in the merge
+     * @returns Merged BatchJob
+     */
+    private createMergedJob;
+    /**
+     * Concatenate multiple Uint8Array buffers into one
+     *
+     * @param buffers - Array of buffers to concatenate
+     * @returns Combined buffer
+     */
+    private concatBuffers;
     /**
      * Check if we should process immediately
      */
@@ -177,6 +259,17 @@ export declare class BatchPrintManager {
      * Clear wait timer
      */
     private clearWaitTimer;
+    /**
+     * Start the flush timer (interval timeout auto-flush)
+     *
+     * If no new jobs arrive within flushIntervalTimeout ms, the pending
+     * jobs are automatically flushed via the 'auto-flush' event.
+     */
+    private startFlushTimer;
+    /**
+     * Clear flush timer
+     */
+    private clearFlushTimer;
     /**
      * Start auto-process timer
      */

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

@@ -0,0 +1,189 @@
+/**
+ * Print Statistics Service
+ *
+ * Tracks and aggregates print job statistics including success rates,
+ * performance metrics, and breakdowns by date/driver.
+ *
+ * @example
+ * ```typescript
+ * const stats = new PrintStatistics();
+ * stats.trackJobStart('job-1', { driver: 'EscPos' });
+ * stats.trackJobComplete('job-1', 1024, 500);
+ * const report = stats.getStatistics();
+ * const json = stats.exportToJSON();
+ * ```
+ */
+/**
+ * Print statistics data interface (returned by getStatistics)
+ */
+export interface PrintStatisticsData {
+    /** Total jobs submitted */
+    totalJobs: number;
+    /** Successfully completed jobs */
+    completedJobs: number;
+    /** Failed jobs */
+    failedJobs: number;
+    /** Cancelled jobs */
+    cancelledJobs: number;
+    /** Total bytes printed */
+    totalBytes: number;
+    /** Average print time in milliseconds */
+    averagePrintTime: number;
+    /** Success rate (0-1) */
+    successRate: number;
+    /** Breakdown by date (YYYY-MM-DD) */
+    byDate: Record<string, {
+        completed: number;
+        failed: number;
+    }>;
+    /** Breakdown by driver name */
+    byDriver: Record<string, {
+        completed: number;
+        failed: number;
+    }>;
+}
+/**
+ * Job tracking metadata
+ */
+export interface JobTrackingMeta {
+    /** Driver name */
+    driver?: string;
+    /** Device ID */
+    deviceId?: string;
+    /** Device name */
+    deviceName?: string;
+    /** Priority */
+    priority?: number;
+    /** Additional metadata */
+    [key: string]: unknown;
+}
+/**
+ * Internal job record
+ */
+interface JobRecord {
+    id: string;
+    status: 'started' | 'completed' | 'failed' | 'cancelled';
+    startedAt: number;
+    completedAt?: number;
+    bytes?: number;
+    duration?: number;
+    error?: string;
+    driver?: string;
+    deviceId?: string;
+    deviceName?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Print Statistics Service
+ *
+ * Collects and aggregates print job metrics for analytics and monitoring.
+ * Provides breakdown by date and driver for detailed reporting.
+ */
+export declare class PrintStatistics {
+    private readonly logger;
+    /** Internal job records map */
+    private readonly jobs;
+    /** Statistics counters */
+    private totalJobs;
+    private completedJobs;
+    private failedJobs;
+    private cancelledJobs;
+    private totalBytes;
+    private totalPrintTime;
+    /** Date-based breakdown: YYYY-MM-DD -> { completed, failed } */
+    private byDate;
+    /** Driver-based breakdown: driverName -> { completed, failed } */
+    private byDriver;
+    /**
+     * Track a job start event
+     *
+     * @param jobId - Unique job identifier
+     * @param metadata - Optional job metadata (driver, device info, etc.)
+     */
+    trackJobStart(jobId: string, metadata?: JobTrackingMeta): void;
+    /**
+     * Track a job completion event
+     *
+     * @param jobId - Unique job identifier
+     * @param bytes - Number of bytes printed
+     * @param duration - Print duration in milliseconds
+     */
+    trackJobComplete(jobId: string, bytes: number, duration: number): void;
+    /**
+     * Track a job failure event
+     *
+     * @param jobId - Unique job identifier
+     * @param error - Error message or error object
+     */
+    trackJobFail(jobId: string, error: unknown): void;
+    /**
+     * Track a job cancellation event
+     *
+     * @param jobId - Unique job identifier
+     */
+    trackJobCancel(jobId: string): void;
+    /**
+     * Get current statistics
+     *
+     * @returns Complete statistics object
+     */
+    getStatistics(): PrintStatisticsData;
+    /**
+     * Export statistics as JSON string
+     *
+     * @param pretty - Whether to format with indentation (default: true)
+     * @returns JSON string representation
+     */
+    exportToJSON(pretty?: boolean): string;
+    /**
+     * Import statistics from JSON string
+     *
+     * @param json - JSON string to import
+     * @returns Number of records imported
+     */
+    importFromJSON(json: string): number;
+    /**
+     * Get statistics for a specific date range
+     *
+     * @param startDate - Start date (timestamp or Date)
+     * @param endDate - End date (timestamp or Date)
+     * @returns Filtered statistics
+     */
+    getStatisticsByDateRange(startDate: Date | number, endDate: Date | number): PrintStatisticsData;
+    /**
+     * Get breakdown by date
+     *
+     * @returns Date-based breakdown object
+     */
+    getByDate(): Record<string, {
+        completed: number;
+        failed: number;
+    }>;
+    /**
+     * Get breakdown by driver
+     *
+     * @returns Driver-based breakdown object
+     */
+    getByDriver(): Record<string, {
+        completed: number;
+        failed: number;
+    }>;
+    /**
+     * Reset all statistics
+     */
+    reset(): void;
+    /**
+     * Get job record by ID
+     *
+     * @param jobId - Job identifier
+     * @returns Job record or undefined
+     */
+    getJobRecord(jobId: string): JobRecord | undefined;
+    private formatDateKey;
+    private formatError;
+    private aggregateByDate;
+    private aggregateByDriver;
+}
+/** Singleton instance for convenience */
+export declare const printStatistics: PrintStatistics;
+export {};

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

@@ -0,0 +1,213 @@
+import { OfflineCache } from '../cache/OfflineCache';
+import { PrintQueue } from '../queue/PrintQueue';
+/**
+ * Scheduled retry entry
+ */
+export interface ScheduledRetry {
+    /** Job ID to retry */
+    jobId: string;
+    /** Scheduled execution time */
+    runAt: Date;
+    /** Current attempt count */
+    attemptCount: number;
+    /** Maximum retry attempts */
+    maxAttempts: number;
+    /** Base delay in ms for exponential backoff */
+    baseDelay: number;
+    /** Maximum delay in ms for exponential backoff */
+    maxDelay: number;
+    /** Last error message */
+    lastError?: string;
+    /** Scheduled timeout reference (internal, not serialized) */
+    timeout?: ReturnType<typeof setTimeout>;
+}
+/**
+ * Retry options
+ */
+export interface RetryOptions {
+    /** Base delay in ms (default: 1000) */
+    baseDelay?: number;
+    /** Maximum delay in ms (default: 60000) */
+    maxDelay?: number;
+    /** Maximum attempts (default: 5) */
+    maxAttempts?: number;
+}
+/**
+ * Scheduler events
+ */
+export interface ScheduledRetryEvents {
+    'retry-due': {
+        entry: ScheduledRetry;
+    };
+    'retry-executed': {
+        entry: ScheduledRetry;
+        success: boolean;
+    };
+    'retry-cancelled': {
+        jobId: string;
+    };
+    'retry-exhausted': {
+        jobId: string;
+    };
+    'schedule-restored': {
+        count: number;
+    };
+}
+/**
+ * Event handler type
+ */
+type EventHandler<T> = (data: T) => void;
+/**
+ * Scheduled retry configuration
+ */
+export interface ScheduledRetryManagerConfig {
+    /** Default base delay in ms */
+    baseDelay: number;
+    /** Default max delay in ms */
+    maxDelay: number;
+    /** Default max attempts */
+    maxAttempts: number;
+    /** Persist scheduled retries to OfflineCache */
+    persistEnabled: boolean;
+    /** Restore pending retries on startup */
+    autoRestore: boolean;
+}
+/**
+ * Scheduled Retry Manager
+ *
+ * Manages time-based retries for failed print jobs with support for:
+ * - Scheduled execution at specific times
+ * - Exponential backoff between retries
+ * - Persistence across process restarts via OfflineCache
+ * - Event-driven callbacks for retry execution
+ */
+export declare class ScheduledRetryManager {
+    private readonly logger;
+    /** Scheduled retries map: jobId -> ScheduledRetry */
+    private readonly scheduledRetries;
+    /** Event listeners */
+    private readonly listeners;
+    /** Configuration */
+    private readonly config;
+    /** Offline cache instance for persistence */
+    private readonly offlineCache;
+    /** Print queue reference for requeueing jobs */
+    private printQueue;
+    /** Retry executor function */
+    private retryExecutor;
+    /**
+     * Creates a new ScheduledRetryManager instance
+     *
+     * @param config - Optional configuration overrides
+     * @param offlineCache - Optional OfflineCache instance (uses singleton if not provided)
+     */
+    constructor(config?: Partial<ScheduledRetryManagerConfig>, offlineCache?: OfflineCache);
+    /**
+     * Set the print queue for job requeuing
+     *
+     * @param queue - PrintQueue instance
+     */
+    setPrintQueue(queue: PrintQueue): void;
+    /**
+     * Set the retry executor function
+     *
+     * @param executor - Async function that executes the retry
+     */
+    setRetryExecutor(executor: (jobId: string) => Promise<void>): void;
+    /**
+     * Schedule a retry for a specific job at a given time
+     *
+     * @param jobId - Job identifier to retry
+     * @param runAt - Date/time to execute the retry
+     * @param options - Optional retry configuration
+     */
+    scheduleRetry(jobId: string, runAt: Date, options?: RetryOptions): void;
+    /**
+     * Schedule a retry with exponential backoff starting from now
+     *
+     * @param jobId - Job identifier to retry
+     * @param options - Retry options including baseDelay, maxDelay, maxAttempts
+     */
+    scheduleRetryWithBackoff(jobId: string, options?: RetryOptions): void;
+    /**
+     * Cancel a scheduled retry
+     *
+     * @param jobId - Job identifier to cancel
+     * @returns true if a retry was cancelled, false if not found
+     */
+    cancelRetry(jobId: string): boolean;
+    /**
+     * Get all scheduled retries
+     *
+     * @returns Array of scheduled retry entries (without timeout refs)
+     */
+    getScheduledRetries(): Array<{
+        jobId: string;
+        runAt: Date;
+    }>;
+    /**
+     * Get a specific scheduled retry entry
+     *
+     * @param jobId - Job identifier
+     * @returns Scheduled retry entry or undefined
+     */
+    getScheduledRetry(jobId: string): ScheduledRetry | undefined;
+    /**
+     * Check if a job has a scheduled retry
+     *
+     * @param jobId - Job identifier
+     * @returns true if retry is scheduled
+     */
+    hasScheduledRetry(jobId: string): boolean;
+    /**
+     * Get count of scheduled retries
+     *
+     * @returns Number of pending scheduled retries
+     */
+    get pendingCount(): number;
+    /**
+     * Register event listener
+     *
+     * @param event - Event name
+     * @param callback - Event handler
+     */
+    on<K extends keyof ScheduledRetryEvents>(event: K, callback: EventHandler<ScheduledRetryEvents[K]>): void;
+    /**
+     * Remove event listener
+     *
+     * @param event - Event name
+     * @param callback - Event handler to remove
+     */
+    off<K extends keyof ScheduledRetryEvents>(event: K, callback: EventHandler<ScheduledRetryEvents[K]>): void;
+    /**
+     * Clear all scheduled retries
+     */
+    clearAll(): void;
+    /**
+     * Destroy the manager
+     */
+    destroy(): void;
+    /**
+     * Execute a scheduled retry
+     */
+    private executeRetry;
+    /**
+     * Persist a scheduled retry to OfflineCache
+     */
+    private persistRetry;
+    /**
+     * Remove a persisted retry from OfflineCache
+     */
+    private removePersistedRetry;
+    /**
+     * Restore scheduled retries from OfflineCache on startup
+     */
+    private restoreScheduledRetries;
+    /**
+     * Emit an event
+     */
+    private emit;
+}
+/** Singleton instance */
+export declare const scheduledRetryManager: ScheduledRetryManager;
+export {};

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

@@ -5,7 +5,9 @@
 export { ConnectionManager, type ConnectionManagerConfig, type ConnectionManagerEvents, } from './ConnectionManager';
 export { CommandBuilder } from './CommandBuilder';
 export { PrintJobManager } from './PrintJobManager';
-export { PrintHistory, printHistory, type PrintHistoryEntry, type PrintHistoryStats, type HistoryQueryOptions } from './PrintHistory';
-export { PrinterStatus, printerStatus, type PrinterStatusInfo, type StatusQueryOptions, type PaperStatus } from './PrinterStatus';
-export { BatchPrintManager, batchPrintManager, type BatchJob, type BatchConfig, type BatchStats, type BatchEvents } from './BatchPrintManager';
+export { PrintHistory, printHistory, type PrintHistoryEntry, type PrintHistoryStats, type HistoryQueryOptions, } from './PrintHistory';
+export { PrinterStatus, printerStatus, type PrinterStatusInfo, type StatusQueryOptions, type PaperStatus, } from './PrinterStatus';
+export { BatchPrintManager, batchPrintManager, type BatchJob, type BatchConfig, type BatchStats, type BatchEvents, } from './BatchPrintManager';
+export { PrintStatistics, printStatistics, type PrintStatisticsData, type JobTrackingMeta, } from './PrintStatistics';
+export { ScheduledRetryManager, scheduledRetryManager, type ScheduledRetry, type RetryOptions, type ScheduledRetryEvents, type ScheduledRetryManagerConfig, } from './ScheduledRetryManager';
 export * from './interfaces';