smartpreview/readme.md

@push.rocks/smartpreview 🖼️

Lightning-fast PDF to JPEG preview generation for Node.js and browsers ⚡

Transform your PDFs into beautiful JPEG previews with zero hassle. Whether you're building a document viewer, thumbnail generator, or file management system, SmartPreview delivers high-quality results in both server and browser environments.

✨ Features

• 🌐 Universal: Works seamlessly in Node.js and browsers
• ⚡ Fast: Web Worker-based processing for non-blocking operations
• 🎯 Precise: Configurable quality, dimensions, and page selection
• 🛡️ Type-Safe: Full TypeScript support with comprehensive type definitions
• 🔧 Extensible: Built to support additional formats in the future
• 📦 Zero Config: Works out of the box with sensible defaults
• 🎨 High Quality: Professional-grade JPEG output with customizable compression

🚀 Quick Start

Installation

# Using pnpm (recommended)
pnpm install @push.rocks/smartpreview

# Using npm
npm install @push.rocks/smartpreview

# Using yarn
yarn add @push.rocks/smartpreview

Node.js Usage

Perfect for server-side processing, APIs, and build tools:

import { SmartPreview } from '@push.rocks/smartpreview';

// Initialize the preview generator
const preview = await SmartPreview.create();

// Generate preview from PDF buffer
const result = await preview.generatePreview(pdfBuffer, {
  quality: 85,
  width: 1200,
  height: 800,
  page: 1,
});

// result.buffer contains the JPEG data
console.log(
  `Generated ${result.size} byte preview: ${result.dimensions.width}x${result.dimensions.height}`
);

// Don't forget to cleanup
await preview.cleanup();

Browser Usage

Ideal for web applications, file uploads, and client-side processing:

import { SmartPreview } from '@push.rocks/smartpreview/web';

// Initialize with progress tracking
const preview = await SmartPreview.create();

// Generate preview from file input
const fileInput = document.querySelector('input[type="file"]');
const file = fileInput.files[0];

const result = await preview.generatePreview(file, {
  quality: 80,
  width: 800,
  height: 600,
  onProgress: (progress, stage) => {
    console.log(`${stage}: ${progress}%`);
  },
});

// Use the result
const img = document.createElement('img');
img.src = result.dataUrl; // Ready-to-use data URL
document.body.appendChild(img);

// Or create a download link
const { url, cleanup } = await preview.createDownloadLink(file, {}, 'preview.jpg');
// Use url for download, call cleanup() when done

📚 API Reference

Node.js API

SmartPreview

The main class for Node.js environments.

Methods

// Factory method (recommended)
static async create(options?: IPreviewOptions): Promise<SmartPreview>

// Manual initialization
async init(): Promise<void>
async cleanup(): Promise<void>

// Preview generation
async generatePreview(buffer: Buffer, options?: IPreviewOptions): Promise<IPreviewResult>
async generatePreviewFromFile(filePath: string, options?: IPreviewOptions): Promise<IPreviewResult>

// Save directly to file
async savePreview(buffer: Buffer, outputPath: string, options?: IPreviewOptions): Promise<void>

// Utility methods
getSupportedFormats(): string[]
isFormatSupported(format: string): boolean

Node.js Result

interface IPreviewResult {
  buffer: Buffer; // JPEG image data
  dimensions: {
    // Actual dimensions
    width: number;
    height: number;
  };
  size: number; // File size in bytes
  mimeType: 'image/jpeg'; // Always JPEG
}

Browser API

SmartPreview

The main class for browser environments with additional web-specific features.

Methods

// Factory method (recommended)
static async create(options?: IWebPreviewOptions): Promise<SmartPreview>

// Manual initialization
async init(): Promise<void>
async cleanup(): Promise<void>

