pdf-oxide 0.3.24 → 0.3.29

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

@@ -0,0 +1,103 @@
+/**
+ * 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';
+/**
+ * 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;
+}
+/**
+ * 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 declare class OptimizationManager extends EventEmitter {
+    private document;
+    private native;
+    constructor(document: any);
+    /**
+     * 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
+     */
+    subsetFonts(): Promise<OptimizationResult>;
+    /**
+     * 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
+     */
+    downsampleImages(dpi?: number, quality?: number): Promise<OptimizationResult>;
+    /**
+     * 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
+     */
+    deduplicate(): Promise<OptimizationResult>;
+    /**
+     * 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
+     */
+    optimizeFull(dpi?: number, quality?: number): Promise<OptimizationResult>;
+    private parseOptimizationResult;
+    private freeOptimizationResult;
+    /**
+     * Releases resources held by this manager.
+     */
+    destroy(): void;
+}
+export default OptimizationManager;
+//# sourceMappingURL=optimization-manager.d.ts.map

package/lib/managers/optimization-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"optimization-manager.d.ts","sourceRoot":"","sources":["../../src/managers/optimization-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAOtC;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,yCAAyC;IACzC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,4BAA4B;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,sCAAsC;IACtC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,uCAAuC;IACvC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,oCAAoC;IACpC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;CACnC;AAMD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,mBAAoB,SAAQ,YAAY;IACnD,OAAO,CAAC,QAAQ,CAAM;IACtB,OAAO,CAAC,MAAM,CAAM;gBAER,QAAQ,EAAE,GAAG;IAiBzB;;;;;;;;OAQG;IACG,WAAW,IAAI,OAAO,CAAC,kBAAkB,CAAC;IAuBhD;;;;;;;OAOG;IACG,gBAAgB,CAAC,GAAG,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAyBnF;;;;;;;;OAQG;IACG,WAAW,IAAI,OAAO,CAAC,kBAAkB,CAAC;IAuBhD;;;;;;;;;;OAUG;IACG,YAAY,CAAC,GAAG,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;IA6B/E,OAAO,CAAC,uBAAuB;IAwB/B,OAAO,CAAC,sBAAsB;IAU9B;;OAEG;IACH,OAAO,IAAI,IAAI;CAGhB;AAED,eAAe,mBAAmB,CAAC"}

package/lib/managers/optimization-manager.js

@@ -0,0 +1,194 @@
+/**
+ * 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;
+//# sourceMappingURL=optimization-manager.js.map

package/lib/managers/optimization-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"optimization-manager.js","sourceRoot":"","sources":["../../src/managers/optimization-manager.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,102 @@
+/**
+ * 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;
+}
+//# sourceMappingURL=outline-manager.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"outline-manager.d.ts","sourceRoot":"","sources":["../../src/managers/outline-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,KAAK,EAAE,MAAM,CAAC;CACf;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,SAAS,CAAM;IAEvB;;;;OAIG;gBACS,QAAQ,EAAE,GAAG;IAOzB;;;OAGG;IACH,WAAW,IAAI,OAAO;IAQtB;;;OAGG;IACH,eAAe,IAAI,MAAM;IAQzB;;;;;;;;;;;OAWG;IACH,WAAW,IAAI,WAAW,EAAE;IAe5B;;;;;;;;;;;;OAYG;IACH,WAAW,CAAC,aAAa,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI;IAiBtD;;;;OAIG;IACH,cAAc,CAAC,aAAa,EAAE,MAAM,GAAG,WAAW,EAAE;IAapD;;;;OAIG;IACH,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,WAAW,EAAE;IASpD;;;;OAIG;IACH,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAQ3C;;;;OAIG;IACH,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI;IAS/C;;;;OAIG;IACH,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;CAQhD"}

package/lib/managers/outline-manager.js

@@ -0,0 +1,170 @@
+/**
+ * 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);
+    }
+}
+//# sourceMappingURL=outline-manager.js.map

package/lib/managers/outline-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outline-manager.js","sourceRoot":"","sources":["../../src/managers/outline-manager.ts"],"names":[],"mappings":"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"}