Document Management

/**
 * Creates a new PDF document
 * @param options - Document configuration options
 */
constructor(options?: PDFDocumentOptions);

interface PDFDocumentOptions {
  /** PDF version to generate */
  pdfVersion?: '1.3' | '1.4' | '1.5' | '1.6' | '1.7' | '1.7ext3';
  /** Enable stream compression (default: true) */
  compress?: boolean;
  /** Automatically add first page (default: true) */
  autoFirstPage?: boolean;
  /** Page size as string or [width, height] in points */
  size?: PageSize | [number, number];
  /** Page orientation */
  layout?: 'portrait' | 'landscape';
  /** Page margins */
  margins?: MarginDefinition;
  /** Buffer pages for manipulation */
  bufferPages?: boolean;
  /** Document metadata */
  info?: DocumentInfo;
  /** Display document title in viewer */
  displayTitle?: boolean;
  /** Document language */
  lang?: string;
  /** PDF subset compliance */
  subset?: PDFSubset;
  /** Enable tagged PDF for accessibility */
  tagged?: boolean;
}

import PDFDocument from "pdfkit";

// Basic document
const doc = new PDFDocument();

// A4 document with custom margins
const doc2 = new PDFDocument({
  size: 'A4',
  margins: { top: 50, left: 50, right: 50, bottom: 50 },
  info: {
    Title: 'My Document',
    Author: 'John Doe'
  }
});

// Letter size landscape with compression disabled
const doc3 = new PDFDocument({
  size: 'LETTER',
  layout: 'landscape',
  compress: false
});

/**
 * Add a new page to the document
 * @param options - Page-specific options (overrides document defaults)
 * @returns Document instance for chaining
 */
addPage(options?: PageOptions): PDFDocument;

/**
 * Continue on a new page with same settings
 * @param options - Page-specific options
 * @returns Document instance for chaining
 */
continueOnNewPage(options?: PageOptions): PDFDocument;

/**
 * Switch to a specific buffered page (requires bufferPages: true)
 * @param n - Page number (0-indexed)
 * @returns Document instance for chaining
 */
switchToPage(n: number): PDFDocument;

/**
 * Flush buffered pages to output
 * @returns Document instance for chaining
 */
flushPages(): PDFDocument;

/**
 * Get current buffer range
 * @returns Buffer range information
 */
bufferedPageRange(): { start: number; count: number };

interface PageOptions {
  size?: PageSize | [number, number];
  layout?: 'portrait' | 'landscape';
  margins?: MarginDefinition;
}

// Add pages with different sizes
doc.addPage()  // Uses document defaults
   .addPage({ size: 'A3', layout: 'landscape' })
   .addPage({ size: [612, 792], margins: 20 });

// Working with buffered pages
const bufferedDoc = new PDFDocument({ bufferPages: true });
bufferedDoc.text('Page 1', 100, 100);
bufferedDoc.addPage();
bufferedDoc.text('Page 2', 100, 100);

// Switch back to first page and add more content
bufferedDoc.switchToPage(0);
bufferedDoc.text('Additional content on page 1', 100, 200);

// Flush all pages to output
bufferedDoc.flushPages();

/**
 * Finalize the PDF document and end the stream
 * @returns Document instance for chaining
 */
end(): PDFDocument;

/**
 * Get string representation
 * @returns String representation of document
 */
toString(): string;

import fs from 'fs';

// Output to file
const doc = new PDFDocument();
doc.pipe(fs.createWriteStream('output.pdf'));
doc.text('Hello World', 100, 100);
doc.end();

// Output to buffer
const chunks = [];
doc.on('data', chunk => chunks.push(chunk));
doc.on('end', () => {
  const pdfBuffer = Buffer.concat(chunks);
  console.log('PDF size:', pdfBuffer.length);
});
doc.text('Hello World', 100, 100);
doc.end();

/**
 * Create a new PDF reference object
 * @param data - Data for the reference
 * @returns PDF reference
 */
ref(data: any): PDFReference;

/**
 * Add content to the current page
 * @param data - Content data to add
 * @returns Document instance for chaining
 */
addContent(data: string): PDFDocument;

/**
 * Add a named destination for internal linking
 * @param name - Destination name
 * @param args - Destination arguments
 * @returns Document instance for chaining
 */
addNamedDestination(name: string, ...args: any[]): PDFDocument;

/**
 * Add a named embedded file
 * @param name - File name
 * @param ref - File reference
 * @returns Document instance for chaining
 */
addNamedEmbeddedFile(name: string, ref: PDFReference): PDFDocument;

/**
 * Add named JavaScript action
 * @param name - Action name
 * @param js - JavaScript code
 * @returns Document instance for chaining
 */
addNamedJavaScript(name: string, js: string): PDFDocument;

interface DocumentInfo {
  Title?: string;
  Author?: string;
  Subject?: string;
  Keywords?: string;
  Creator?: string;
  Producer?: string;
  CreationDate?: Date;
  ModDate?: Date;
}

type MarginDefinition = 
  | number 
  | [number, number] 
  | [number, number, number, number] 
  | { vertical: number; horizontal: number } 
  | { top: number; right: number; bottom: number; left: number };

type PDFSubset = 
  | 'PDF/A-1' | 'PDF/A-1a' | 'PDF/A-1b' 
  | 'PDF/A-2' | 'PDF/A-2a' | 'PDF/A-2b' 
  | 'PDF/A-3' | 'PDF/A-3a' | 'PDF/A-3b' 
  | 'PDF/UA';

type PageSize = 
  | 'A0' | 'A1' | 'A2' | 'A3' | 'A4' | 'A5' | 'A6' | 'A7' | 'A8' | 'A9' | 'A10'
  | 'B0' | 'B1' | 'B2' | 'B3' | 'B4' | 'B5' | 'B6' | 'B7' | 'B8' | 'B9' | 'B10'
  | 'C0' | 'C1' | 'C2' | 'C3' | 'C4' | 'C5' | 'C6' | 'C7' | 'C8' | 'C9' | 'C10'
  | 'RA0' | 'RA1' | 'RA2' | 'RA3' | 'RA4' 
  | 'SRA0' | 'SRA1' | 'SRA2' | 'SRA3' | 'SRA4'
  | 'EXECUTIVE' | 'FOLIO' | 'LEGAL' | 'LETTER' | 'TABLOID';