// Preview generation
async generatePreview(input: TWebInputType, options?: IWebPreviewOptions): Promise<IPreviewResult>
async generatePreviewFromFile(file: File, options?: IWebPreviewOptions): Promise<IPreviewResult>
async generatePreviewFromUrl(url: string, options?: IWebPreviewOptions): Promise<IPreviewResult>

// Download functionality
async createDownloadLink(input: TWebInputType, options?: IWebPreviewOptions, filename?: string): Promise<{url: string, cleanup: () => void}>
async downloadPreview(input: TWebInputType, options?: IWebPreviewOptions, filename?: string): Promise<void>

// Browser compatibility
static getBrowserCompatibility(): {fileApi: boolean, webWorkers: boolean, offscreenCanvas: boolean, isSupported: boolean}
static isFileApiSupported(): boolean
static isWebWorkerSupported(): boolean
static isOffscreenCanvasSupported(): boolean

Web Input Types

type TWebInputType = File | Blob | ArrayBuffer | Uint8Array | string; // string = data URL

Web Result

interface IPreviewResult {
  blob: Blob; // JPEG image blob
  dimensions: {
    // Actual dimensions
    width: number;
    height: number;
  };
  size: number; // File size in bytes
  mimeType: 'image/jpeg'; // Always JPEG
  dataUrl: string; // Ready-to-use data URL (optional)
}

Configuration Options

Basic Options (IPreviewOptions)

interface IPreviewOptions {
  quality?: number; // JPEG quality 1-100 (default: 80)
  width?: number; // Max width in pixels (default: 800)
  height?: number; // Max height in pixels (default: 600)
  page?: number; // PDF page number 1-based (default: 1)
  scale?: number; // Scale factor (default: 1.0)
}

Web-Specific Options (IWebPreviewOptions)

interface IWebPreviewOptions extends IPreviewOptions {
  onProgress?: (progress: number, stage: string) => void; // Progress callback
  timeout?: number; // Worker timeout in ms (default: 30000)
  generateDataUrl?: boolean; // Generate data URL (default: true)
}

🎯 Advanced Examples

Server-Side Batch Processing

import { SmartPreview } from '@push.rocks/smartpreview';
import { promises as fs } from 'fs';
import path from 'path';

async function batchProcess(inputDir: string, outputDir: string) {
  const preview = await SmartPreview.create();

  try {
    const files = await fs.readdir(inputDir);
    const pdfFiles = files.filter((f) => f.endsWith('.pdf'));

    for (const file of pdfFiles) {
      const inputPath = path.join(inputDir, file);
      const outputPath = path.join(outputDir, file.replace('.pdf', '.jpg'));

      await preview.savePreview(await fs.readFile(inputPath), outputPath, {
        quality: 90,
        width: 1920,
        height: 1080,
      });

      console.log(`✅ Processed: ${file}`);
    }
  } finally {
    await preview.cleanup();
  }
}

Interactive File Upload

import { SmartPreview } from '@push.rocks/smartpreview/web';

class FilePreviewHandler {
  private preview: SmartPreview | null = null;

  async init() {
    // Check browser compatibility first
    const compat = SmartPreview.getBrowserCompatibility();
    if (!compat.isSupported) {
      throw new Error('Browser not supported');
    }

    this.preview = await SmartPreview.create();
  }

  async handleFileUpload(file: File): Promise<string> {
    if (!this.preview) throw new Error('Not initialized');

    // Generate preview with progress tracking
    const result = await this.preview.generatePreview(file, {
      quality: 85,
      width: 400,
      height: 300,
      onProgress: (progress, stage) => {
        this.updateProgress(progress, stage);
      },
    });

    return result.dataUrl;
  }

  private updateProgress(progress: number, stage: string) {
    console.log(`${stage}: ${Math.round(progress)}%`);
    // Update your UI here
  }

  async cleanup() {
    if (this.preview) {
      await this.preview.cleanup();
      this.preview = null;
    }
  }
}

Multi-Page Preview Generation

import { SmartPreview } from '@push.rocks/smartpreview';

