pdf-oxide-fips 0.3.47

package/lib/managers/optimization-manager.js

@@ -0,0 +1,213 @@
+/**
+ * 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.js';
+// =============================================================================
+// 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 {
+    constructor(document) {
+        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() {
+        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, quality) {
+        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() {
+        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, quality) {
+        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
+    // ===========================================================================
+    parseOptimizationResult(resultPtr) {
+        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,
+        };
+    }
+    freeOptimizationResult(resultPtr) {
+        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() {
+        this.removeAllListeners();
+    }
+}
+export default OptimizationManager;

package/lib/managers/outline-manager.d.ts

@@ -0,0 +1,101 @@
+/**
+ * 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 declare class OutlineManager {
+    private _document;
+    /**
+     * Creates a new OutlineManager for the given document
+     * @param document - The PDF document
+     * @throws Error if document is null or undefined
+     */
+    constructor(document: any);
+    /**
+     * Checks if the document has an outline (bookmarks)
+     * @returns True if the document has outlines
+     */
+    hasOutlines(): boolean;
+    /**
+     * Gets the number of top-level outline items
+     * @returns Number of outline items
+     */
+    getOutlineCount(): number;
+    /**
+     * 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[];
+    /**
+     * 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;
+    /**
+     * 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[];
+    /**
+     * Gets outline items for a specific page
+     * @param pageIndex - Zero-based page index
+     * @returns Outline items on that page
+     */
+    getOutlinesForPage(pageIndex: number): OutlineItem[];
+    /**
+     * 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;
+    /**
+     * Gets an outline item by index
+     * @param index - Item index
+     * @returns Outline item or null if not found
+     */
+    getOutlineAt(index: number): OutlineItem | 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;
+}

package/lib/managers/outline-manager.js

@@ -0,0 +1,169 @@
+/**
+ * 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 class OutlineManager {
+    /**
+     * Creates a new OutlineManager for the given document
+     * @param document - The PDF document
+     * @throws Error if document is null or undefined
+     */
+    constructor(document) {
+        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() {
+        try {
+            return this._document.hasOutlines();
+        }
+        catch (error) {
+            return false;
+        }
+    }
+    /**
+     * Gets the number of top-level outline items
+     * @returns Number of outline items
+     */
+    getOutlineCount() {
+        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() {
+        try {
+            const rawOutlines = this._document.getOutlines();
+            // Convert native OutlineInfo to OutlineItem format expected by JS
+            return rawOutlines.map((item) => ({
+                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) {
+        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) {
+        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) {
+        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) {
+        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) {
+        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) {
+        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);
+    }
+}

package/lib/managers/page-manager.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Manager for PDF page-level operations
+ *
+ * Provides methods to query page count, dimensions, and validate indices.
+ *
+ * @example
+ * ```typescript
+ * import { PageManager } from 'pdf_oxide';
+ *
+ * const doc = PdfDocument.open('document.pdf');
+ * const pageManager = new PageManager(doc);
+ *
+ * console.log(`Document has ${pageManager.getPageCount()} pages`);
+ *
+ * if (pageManager.isValidPageIndex(5)) {
+ *   const info = pageManager.getPageInfo(5);
+ *   console.log(`Page 5: ${info.width} x ${info.height} points`);
+ * }
+ * ```
+ */
+export interface PageInfo {
+    index: number;
+    width: number;
+    height: number;
+}
+export interface PageRange {
+    firstPage: number;
+    lastPage: number;
+}
+export interface PageStatistics {
+    count: number;
+    minWidth: number;
+    maxWidth: number;
+    minHeight: number;
+    maxHeight: number;
+    averageWidth: number;
+    averageHeight: number;
+    hasVariableSizes: boolean;
+}
+export declare class PageManager {
+    private _document;
+    private _cache;
+    /**
+     * Creates a new PageManager for the given document
+     * @param document - The PDF document
+     * @throws Error if document is null or undefined
+     */
+    constructor(document: any);
+    /**
+     * Clears the page cache
+     */
+    clearCache(): void;
+    /**
+     * Gets the total number of pages in the document
+     * @returns Number of pages
+     */
+    getPageCount(): number;
+    /**
+     * Checks if a page index is valid for this document
+     * @param pageIndex - Page index to validate (0-based)
+     * @returns True if the page index is valid
+     */
+    isValidPageIndex(pageIndex: number): boolean;
+    /**
+     * Gets information about a specific page
+     * @param pageIndex - Page index (0-based)
+     * @returns PageInfo object with page dimensions
+     * @throws Error if page index is invalid
+     *
+     * @example
+     * ```typescript
+     * const info = manager.getPageInfo(0);
+     * console.log(`Page 0: ${info.width} x ${info.height} points`);
+     * ```
+     */
+    getPageInfo(pageIndex: number): PageInfo;
+    /**
+     * Gets information about all pages in the document
+     * @returns Array of PageInfo objects
+     *
+     * @example
+     * ```typescript
+     * const pages = manager.getAllPageInfo();
+     * pages.forEach(page => {
+     *   console.log(`Page ${page.index}: ${page.width} x ${page.height}`);
+     * });
+     * ```
+     */
+    getAllPageInfo(): PageInfo[];
+    /**
+     * Checks if the document has no pages
+     * @returns True if the document has no pages
+     */
+    isEmpty(): boolean;
+    /**
+     * Checks if the document has more than one page
+     * @returns True if document has multiple pages
+     */
+    hasMultiplePages(): boolean;
+    /**
+     * Gets the valid page range
+     * @returns Object with firstPage and lastPage indices
+     *
+     * @example
+     * ```typescript
+     * const range = manager.getPageRange();
+     * console.log(`Page range: ${range.firstPage} to ${range.lastPage}`);
+     * ```
+     */
+    getPageRange(): PageRange;
+    /**
+     * Gets page dimension statistics
+     * @returns Statistics about page dimensions
+     *
+     * @example
+     * ```typescript
+     * const stats = manager.getPageStatistics();
+     * console.log(`Average width: ${stats.averageWidth}`);
+     * console.log(`Pages vary in size: ${stats.hasVariableSizes}`);
+     * ```
+     */
+    getPageStatistics(): PageStatistics;
+    /**
+     * Gets pages within a specific size range
+     * @param minWidth - Minimum width
+     * @param maxWidth - Maximum width
+     * @param minHeight - Minimum height
+     * @param maxHeight - Maximum height
+     * @returns Matching PageInfo objects
+     */
+    getPagesInSizeRange(minWidth: number, maxWidth: number, minHeight: number, maxHeight: number): PageInfo[];
+    /**
+     * Gets landscape pages
+     * @returns Array of landscape PageInfo objects
+     */
+    getLandscapePages(): PageInfo[];
+    /**
+     * Gets portrait pages
+     * @returns Array of portrait PageInfo objects
+     */
+    getPortraitPages(): PageInfo[];
+}