enhanced-printer 1.0.7 → 1.0.9

package/README.md

@@ -59,6 +59,7 @@ printPDF();
 | `getJobInfo()` | Get info of a specific job by custom job name |
 | `getJobs()` | Get all print jobs for a printer |
 | `cancelJob()` | Cancel a print job by custom job name |
+| `watchJob()` | Poll a job until it completes, errors, or times out |
 
 ## API Reference
 
@@ -210,6 +211,72 @@ console.log('Cancelled:', cancelled);
 
 ---
 
+### `watchJob(customJobName: string, printerName?: string, options?: WatchJobOptions): Promise<WatchJobResult>`
+
+Polls a print job at regular intervals until it completes, enters an error state, is aborted, or times out.
+
+> **Why use this?** Windows removes completed jobs from the print queue immediately. Without `watchJob`, polling `getJobInfo` after completion returns `null`, which is indistinguishable from an error. `watchJob` tracks the last known status and correctly resolves a vanished job as `COMPLETED`.
+
+**Options:**
+
+```typescript
+interface WatchJobOptions {
+  pollInterval?: number;                       // ms between polls (default: 500)
+  timeout?: number;                            // max wait ms — 0 or omit = no timeout (default: 0)
+  onStatusChange?: (status: string[]) => void; // called on every status change
+  signal?: AbortSignal;                        // AbortController signal for manual stop
+}
+```
+
+**Returns:**
+
+```typescript
+interface WatchJobResult {
+  finalStatus: string[];   // e.g. ["COMPLETED"], ["ERROR"], ["ABORTED"]
+  completed: boolean;      // true = success, false = error / timed out / aborted
+}
+```
+
+**Example — basic watch with timeout:**
+
+```javascript
+const { finalStatus, completed } = await watchJob('Invoice_12345', undefined, {
+  timeout: 30000,           // stop after 30 seconds
+  pollInterval: 500,
+  onStatusChange: (status) => console.log('Status:', status)
+});
+
+console.log('Completed:', completed);      // true
+console.log('Final status:', finalStatus); // ["COMPLETED"]
+```
+
+**Example — watch indefinitely (no timeout):**
+
+```javascript
+// timeout: 0 (default) = never times out, watches until job finishes or errors
+const { finalStatus, completed } = await watchJob('Invoice_12345');
+```
+
+**Example — manual stop via AbortController:**
+
+```javascript
+const controller = new AbortController();
+
+// Start watching (doesn't block — run via Promise if needed)
+const watchPromise = watchJob('Invoice_12345', undefined, {
+  signal: controller.signal,
+  onStatusChange: (status) => console.log('Status:', status)
+});
+
+// Stop watching manually (e.g. user cancelled, component unmounted, etc.)
+controller.abort();
+
+const { finalStatus } = await watchPromise;
+console.log(finalStatus); // ["ABORTED"]
+```
+
+---
+
 ## Usage Examples
 
 ### Using Printer Defaults

package/lib/index.d.ts

@@ -10,5 +10,6 @@
  * - Automatic use of printer defaults when settings not specified
  * - Query job status and printer information
  */
-export { print, getPrinters, getDefaultPrinter, getJobInfo, getJobs, cancelJob } from './print-manager';
+export { print, getPrinters, getDefaultPrinter, getJobInfo, getJobs, cancelJob, watchJob } from './print-manager';
 export { PrintOptions, PrintResult, PrinterInfo, JobInfo } from './types';
+export { WatchJobOptions, WatchJobResult } from './job-tracker';

package/lib/index.js

@@ -12,7 +12,7 @@
  * - Query job status and printer information
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.cancelJob = exports.getJobs = exports.getJobInfo = exports.getDefaultPrinter = exports.getPrinters = exports.print = void 0;
+exports.watchJob = exports.cancelJob = exports.getJobs = exports.getJobInfo = exports.getDefaultPrinter = exports.getPrinters = exports.print = void 0;
 var print_manager_1 = require("./print-manager");
 Object.defineProperty(exports, "print", { enumerable: true, get: function () { return print_manager_1.print; } });
 Object.defineProperty(exports, "getPrinters", { enumerable: true, get: function () { return print_manager_1.getPrinters; } });
