pdf-oxide 0.3.24

package/src/managers/optimization-manager.ts

@@ -0,0 +1,262 @@
+/**
+ * OptimizationManager - PDF Optimization Operations
+ *
+ * Provides document optimization capabilities including:
+ * - Font subsetting
+ * - Image downsampling
+ * - Object deduplication
+ * - Full optimization pipeline
+ *
+ * @since 1.0.0
+ */
+
+import { EventEmitter } from 'events';
+import { mapFfiErrorCode, OptimizationException } from '../errors';
+
+// =============================================================================
+// Type Definitions
+// =============================================================================
+
+/**
+ * Result of an optimization operation.
+ */
+export interface OptimizationResult {
+  /** Whether the optimization succeeded */
+  readonly success: boolean;
+  /** Number of bytes saved */
+  readonly bytesSaved: number;
+  /** Original document size in bytes */
+  readonly originalSize: number;
+  /** Optimized document size in bytes */
+  readonly optimizedSize: number;
+  /** Compression ratio (0.0 - 1.0) */
+  readonly compressionRatio: number;
+}
+
+// =============================================================================
+// OptimizationManager
+// =============================================================================
+
+/**
+ * Manager for PDF optimization operations.
+ *
+ * Provides methods for reducing PDF file size through font subsetting,
+ * image downsampling, object deduplication, and combined optimization.
+ *
+ * @example
+ * ```typescript
+ * const optimizer = new OptimizationManager(document);
+ *
+ * // Subset fonts to remove unused glyphs
+ * const fontResult = await optimizer.subsetFonts();
+ * console.log(`Font subsetting saved ${fontResult.bytesSaved} bytes`);
+ *
+ * // Downsample high-resolution images
+ * const imageResult = await optimizer.downsampleImages(150, 80);
+ *
+ * // Full optimization pipeline
+ * const fullResult = await optimizer.optimizeFull(150, 80);
+ * console.log(`Total savings: ${fullResult.bytesSaved} bytes`);
+ * ```
+ */
+export class OptimizationManager extends EventEmitter {
+  private document: any;
+  private native: any;
+
+  constructor(document: any) {
+    super();
+    if (!document) {
+      throw new Error('Document cannot be null or undefined');
+    }
+    this.document = document;
+    try {
+      this.native = require('../../index.node');
+    } catch {
+      this.native = null;
+    }
+  }
+
+  // ===========================================================================
+  // Optimization Operations
+  // ===========================================================================
+
+  /**
+   * Subsets all embedded fonts in the document.
+   *
+   * Removes unused glyphs from embedded fonts, reducing file size
+   * while preserving visual fidelity for the characters actually used.
+   *
+   * @returns Optimization result with bytes saved
+   * @throws OptimizationException if the operation fails
+   */
+  async subsetFonts(): Promise<OptimizationResult> {
+    if (!this.native?.pdf_optimize_subset_fonts) {
+      throw new OptimizationException('Native optimization not available: pdf_optimize_subset_fonts not found');
+    }
+
+    const errorCode = Buffer.alloc(4);
+    const resultPtr = this.native.pdf_optimize_subset_fonts(
+      this.document._handle ?? this.document,
+      errorCode,
+    );
+    const code = errorCode.readInt32LE(0);
+
+    if (code !== 0) {
+      throw mapFfiErrorCode(code, 'Failed to subset fonts');
+    }
+
+    const result = this.parseOptimizationResult(resultPtr);
+    this.emit('fonts-subsetted', { bytesSaved: result.bytesSaved });
+
+    this.freeOptimizationResult(resultPtr);
+    return result;
+  }
+
+  /**
+   * Downsamples images in the document to reduce file size.
+   *
+   * @param dpi - Target resolution in dots per inch (default: 150)
+   * @param quality - JPEG quality for recompression (1-100, default: 80)
+   * @returns Optimization result with bytes saved
+   * @throws OptimizationException if the operation fails
+   */
+  async downsampleImages(dpi?: number, quality?: number): Promise<OptimizationResult> {
+    if (!this.native?.pdf_optimize_downsample_images) {
+      throw new OptimizationException('Native optimization not available: pdf_optimize_downsample_images not found');
+    }
+
+    const errorCode = Buffer.alloc(4);
+    const resultPtr = this.native.pdf_optimize_downsample_images(
+      this.document._handle ?? this.document,
+      dpi ?? 150,
+      quality ?? 80,
+      errorCode,
+    );
+    const code = errorCode.readInt32LE(0);
+
+    if (code !== 0) {
+      throw mapFfiErrorCode(code, 'Failed to downsample images');
+    }
+
+    const result = this.parseOptimizationResult(resultPtr);
+    this.emit('images-downsampled', { dpi: dpi ?? 150, quality: quality ?? 80, bytesSaved: result.bytesSaved });
+
+    this.freeOptimizationResult(resultPtr);
+    return result;
+  }
+
+  /**
+   * Deduplicates identical objects in the document.
+   *
+   * Identifies and merges duplicate fonts, images, and other resources
+   * that appear multiple times in the document.
+   *
+   * @returns Optimization result with bytes saved
+   * @throws OptimizationException if the operation fails
+   */
+  async deduplicate(): Promise<OptimizationResult> {
+    if (!this.native?.pdf_optimize_deduplicate) {
+      throw new OptimizationException('Native optimization not available: pdf_optimize_deduplicate not found');
+    }
+
+    const errorCode = Buffer.alloc(4);
+    const resultPtr = this.native.pdf_optimize_deduplicate(
+      this.document._handle ?? this.document,
+      errorCode,
+    );
+    const code = errorCode.readInt32LE(0);
+
+    if (code !== 0) {
+      throw mapFfiErrorCode(code, 'Failed to deduplicate objects');
+    }
+
+    const result = this.parseOptimizationResult(resultPtr);
+    this.emit('deduplicated', { bytesSaved: result.bytesSaved });
+
+    this.freeOptimizationResult(resultPtr);
+    return result;
+  }
+
+  /**
+   * Runs the full optimization pipeline.
+   *
+   * Combines font subsetting, image downsampling, and object deduplication
+   * into a single operation for maximum file size reduction.
+   *
+   * @param dpi - Target image resolution in dots per inch (default: 150)
+   * @param quality - JPEG quality for recompression (1-100, default: 80)
+   * @returns Optimization result with total bytes saved
+   * @throws OptimizationException if the operation fails
+   */
+  async optimizeFull(dpi?: number, quality?: number): Promise<OptimizationResult> {
+    if (!this.native?.pdf_optimize_full) {
+      throw new OptimizationException('Native optimization not available: pdf_optimize_full not found');
+    }
+
+    const errorCode = Buffer.alloc(4);
+    const resultPtr = this.native.pdf_optimize_full(
+      this.document._handle ?? this.document,
+      dpi ?? 150,
+      quality ?? 80,
+      errorCode,
+    );
+    const code = errorCode.readInt32LE(0);
+
+    if (code !== 0) {
+      throw mapFfiErrorCode(code, 'Failed to run full optimization');
+    }
+
+    const result = this.parseOptimizationResult(resultPtr);
+    this.emit('optimized-full', { dpi: dpi ?? 150, quality: quality ?? 80, bytesSaved: result.bytesSaved });
+
+    this.freeOptimizationResult(resultPtr);
+    return result;
+  }
+
+  // ===========================================================================
+  // Private Helpers
+  // ===========================================================================
+
+  private parseOptimizationResult(resultPtr: any): OptimizationResult {
+    if (!resultPtr) {
+      return { success: true, bytesSaved: 0, originalSize: 0, optimizedSize: 0, compressionRatio: 0 };
+    }
+
+    if (typeof resultPtr === 'string') {
+      try {
+        return JSON.parse(resultPtr);
+      } catch {
+        return { success: true, bytesSaved: 0, originalSize: 0, optimizedSize: 0, compressionRatio: 0 };
+      }
+    }
+
+    // Handle native result handle
+    const bytesSaved = this.native?.pdf_optimization_result_bytes_saved?.(resultPtr) ?? 0;
+    return {
+      success: true,
+      bytesSaved,
+      originalSize: 0,
+      optimizedSize: 0,
+      compressionRatio: 0,
+    };
+  }
+
+  private freeOptimizationResult(resultPtr: any): void {
+    if (resultPtr && typeof resultPtr !== 'string' && this.native?.pdf_optimization_result_free) {
+      this.native.pdf_optimization_result_free(resultPtr);
+    }
+  }
+
+  // ===========================================================================
+  // Cleanup
+  // ===========================================================================
+
+  /**
+   * Releases resources held by this manager.
+   */
+  destroy(): void {
+    this.removeAllListeners();
+  }
+}
+
+export default OptimizationManager;

