safeer-pdf-generator

A powerful, framework-agnostic TypeScript library for generating PDF reports with chunking, merging, S3 upload, and email delivery.

✨ Features

• 🚀 High Performance - Concurrent processing with memory optimization
• 📊 Rich Templates - Built-in templates with charts and styling
• 🔧 Framework Agnostic - Works with Express, NestJS, Fastify, or standalone
• ☁️ S3 Integration - Direct upload to Amazon S3 with presigned URLs
• 📧 Email Delivery - Send PDFs as attachments or download links
• 🔀 PDF Operations - Merge, split, and manipulate existing PDFs
• 💾 Memory Efficient - Handle large datasets (100k+ records)
• 🛡️ TypeScript - Full type safety and IntelliSense support

📦 Installation

Prerequisites

This package requires Chromium to be installed on your system for PDF generation:

# Install Chromium
sudo apt-get install chromium-browser

# Or set custom path
export PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium-browser

Package Installation

npm install safeer-pdf-generator

# Optional peer dependencies for S3 and email
npm install @aws-sdk/client-s3 nodemailer

🚀 Quick Start

Basic PDF Generation

import { generatePdf } from 'safeer-pdf-generator';

const result = await generatePdf({
  title: 'Sales Report',
  data: [
    { name: 'John Doe', sales: 1200, region: 'North' },
    { name: 'Jane Smith', sales: 1500, region: 'South' },
  ],
  columns: [
    { key: 'name', title: 'Name', dataIndex: 'name' },
    { key: 'sales', title: 'Sales', dataIndex: 'sales', format: 'currency' },
    { key: 'region', title: 'Region', dataIndex: 'region' },
  ],
});

console.log('PDF generated!', result.buffer);

Complete Example with S3 & Email

import { generatePdf, consoleLogger } from 'safeer-pdf-generator';

const result = await generatePdf({
  title: 'Monthly Report',
  data: salesData,
  columns: [
    { key: 'name', title: 'Sales Rep', dataIndex: 'name' },
    { key: 'sales', title: 'Sales', dataIndex: 'sales', format: 'currency' },
    { key: 'commission', title: 'Commission', dataIndex: 'commission', format: 'percentage' },
  ],
  // S3 Upload
  s3: {
    bucket: process.env.S3_BUCKET_NAME || 'your-default-bucket',
    region: process.env.AWS_REGION || 'us-east-1',
    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
  },
  // Email Delivery
  email: {
    to: '[email protected]',
    attachmentMode: 'link', // or 'attachment'
    smtp: {
      host: process.env.SMTP_HOST || 'smtp.example.com',
      port: process.env.SMTP_PORT ? Number(process.env.SMTP_PORT) : 587,
      secure: process.env.SMTP_SECURE === 'true',
      auth: {
        user: process.env.SMTP_USER,
        pass: process.env.SMTP_PASS,
      },
    },
  },
  logging: consoleLogger,
});

console.log(`PDF generated: ${result.s3?.url}`);
console.log(`Processing time: ${result.durationMs}ms`);

🏗️ Framework Examples

Express.js

import express from 'express';
import { generatePdf } from 'safeer-pdf-generator';

const app = express();

app.post('/generate-report', async (req, res) => {
  try {
    const result = await generatePdf({
      title: 'User Report',
      data: req.body.data,
      columns: req.body.columns,
    });
    
    res.setHeader('Content-Type', 'application/pdf');
    res.setHeader('Content-Disposition', 'attachment; filename="report.pdf"');
    res.send(result.buffer);
  } catch (error) {
    res.status(500).json({ error: 'PDF generation failed' });
  }
});

NestJS

import { Injectable } from '@nestjs/common';
import { generatePdf } from 'safeer-pdf-generator';

@Injectable()
export class PdfService {
  async createReport(data: any[]) {
    return await generatePdf({
      title: 'Report',
      data,
      columns: [
        { key: 'id', title: 'ID', dataIndex: 'id' },
        { key: 'name', title: 'Name', dataIndex: 'name' },
      ],
    });
  }
}

Next.js API Route

// pages/api/generate-pdf.ts
import { NextApiRequest, NextApiResponse } from 'next';
import { generatePdf } from 'safeer-pdf-generator';

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  if (req.method !== 'POST') {
    return res.status(405).json({ message: 'Method not allowed' });
  }

  try {
    const result = await generatePdf({
      title: 'Report',
      data: req.body.data,
      columns: req.body.columns,
    });

    res.setHeader('Content-Type', 'application/pdf');
    res.send(result.buffer);
  } catch (error) {
    res.status(500).json({ error: 'Failed to generate PDF' });
  }
}

📊 Advanced Features

Large Dataset Handling

import { generatePdf } from 'safeer-pdf-generator';

// Handle 100k+ records efficiently
const result = await generatePdf({
  title: 'Large Report',
  data: largeDataset, // 100,000+ records
  columns: columns,
  chunkSize: 1000, // Process in chunks
  performance: {
    concurrent: true,
    maxConcurrency: 4,
  },
});

PDF Merging

import { mergePdfs } from 'safeer-pdf-generator';

const mergedPdf = await mergePdfs({
  files: ['report1.pdf', 'report2.pdf', 'report3.pdf'],
  // or use buffers
  buffers: [buffer1, buffer2, buffer3],
});

Custom Styling

const result = await generatePdf({
  title: 'Styled Report',
  data: data,
  columns: columns,
  styling: {
    headerBackground: '#2563eb',
    headerTextColor: '#ffffff',
    alternateRowBackground: '#f8fafc',
    fontSize: 12,
    fontFamily: 'Inter',
  },
});

📧 Email Templates

The library includes smart email templates with automatic configuration:

// Automatic SMTP detection and validation
const result = await generatePdf({
  // ... pdf config
  email: {
    to: '[email protected]',
    subject: 'Your Report is Ready',
    attachmentMode: 'link', // Smart S3 link or attachment
    // SMTP auto-configured from common providers
  },
});

🔧 Configuration Options

Column Configuration

const columns = [
  {
    key: 'name',
    title: 'Name',
    dataIndex: 'name',
    width: 200,
    align: 'left'
  },
  {
    key: 'amount',
    title: 'Amount',
    dataIndex: 'amount',
    format: 'currency', // Built-in formatters
    align: 'right'
  },
  {
    key: 'date',
    title: 'Date',
    dataIndex: 'date',
    format: 'date',
    dateFormat: 'MM/DD/YYYY'
  }
];

Performance Options

const result = await generatePdf({
  // ... other config
  performance: {
    concurrent: true,
    maxConcurrency: 4,
    chunkSize: 1000,
    memoryLimit: '512MB',
  },
});

🌟 Why Choose safeer-pdf-generator?

• Production Ready: Used in enterprise applications
• Memory Efficient: Handles massive datasets without memory issues
• Developer Friendly: Excellent TypeScript support and documentation
• Framework Agnostic: Works with any Node.js framework
• Full Featured: Everything you need for PDF generation in one package
• Active Maintenance: Regular updates and community support

�� Documentation

• API Reference
• Examples
• Migration Guide

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

📄 License

MIT © Safeersoft

🔗 Links

• NPM Package
• GitHub Repository
• Issues & Support
• Changelog