npm package: @ikilabs/pdf-to-img
Description: A library to convert PDFs to images (single combined or per-page)
Author: Alejandro Narancio
Latest version: 1.0.0

# @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

```bash
npm install @ikilabs/pdf-to-img
```

## Compilation and Testing

### Building the Library

```bash
# Install dependencies
npm install

# Compile TypeScript to JavaScript
npm run build
```

### Running Tests

```bash
# 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

```typescript
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

```typescript
// 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

```typescript
// 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

```bash
npm install @ikilabs/pdf-to-img
```

### 2. Import and use in your TypeScript code

```typescript
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:

```typescript
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