safeer-pdf-generator/examples/basic-script/README.md

Framework-agnostic PDF generation library with chunking, merging, S3 upload, and email delivery

# Basic PDF Generation Script

This example demonstrates comprehensive PDF generation capabilities using `pdf-reporter` in a simple Node.js script.

## Features Demonstrated

- 📄 **Basic PDF Generation** - Simple table-based reports
- 🎨 **Advanced Custom Templates** - Professional styling with gradients and charts
- ⚡ **Large Dataset Processing** - Optimized chunking for 1000+ records
- 🔍 **PDF Analysis & Manipulation** - Extract pages, analyze properties
- 🔗 **Department Reports & Merging** - Generate and combine multiple PDFs
- ✂️ **PDF Splitting** - Break PDFs into individual pages
- 🛡️ **Error Handling** - Robust error management and recovery

## Quick Start

### Installation

```bash
cd examples/basic-script
npm install
```

### Run the Example

```bash
npm start
```

## What It Does

The script runs 7 comprehensive examples showcasing different aspects of PDF generation:

### 1. Basic PDF Generation
- Creates a simple employee report with standard table layout
- Demonstrates basic data validation and PDF generation
- Output: `employee-report-basic.pdf`

### 2. Advanced Custom Template
- Uses a custom template with modern design elements
- Includes gradients, animations, status badges, and metrics
- Shows company branding integration
- Output: `employee-report-advanced.pdf`

### 3. Large Dataset Processing
- Processes 1000 employee records using optimized chunking
- Demonstrates performance estimation and monitoring
- Shows automatic chunk size and concurrency optimization
- Output: `employee-report-large.pdf` (140+ pages)

### 4. PDF Analysis & Manipulation
- Analyzes existing PDFs for metadata and properties
- Validates PDF integrity
- Extracts specific pages from large documents
- Output: `employee-report-extract.pdf`

### 5. Department Reports & Merging
- Generates separate reports for different departments
- Merges multiple PDFs into a single comprehensive document
- Shows how to handle multi-department reporting
- Output: `employee-report-merged-departments.pdf`

### 6. PDF Splitting
- Demonstrates splitting a PDF into individual page files
- Useful for creating page-by-page archives
- Output: `split-pages/` directory with individual pages

### 7. Error Handling
- Shows proper error handling for invalid inputs
- Demonstrates recovery from common PDF generation errors
- Includes validation error examples

## Sample Data

The script generates realistic sample data including:

```javascript
{
  id: 1,
  name: "John Doe",
  email: "john.doe@company.com", 
  department: "Engineering",
  position: "Senior Developer",
  salary: 95000,
  skills: ["JavaScript", "Python", "React"],
  performance: 4.5,
  location: "New York"
}
```

## Custom Template Features

The advanced template includes:

- 🎨 **Modern Design** - Gradient backgrounds and professional styling
- 📊 **Automatic Metrics** - Calculated totals, averages, and statistics
- 🏷️ **Status Badges** - Color-coded status indicators
- 📈 **Charts Integration** - Ready for chart.js integration
- 📱 **Responsive Layout** - Optimized for different page sizes
- 🏢 **Company Branding** - Support for logos and custom styling

## Performance Features

- **Smart Chunking**: Automatically divides large datasets
- **Concurrent Processing**: Parallel PDF generation for speed
- **Memory Optimization**: Efficient memory usage for large documents
- **Progress Monitoring**: Real-time progress tracking
- **Performance Estimation**: Predicts processing time and resource usage

## Output Files

After running the script, you'll find these files in the `output/` directory:

| File | Description | Features |
|------|-------------|----------|
| `employee-report-basic.pdf` | Basic table report | Simple layout, 1 page |
| `employee-report-advanced.pdf` | Styled professional report | Modern design, 4 pages |
| `employee-report-large.pdf` | Large dataset report | 1000 records, 140+ pages |
| `employee-report-extract.pdf` | Extracted pages | First 5 pages only |
| `employee-report-merged-departments.pdf` | Merged departments | Combined reports, 70+ pages |
| `split-pages/` | Individual page files | Separate PDF per page |

## Code Structure

```javascript
// Import the library
const {
  generatePdf,
  generateOptimizedPdf,
  estimatePdfGeneration,
  // ... other imports
} = require('pdf-reporter');

// Generate sample data
const sampleData = generateSampleData(count);

// Register custom templates
registerTemplate('advanced-employee-report', params => {
  // Custom template implementation
});

// Generate PDFs with different options
const result = await generatePdf({
  title: 'My Report',
  data: sampleData,
  columns: columnDefinitions,
  options: {
    template: 'advanced-employee-report',
    format: 'A4',
    orientation: 'portrait'
  }
});
```