@@ -20,3 +20,4 @@ Object.defineProperty(exports, "getDefaultPrinter", { enumerable: true, get: fun
 Object.defineProperty(exports, "getJobInfo", { enumerable: true, get: function () { return print_manager_1.getJobInfo; } });
 Object.defineProperty(exports, "getJobs", { enumerable: true, get: function () { return print_manager_1.getJobs; } });
 Object.defineProperty(exports, "cancelJob", { enumerable: true, get: function () { return print_manager_1.cancelJob; } });
+Object.defineProperty(exports, "watchJob", { enumerable: true, get: function () { return print_manager_1.watchJob; } });

package/lib/job-tracker.d.ts

@@ -12,6 +12,48 @@ export declare function getJobInfoBySystemId(printerName: string, jobId: number)
  * Resolves the custom job name to the system job ID, then queries the spooler
  */
 export declare function getJobInfo(customJobName: string, printerName?: string): Promise<JobInfo | null>;
+export interface WatchJobResult {
+    /** Final resolved status of the job */
+    finalStatus: string[];
+    /** True if the job completed successfully, false if it errored or timed out */
+    completed: boolean;
+}
+export interface WatchJobOptions {
+    /** Milliseconds between each status poll (default: 500) */
+    pollInterval?: number;
+    /**
+     * Maximum time to wait in milliseconds before giving up.
+     * Set to 0 or omit to watch indefinitely (no timeout).
+     * Default: 0 (no timeout)
+     */
+    timeout?: number;
+    /** Called every time the job status changes */
+    onStatusChange?: (status: string[]) => void;
+    /**
+     * An AbortSignal to stop watching manually.
+     * Call controller.abort() on the corresponding AbortController to stop.
+     * @example
+     * const controller = new AbortController();
+     * watchJob('MyJob', undefined, { signal: controller.signal });
+     * // later...
+     * controller.abort(); // stops watching
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Polls a print job until it finishes, is aborted, times out, or enters an error state.
+ *
+ * Handles the Windows spooler race condition where completed jobs are
+ * immediately removed from the queue (making them indistinguishable from
+ * missing jobs). If the job disappears and the last known status was not
+ * an error, it is treated as successfully COMPLETED.
+ *
+ * @example No timeout, manual stop via AbortController:
+ * const controller = new AbortController();
+ * const result = await watchJob('MyJob', undefined, { signal: controller.signal });
+ * // elsewhere: controller.abort();
+ */
+export declare function watchJob(customJobName: string, printerName?: string, options?: WatchJobOptions): Promise<WatchJobResult>;
 /**
  * Gets all print jobs for a printer with enhanced details
  */

package/lib/job-tracker.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.getJobIdByName = getJobIdByName;
 exports.getJobInfoBySystemId = getJobInfoBySystemId;
 exports.getJobInfo = getJobInfo;
+exports.watchJob = watchJob;
 exports.getAllJobs = getAllJobs;
 const child_process_1 = require("child_process");
 const job_name_mapper_1 = require("./job-name-mapper");
@@ -110,6 +111,70 @@ async function getJobInfo(customJobName, printerName) {
     }
     return getJobInfoBySystemId(mapping.printerName, mapping.jobId);
 }
+/** Status flags that indicate a job has stopped due to a problem */
+const ERROR_STATUSES = ['ERROR', 'OFFLINE', 'PAPER_OUT', 'USER_INTERVENTION', 'DELETED', 'DELETING'];
+/** Status flags that indicate a job has finished successfully */
+const DONE_STATUSES = ['PRINTED', 'COMPLETE'];
+/**
+ * Polls a print job until it finishes, is aborted, times out, or enters an error state.
+ *
+ * Handles the Windows spooler race condition where completed jobs are
+ * immediately removed from the queue (making them indistinguishable from
+ * missing jobs). If the job disappears and the last known status was not
+ * an error, it is treated as successfully COMPLETED.
+ *
+ * @example No timeout, manual stop via AbortController:
+ * const controller = new AbortController();
+ * const result = await watchJob('MyJob', undefined, { signal: controller.signal });
+ * // elsewhere: controller.abort();
+ */
+async function watchJob(customJobName, printerName, options = {}) {
+    const { pollInterval = 500, timeout = 0, onStatusChange, signal } = options;
+    const hasTimeout = timeout > 0;
+    const deadline = hasTimeout ? Date.now() + timeout : Infinity;
+    let lastKnownStatus = ['INQUEUE'];
+    while (Date.now() < deadline) {
+        // Check if manually aborted
+        if (signal?.aborted) {
+            return { finalStatus: ['ABORTED'], completed: false };
+        }
+        const jobInfo = await getJobInfo(customJobName, printerName);
+        if (jobInfo === null) {
+            // Job has disappeared from the queue.
+            // If the last known status was a hard error, surface that.
+            // Otherwise, Windows removed it because it finished — treat as COMPLETED.
+            const hadError = lastKnownStatus.some(s => ERROR_STATUSES.includes(s));
+            return {
+                finalStatus: hadError ? lastKnownStatus : ['COMPLETED'],
+                completed: !hadError
+            };
+        }
+        const currentStatus = jobInfo.status;
+        // Notify caller if status changed
+        if (JSON.stringify(currentStatus) !== JSON.stringify(lastKnownStatus)) {
+            lastKnownStatus = currentStatus;
+            onStatusChange?.(currentStatus);
+        }
+        // Job explicitly marked as done
+        if (currentStatus.some(s => DONE_STATUSES.includes(s))) {
+            return { finalStatus: ['COMPLETED'], completed: true };
+        }
+        // Job is in a hard-error state — stop polling
+        if (currentStatus.some(s => ERROR_STATUSES.includes(s))) {
+            return { finalStatus: currentStatus, completed: false };
+        }
+        // Sleep for pollInterval, but wake early if aborted
+        await new Promise(resolve => {
+            const timer = setTimeout(resolve, pollInterval);
+            signal?.addEventListener('abort', () => {
+                clearTimeout(timer);
+                resolve();
+            }, { once: true });
+        });
+    }
+    // Timed out
+    return { finalStatus: lastKnownStatus, completed: false };
+}
 /**
  * Gets all print jobs for a printer with enhanced details
  */

package/lib/print-manager.d.ts

@@ -1,4 +1,5 @@
 import { PrintOptions, PrintResult, PrinterInfo, JobInfo } from './types';
+import { WatchJobOptions, WatchJobResult } from './job-tracker';
 /**
  * Prints a PDF file with the specified options
  */
@@ -23,3 +24,8 @@ export declare function getJobs(printerName: string): Promise<JobInfo[]>;
  * Cancels a print job using custom job name
  */
 export declare function cancelJob(customJobName: string, printerName?: string): Promise<boolean>;
+/**
+ * Watches a print job until it completes, errors, or times out.
+ * Handles the Windows spooler race condition where completed jobs disappear from the queue.
+ */
+export declare function watchJob(customJobName: string, printerName?: string, options?: WatchJobOptions): Promise<WatchJobResult>;

package/lib/print-manager.js

@@ -6,6 +6,7 @@ exports.getDefaultPrinter = getDefaultPrinter;
 exports.getJobInfo = getJobInfo;
 exports.getJobs = getJobs;
 exports.cancelJob = cancelJob;
+exports.watchJob = watchJob;
 const pdf_to_printer_1 = require("pdf-to-printer");
 const uuid_1 = require("uuid");
 const child_process_1 = require("child_process");
@@ -150,6 +151,13 @@ async function cancelJob(customJobName, printerName) {
         return false;
     }
 }
+/**
+ * Watches a print job until it completes, errors, or times out.
+ * Handles the Windows spooler race condition where completed jobs disappear from the queue.
+ */
+async function watchJob(customJobName, printerName, options = {}) {
+    return (0, job_tracker_1.watchJob)(customJobName, printerName, options);
+}
 /**
  * Executes a PowerShell script and returns output
  */
@@ -170,7 +178,7 @@ function executePowerShell(script) {
             errorOutput += data.toString();
         });
         ps.on('close', (code) => {
-            if (code === 0 && output.trim()) {
+            if (code === 0) {
                 resolve(output.trim());
             }
             else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "enhanced-printer",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "description": "Advanced PDF printing library with job tracking, custom page sizes, and tray selection for Node.js and Electron",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",