package/src/managers/outline-manager.ts

@@ -0,0 +1,196 @@
+/**
+ * Manager for PDF document outlines (bookmarks)
+ *
+ * Provides functionality for reading and navigating the document's outline tree,
+ * which represents the hierarchical bookmark structure.
+ *
+ * @example
+ * ```typescript
+ * import { OutlineManager } from 'pdf_oxide';
+ *
+ * const doc = PdfDocument.open('document.pdf');
+ * const outlineManager = new OutlineManager(doc);
+ *
+ * if (outlineManager.hasOutlines()) {
+ *   const outlines = outlineManager.getOutlines();
+ *   console.log(`Found ${outlines.length} outline items`);
+ * }
+ * ```
+ */
+
+export interface OutlineItem {
+  title: string;
+  pageIndex: number;
+  pageNumber: number | null;
+  level: number;
+}
+
+export class OutlineManager {
+  private _document: any;
+
+  /**
+   * Creates a new OutlineManager for the given document
+   * @param document - The PDF document
+   * @throws Error if document is null or undefined
+   */
+  constructor(document: any) {
+    if (!document) {
+      throw new Error('Document is required');
+    }
+    this._document = document;
+  }
+
+  /**
+   * Checks if the document has an outline (bookmarks)
+   * @returns True if the document has outlines
+   */
+  hasOutlines(): boolean {
+    try {
+      return this._document.hasOutlines();
+    } catch (error) {
+      return false;
+    }
+  }
+
+  /**
+   * Gets the number of top-level outline items
+   * @returns Number of outline items
+   */
+  getOutlineCount(): number {
+    try {
+      return this._document.getOutlineCount();
+    } catch (error) {
+      return 0;
+    }
+  }
+
+  /**
+   * Gets all outline items (flattened)
+   * @returns Array of outline items
+   *
+   * @example
+   * ```typescript
+   * const outlines = manager.getOutlines();
+   * outlines.forEach(item => {
+   *   console.log(`${item.title} -> Page ${item.pageNumber}`);
+   * });
+   * ```
+   */
+  getOutlines(): OutlineItem[] {
+    try {
+      const rawOutlines = this._document.getOutlines();
+      // Convert native OutlineInfo to OutlineItem format expected by JS
+      return rawOutlines.map((item: any) => ({
+        title: item.title,
+        pageIndex: item.pageIndex,
+        pageNumber: item.pageIndex >= 0 ? item.pageIndex + 1 : null,
+        level: item.level,
+      }));
+    } catch (error) {
+      return [];
+    }
+  }
+
+  /**
+   * Finds an outline item by title (case-insensitive substring match)
+   * @param titleFragment - Partial title to search for
+   * @returns Matching outline item or null
+   *
+   * @example
+   * ```typescript
+   * const item = manager.findByTitle('Introduction');
+   * if (item) {
+   *   console.log(`Found: ${item.title} on page ${item.pageNumber}`);
+   * }
+   * ```
+   */
+  findByTitle(titleFragment: string): OutlineItem | null {
+    if (!titleFragment || typeof titleFragment !== 'string') {
+      throw new Error('Title fragment must be a non-empty string');
+    }
+
+    const outlines = this.getOutlines();
+    const fragment = titleFragment.toLowerCase();
+
+    for (const item of outlines) {
+      if (item.title && item.title.toLowerCase().includes(fragment)) {
+        return item;
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Finds all outline items by title (case-insensitive substring match)
+   * @param titleFragment - Partial title to search for
+   * @returns Array of matching outline items
+   */
+  findAllByTitle(titleFragment: string): OutlineItem[] {
+    if (!titleFragment || typeof titleFragment !== 'string') {
+      throw new Error('Title fragment must be a non-empty string');
+    }
+
+    const outlines = this.getOutlines();
+    const fragment = titleFragment.toLowerCase();
+
+    return outlines.filter((item) =>
+      item.title && item.title.toLowerCase().includes(fragment)
+    );
+  }
+
+  /**
+   * Gets outline items for a specific page
+   * @param pageIndex - Zero-based page index
+   * @returns Outline items on that page
+   */
+  getOutlinesForPage(pageIndex: number): OutlineItem[] {
+    if (typeof pageIndex !== 'number' || pageIndex < 0) {
+      throw new Error('Page index must be a non-negative number');
+    }
+
+    const outlines = this.getOutlines();
+    return outlines.filter((item) => item.pageIndex === pageIndex);
+  }
+
+  /**
+   * Checks if a specific page has outline items
+   * @param pageIndex - Zero-based page index
+   * @returns True if page has outline items
+   */
+  pageHasOutlines(pageIndex: number): boolean {
+    if (typeof pageIndex !== 'number' || pageIndex < 0) {
+      throw new Error('Page index must be a non-negative number');
+    }
+
+    return this.getOutlinesForPage(pageIndex).length > 0;
+  }
+
+  /**
+   * Gets an outline item by index
+   * @param index - Item index
+   * @returns Outline item or null if not found
+   */
+  getOutlineAt(index: number): OutlineItem | null {
+    if (typeof index !== 'number' || index < 0) {
+      throw new Error('Index must be a non-negative number');
+    }
+
+    const outlines = this.getOutlines();
+    return outlines[index] || null;
+  }
+
+  /**
+   * Checks if a page number exists in the outline
+   * @param pageNumber - One-based page number
+   * @returns True if page appears in outline
+   */
+  containsPageNumber(pageNumber: number): boolean {
+    if (typeof pageNumber !== 'number' || pageNumber < 1) {
+      throw new Error('Page number must be a positive number');
+    }
+
+    const outlines = this.getOutlines();
+    return outlines.some((item) => item.pageNumber === pageNumber);
+  }
+}