Enhanced Printer Library

A powerful Node.js/Electron library for advanced PDF printing with job tracking, custom page sizes, and tray selection. Compatible with Node.js 20+ and Electron 39+.

Features

✅ PDF Printing - Print PDF files with full control
✅ Job ID Tracking - Retrieve Windows print spooler job IDs
✅ Custom Page Sizes - Support for standard and custom paper sizes
✅ Tray Selection - Select specific printer trays/bins
✅ Default Preferences - Automatically uses printer defaults when settings not specified
✅ Job Monitoring - Query job status and manage print queue
✅ Electron Compatible - Works seamlessly with Electron 39+

Installation

npm install enhanced-printer

Note: Replace enhanced-printer with the actual package name you choose when publishing to npm. Check PUBLISH-CHECKLIST.md for publishing steps.

Requirements

• Node.js: 20.0.0 or higher
• Electron: 39.0.0 or higher (optional)
• OS: Windows (uses PowerShell for job tracking)

Quick Start

const { print, getPrinters } = require('enhanced-printer');

async function printPDF() {
  // Get available printers
  const printers = await getPrinters();
  console.log('Available printers:', printers);
  
  // Print with default settings
  const result = await print({
    printerName: 'Your Printer Name',
    filePath: 'C:\\path\\to\\document.pdf'
  });
  
  console.log('Success:', result.success);
  console.log('Job ID:', result.jobId);
}

printPDF();

Available Methods

• print() - Print PDF with custom settings
• getPrinters() - Get list of available printers
• getDefaultPrinter() - Get default printer name
• getJobs() - Get all print jobs with custom names
• getPrinterJobs() - Get all print jobs (alias for getJobs)
• getJobStatus() - Get status of specific job by ID
• cancelJob() - Cancel a print job

API Reference

print(options: PrintOptions): Promise<PrintResult>

Prints a PDF file with the specified options.

Parameters:

interface PrintOptions {
  printerName: string;     // Required: Name of the printer
  filePath: string;        // Required: Path to PDF file
  
  // Optional settings - defaults to printer preferences if not specified
  pageSize?: string;       // e.g., "A4", "A5", "A6", "Letter", "Legal"
  tray?: string | number;  // Tray name or number
  jobName?: string;        // Document/job name for tracking
  copies?: number;         // Number of copies
  orientation?: 'portrait' | 'landscape';
  duplex?: 'simplex' | 'duplex';
  monochrome?: boolean;    // Black & white printing
  pages?: string;          // e.g., "1-3,5" to print specific pages
  subset?: 'odd' | 'even'; // Print only odd or even pages
}

Returns:

interface PrintResult {
  success: boolean;
  jobId?: number;        // Job ID from print spooler (if available)
  jobName: string;       // Document name used for tracking
  error?: string;        // Error message if print failed
}

Example:

const result = await print({
  printerName: 'HP LaserJet',
  filePath: './invoice.pdf',
  pageSize: 'A4',
  tray: 2,
  copies: 2
});

getPrinters(): Promise<PrinterInfo[]>

Gets a list of available printers.

Returns:

interface PrinterInfo {
  name: string;
  isDefault: boolean;
  status: string;
}

Example:

const printers = await getPrinters();
printers.forEach(p => {
  console.log(`${p.name} - ${p.status} ${p.isDefault ? '(Default)' : ''}`);
});

getDefaultPrinter(): Promise<string | null>

Gets the name of the default printer.

getJobStatus(printerName: string, jobId: number): Promise<JobInfo | null>

Gets information about a specific print job.

Example:

const jobInfo = await getJobStatus('HP LaserJet', 123);
console.log('Status:', jobInfo.status);
console.log('Pages:', jobInfo.pages);

getPrinterJobs(printerName: string): Promise<JobInfo[]>

Gets all print jobs for a specific printer.

cancelJob(printerName: string, jobId: number): Promise<boolean>

Cancels a print job.

Usage Examples

Using Printer Defaults

When you don't specify optional settings, the library automatically uses the printer's default configuration:

// Uses printer's default page size, tray, and other settings
const result = await print({
  printerName: 'My Printer',
  filePath: './document.pdf'
});

Custom Page Size with Default Tray

// Custom page size, but uses printer's default tray
const result = await print({
  printerName: 'Label Printer',
  filePath: './label.pdf',
  pageSize: 'A6'  // 4x6 inches for labels
  // tray not specified - uses default
});

Custom Tray with Default Page Size

// Specific tray, but uses printer's default page size
const result = await print({
  printerName: 'Office Printer',
  filePath: './document.pdf',
  tray: 'Tray 2'  // or use number: tray: 2
  // pageSize not specified - uses default
});

Multiple Custom Settings

const result = await print({
  printerName: 'My Printer',
  filePath: './document.pdf',
  pageSize: 'Legal',
  tray: 1,
  copies: 3,
  orientation: 'landscape',
  duplex: 'duplex',
  monochrome: true,
  jobName: 'Important-Document'
});

Job Tracking

const result = await print({
  printerName: 'My Printer',
  filePath: './document.pdf'
});

if (result.jobId) {
  // Monitor job status
  const jobInfo = await getJobStatus('My Printer', result.jobId);
  console.log(`Job ${jobInfo.jobId}: ${jobInfo.status}`);
  
  // Cancel if needed
  // await cancelJob('My Printer', result.jobId);
}

Electron Integration

See examples/electron-integration.js for a complete example.

Main Process:

const { ipcMain } = require('electron');
const { print, getPrinters } = require('@your-org/enhanced-printer');

ipcMain.handle('print-pdf', async (event, options) => {
  return await print(options);
});

ipcMain.handle('get-printers', async () => {
  return await getPrinters();
});

Renderer Process:

const result = await window.printerAPI.print({
  printerName: 'My Printer',
  filePath: pdfPath
});

TypeScript Support

This library is written in TypeScript and includes full type definitions.

import { print, PrintOptions, PrintResult } from '@your-org/enhanced-printer';

const options: PrintOptions = {
  printerName: 'My Printer',
  filePath: './document.pdf',
  pageSize: 'A4'
};

const result: PrintResult = await print(options);

How It Works

1. PDF Printing: Uses pdf-to-printer library which wraps SumatraPDF on Windows
2. Job ID Retrieval: Queries Windows print spooler using PowerShell commands
3. Default Settings: When settings aren't specified, SumatraPDF uses the printer's DEVMODE defaults

Limitations

• Windows Only: Job ID tracking requires PowerShell (Windows-specific)
• PDF Files: Designed for PDF printing (for raw data, convert to PDF first)
• Job ID Timing: Very fast printers may complete jobs before ID can be retrieved

Examples

See the examples/ directory for complete working examples:

• basic-print.js - Simple printing with defaults
• custom-settings.js - Custom page sizes, trays, and options
• job-monitoring.js - Job status tracking
• electron-integration.js - Electron app integration

Troubleshooting

Job ID is undefined

This can happen if:

• The print job completes very quickly
• The printer isn't accessible
• PowerShell execution is blocked

The library will still print successfully; only job ID retrieval may fail.

Custom page size not working

Ensure the page size is either:

1. A standard size name ("A4", "Letter", etc.)
2. A custom size that's been pre-configured in Windows printer settings

Printer not found

Use getPrinters() to see available printers and verify the exact printer name (case-sensitive).

License

MIT

Contributing

Contributions welcome! Please open an issue or pull request.