## Customization

### Adding Your Own Data

Replace the sample data generation with your actual data:

```javascript
const yourData = [
  { id: 1, name: 'Your Data', /* ... */ },
  // ... more records
];

const result = await generatePdf({
  title: 'Your Report Title',
  data: yourData,
  columns: yourColumnDefinitions,
  // ... other options
});
```

### Creating Custom Templates

Define your own template function:

```javascript
registerTemplate('my-custom-template', (params) => {
  const { title, data, columns } = params;
  
  return {
    html: `
      <!DOCTYPE html>
      <html>
        <head>
          <title>${title}</title>
          <style>
            /* Your custom CSS */
          </style>
        </head>
        <body>
          <!-- Your custom HTML -->
        </body>
      </html>
    `,
    header: '<div>Custom Header</div>',
    footer: '<div>Custom Footer</div>'
  };
});
```

### Adjusting Performance Settings

Customize chunking and concurrency:

```javascript
const options = {
  chunking: {
    enabled: true,
    chunkSize: 200,        // Records per chunk
    maxConcurrency: 4      // Parallel processes
  }
};
```

## Error Handling

The script demonstrates proper error handling:

```javascript
try {
  const result = await generatePdf(options);
  console.log('✅ PDF generated successfully');
} catch (error) {
  if (error.name === 'ValidationError') {
    console.log('❌ Invalid input:', error.message);
  } else if (error.name === 'PdfGenerationError') {
    console.log('❌ PDF generation failed:', error.message);
  } else {
    console.log('❌ Unexpected error:', error.message);
  }
}
```

## Integration Examples

### Use in Your Application

```javascript
const { generatePdf } = require('pdf-reporter');

async function createMonthlyReport(employeeData) {
  try {
    const result = await generatePdf({
      title: 'Monthly Employee Report',
      data: employeeData,
      columns: [
        { key: 'name', title: 'Employee Name', dataIndex: 'name', flex: 3 },
        { key: 'dept', title: 'Department', dataIndex: 'department', flex: 2 },
        { key: 'performance', title: 'Performance', dataIndex: 'performance', flex: 1 }
      ],
      userInfo: {
        companyName: 'Your Company',
        name: 'Report Generator'
      }
    });
    
    return result.buffer;
  } catch (error) {
    console.error('Report generation failed:', error);
    throw error;
  }
}
```

### Save to File System

```javascript
const fs = require('fs').promises;

const pdfBuffer = await generatePdf(options);
await fs.writeFile('my-report.pdf', pdfBuffer);
console.log('Report saved to my-report.pdf');
```

### Stream to HTTP Response

```javascript
app.get('/report', async (req, res) => {
  try {
    const result = await generatePdf(options);
    
    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: error.message });
  }
});
```

## Performance Tips

1. **Use Chunking for Large Datasets**: Enable chunking for 1000+ records
2. **Monitor Memory Usage**: Watch memory consumption during generation
3. **Optimize Concurrency**: Adjust `maxConcurrency` based on CPU cores
4. **Validate Inputs**: Always validate data before processing
5. **Handle Errors Gracefully**: Implement comprehensive error handling
6. **Cache Templates**: Reuse templates for better performance

## Troubleshooting

### Common Issues

**PDF Generation Fails**
- Check that all required fields are provided
- Validate data structure matches column definitions
- Ensure sufficient memory for large datasets

**Performance Issues**
- Reduce chunk size for memory-constrained environments
- Lower concurrency for CPU-limited systems
- Use estimation to predict resource requirements

**Template Errors**
- Verify HTML structure is valid
- Check CSS syntax in template styles
- Ensure all template parameters are used correctly

### Debug Mode

Enable debug logging to troubleshoot issues:

```javascript
const { consoleLogger } = require('pdf-reporter');

const result = await generatePdf({
  // ... your options
  logger: consoleLogger // Enables detailed logging
});
```

## Contributing

1. Fork the repository
2. Create your feature branch
3. Make your changes to this example
4. Test thoroughly
5. Submit a pull request

## License

MIT License - see the [LICENSE](../../LICENSE) file for details.

## Support

- 📚 [Documentation](https://github.com/Safeersoft/pdf-reporter)
- 🐛 [Issue Tracker](https://github.com/Safeersoft/pdf-reporter/issues)
- 📧 [Email Support](mailto:support@safeersoft.com)