async function generateMultiPagePreviews(pdfBuffer: Buffer, maxPages: number = 5) {
  const preview = await SmartPreview.create();
  const previews: Buffer[] = [];

  try {
    for (let page = 1; page <= maxPages; page++) {
      try {
        const result = await preview.generatePreview(pdfBuffer, {
          page,
          quality: 80,
          width: 600,
          height: 800,
        });

        previews.push(result.buffer);
        console.log(
          `📄 Generated preview for page ${page}: ${result.dimensions.width}x${result.dimensions.height}`
        );
      } catch (error) {
        // Page doesn't exist, stop here
        if (error.errorType === 'PAGE_NOT_FOUND') {
          break;
        }
        throw error; // Re-throw other errors
      }
    }
  } finally {
    await preview.cleanup();
  }

  return previews;
}

🛠️ Development

Setup

# Clone the repository
git clone https://code.foss.global/push.rocks/smartpreview.git
cd smartpreview

# Install dependencies
pnpm install

# Build the project
pnpm run build

# Run tests
pnpm test

Testing

The project includes comprehensive tests for both Node.js and browser environments:

# Run all tests
pnpm test

# Run only Node.js tests
pnpm tstest test/test.node.ts

# Run only browser tests
pnpm tstest test/test.browser.ts --web

Architecture

The library follows a dual-environment architecture:

📁 smartpreview/
├── 📁 ts/              # Node.js implementation
│   ├── smartpreview.ts  # Main Node.js class
│   ├── pdfprocessor.ts  # PDF processing with @push.rocks/smartpdf
│   └── interfaces.ts    # Shared interfaces
├── 📁 ts_web/          # Browser implementation
│   ├── smartpreview.ts  # Main browser class
│   ├── pdfprocessor.ts  # Web PDF processor
│   ├── pdfworker.ts     # PDF.js worker wrapper
│   └── interfaces.ts    # Web-specific interfaces
└── 📁 test/            # Comprehensive test suite

🔧 Error Handling

SmartPreview provides detailed error information through typed errors:

import { PreviewError } from '@push.rocks/smartpreview';

try {
  const result = await preview.generatePreview(invalidPdf);
} catch (error) {
  if (error instanceof PreviewError) {
    switch (error.errorType) {
      case 'PDF_CORRUPTED':
        console.error('The PDF file is corrupted');
        break;
      case 'PAGE_NOT_FOUND':
        console.error('Requested page does not exist');
        break;
      case 'INVALID_OPTIONS':
        console.error('Invalid configuration options');
        break;
      default:
        console.error(`Preview error: ${error.message}`);
    }
  }
}

Error Types

• INVALID_INPUT - Input data is invalid or missing
• UNSUPPORTED_FORMAT - File format not supported
• PROCESSING_FAILED - General processing error
• INVALID_OPTIONS - Configuration options are invalid
• PDF_CORRUPTED - PDF file is corrupted or invalid
• PAGE_NOT_FOUND - Requested page doesn't exist
• WORKER_ERROR - Web worker error (browser only)
• WORKER_TIMEOUT - Worker timeout (browser only)

🌟 Why SmartPreview?

• 🚀 Performance: Optimized for speed with worker-based processing
• 💪 Reliable: Battle-tested with comprehensive error handling
• 🔒 Type-Safe: Full TypeScript support prevents runtime errors
• 🌐 Universal: One API works everywhere - Node.js, browsers, edge functions
• 🎨 Quality: Professional-grade output with fine-tuned compression
• 📈 Scalable: Built for high-volume production use
• 🔮 Future-Proof: Extensible architecture ready for new formats

🤝 Contributing

We welcome contributions! Please see our contribution guidelines for details.

📄 Changelog

See CHANGELOG.md for version history and updates.

---

License and Legal Information

This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the license file within this repository.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.

Company Information

Task Venture Capital GmbH
Registered at District court Bremen HRB 35230 HB, Germany

For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.