@ikilabs/pdf-to-img

A TypeScript library for converting PDF documents to images. Supports both single combined images (vertically stacked pages) and multiple individual page images.

Features

• Convert PDF to single combined image (all pages stacked vertically)
• Convert PDF to multiple individual page images
• Customizable viewport scaling for image quality
• Customizable background color for combined images
• TypeScript support with full type definitions
• Promise-based API
• Both buffer-based and file-based conversion methods

Installation

npm install @ikilabs/pdf-to-img

Compilation and Testing

Building the Library

# Install dependencies
npm install

# Compile TypeScript to JavaScript
npm run build

Running Tests

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage report
npm run test:coverage

The test suite includes:

• 20+ comprehensive test cases
• 80% minimum coverage requirement (currently achieving 100%)
• Mocked dependencies for reliable testing
• Sample PDF files for testing different scenarios

Usage

Basic Usage

import {
  convertPdfToImages,
  convertPdfFileToSingleImageFile,
  convertPdfFileToMultipleImageFiles
} from '@ikilabs/pdf-to-img';

// Convert PDF buffer to single combined image
const pdfBuffer = await fs.readFile('document.pdf');
const singleImage = await convertPdfToImages(pdfBuffer, 'single');
await fs.writeFile('output.png', singleImage as Buffer);

// Convert PDF buffer to multiple page images
const multipleImages = await convertPdfToImages(pdfBuffer, 'multiple');
for (let i = 0; i < multipleImages.length; i++) {
  await fs.writeFile(`page_${i + 1}.png`, multipleImages[i] as Buffer);
}

File-based Conversion

// Convert PDF file to single combined image file
await convertPdfFileToSingleImageFile(
  'input.pdf',
  'output.png',
  { viewportScale: 2.0, backgroundColor: 0xffffffff }
);

// Convert PDF file to multiple image files
await convertPdfFileToMultipleImageFiles(
  'input.pdf',
  './output-directory',
  { viewportScale: 1.5 }
);

Advanced Options

// Custom options
const options = {
  viewportScale: 2.0,        // Higher values = better quality, larger files
  backgroundColor: 0xff0000ff // Red background (RGBA format)
};

const result = await convertPdfToImages(pdfBuffer, 'single', options);

API Reference

convertPdfToImages(pdfBuffer, mode, options?)

Converts a PDF buffer to image buffer(s).

Parameters:

• pdfBuffer: Buffer - The PDF data as a Buffer
• mode: 'single' | 'multiple' - Conversion mode
• options?: object - Optional conversion options
  • viewportScale?: number - Scaling factor (default: 2.0)
  • backgroundColor?: number - Background color in RGBA format (default: 0xffffffff)

Returns: Promise<Buffer | Buffer[]>

• Buffer for single mode
• Buffer[] for multiple mode

convertPdfFileToSingleImageFile(inputPath, outputPath, options?)

Converts a PDF file to a single combined image file.

Parameters:

• inputPath: string - Path to input PDF file
• outputPath: string - Path to output image file
• options?: object - Optional conversion options

Returns: Promise<void>

convertPdfFileToMultipleImageFiles(inputPath, outputDir, options?)

Converts a PDF file to multiple individual image files.

Parameters:

• inputPath: string - Path to input PDF file
• outputDir: string - Directory for output image files
• options?: object - Optional conversion options (viewportScale only)

Returns: Promise<void>

Using in TypeScript Projects

1. Install the package

npm install @ikilabs/pdf-to-img

2. Import and use in your TypeScript code

import { convertPdfToImages } from '@ikilabs/pdf-to-img';
import * as fs from 'fs/promises';

async function convertMyPdf() {
  try {
    const pdfBuffer = await fs.readFile('document.pdf');
    
    // Convert to single image
    const singleImage = await convertPdfToImages(pdfBuffer, 'single', {
      viewportScale: 2.0,
      backgroundColor: 0xffffffff
    });
    
    await fs.writeFile('output.png', singleImage as Buffer);
    console.log('PDF converted successfully!');
  } catch (error) {
    console.error('Conversion failed:', error);
  }
}

convertMyPdf();

3. Type safety

The library includes full TypeScript definitions, so you'll get:

• IntelliSense and auto-completion
• Type checking at compile time
• Clear parameter and return type information

Error Handling

The library throws errors for common issues:

try {
  const result = await convertPdfToImages(pdfBuffer, 'single');
} catch (error) {
  if (error.message === 'No pages found in PDF') {
    console.log('PDF appears to be empty');
  } else {
    console.log('Conversion failed:', error.message);
  }
}

Requirements

• Node.js 18+ (recommended)
• TypeScript 5.0+ (for development)

Dependencies

• jimp - Image processing
• pdf-to-png-converter - PDF to PNG conversion

License

MIT