pdf-oxide-fips 0.3.47

package/lib/hybrid-ml-manager.js

@@ -0,0 +1,208 @@
+/**
+ * HybridMLManager for advanced PDF analysis using machine learning
+ *
+ * Analyzes PDF pages for complexity, content type, and optimal extraction strategies.
+ * API is consistent with Python, Java, C#, Go, and Swift implementations.
+ */
+import { EventEmitter } from 'events';
+/**
+ * Page complexity levels
+ */
+export var PageComplexity;
+(function (PageComplexity) {
+    PageComplexity["Simple"] = "simple";
+    PageComplexity["Moderate"] = "moderate";
+    PageComplexity["Complex"] = "complex";
+    PageComplexity["VeryComplex"] = "very_complex";
+})(PageComplexity || (PageComplexity = {}));
+/**
+ * Content type classifications
+ */
+export var ContentType;
+(function (ContentType) {
+    ContentType["TextOnly"] = "text_only";
+    ContentType["TextImages"] = "text_images";
+    ContentType["Tables"] = "tables";
+    ContentType["MixedLayout"] = "mixed_layout";
+    ContentType["Scanned"] = "scanned";
+    ContentType["Form"] = "form";
+    ContentType["VectorGraphics"] = "vector_graphics";
+})(ContentType || (ContentType = {}));
+/**
+ * Hybrid ML Manager for advanced PDF analysis
+ *
+ * Provides methods to:
+ * - Analyze page complexity
+ * - Detect content types
+ * - Recommend extraction strategies
+ * - Detect tables and columns
+ * - Estimate processing time
+ */
+export class HybridMLManager extends EventEmitter {
+    constructor(document) {
+        super();
+        this.resultCache = new Map();
+        this.maxCacheSize = 100;
+        this.document = document;
+    }
+    /**
+     * Analyzes a specific page
+     * Matches: Python analyzePage(), Java analyzePage(), C# AnalyzePage()
+     */
+    async analyzePage(pageIndex) {
+        const cacheKey = `ml:analysis:${pageIndex}`;
+        if (this.resultCache.has(cacheKey)) {
+            return this.resultCache.get(cacheKey);
+        }
+        // In real implementation, would call native FFI
+        const result = {
+            pageIndex,
+            complexity: PageComplexity.Moderate,
+            complexityScore: 0.5,
+            contentType: ContentType.TextImages,
+            textDensity: 0.7,
+            imageDensity: 0.3,
+            hasText: true,
+            hasImages: false,
+            hasTables: false,
+            estimatedProcessingTime: 100,
+        };
+        this.setCached(cacheKey, result);
+        return result;
+    }
+    /**
+     * Analyzes all pages in the document
+     * Matches: Python analyzeDocument(), Java analyzeDocument(), C# AnalyzeDocument()
+     */
+    async analyzeDocument() {
+        const cacheKey = 'ml:analysis:all';
+        if (this.resultCache.has(cacheKey)) {
+            return this.resultCache.get(cacheKey);
+        }
+        // In real implementation, would call native FFI
+        const results = [];
+        this.setCached(cacheKey, results);
+        return results;
+    }
+    /**
+     * Gets extraction strategy recommendation for a page
+     * Matches: Python getExtractionStrategy(), Java getExtractionStrategy(), C# GetExtractionStrategy()
+     */
+    async getExtractionStrategy(pageIndex) {
+        const cacheKey = `ml:strategy:${pageIndex}`;
+        if (this.resultCache.has(cacheKey)) {
+            return this.resultCache.get(cacheKey);
+        }
+        // In real implementation, would call native FFI
+        const strategy = {
+            pageIndex,
+            description: 'Standard text extraction recommended',
+            recommendsOcr: false,
+            recommendedMethod: 'text_extraction',
+            confidence: 0.9,
+        };
+        this.setCached(cacheKey, strategy);
+        return strategy;
+    }
+    /**
+     * Detects tables on a page
+     * Matches: Python detectTables(), Java detectTables(), C# DetectTables()
+     */
+    async detectTables(pageIndex) {
+        const cacheKey = `ml:tables:${pageIndex}`;
+        if (this.resultCache.has(cacheKey)) {
+            return this.resultCache.get(cacheKey);
+        }
+        // In real implementation, would call native FFI
+        const tables = [];
+        this.setCached(cacheKey, tables);
+        return tables;
+    }
+    /**
+     * Detects columns on a page
+     * Matches: Python detectColumns(), Java detectColumns(), C# DetectColumns()
+     */
+    async detectColumns(pageIndex) {
+        const cacheKey = `ml:columns:${pageIndex}`;
+        if (this.resultCache.has(cacheKey)) {
+            return this.resultCache.get(cacheKey);
+        }
+        // In real implementation, would call native FFI
+        const columns = [];
+        this.setCached(cacheKey, columns);
+        return columns;
+    }
+    /**
+     * Gets average page complexity in document
+     * Matches: Python getAverageComplexity(), Java getAverageComplexity(), C# GetAverageComplexity()
+     */
+    async getAverageComplexity() {
+        const cacheKey = 'ml:avg_complexity';
+        if (this.resultCache.has(cacheKey)) {
+            return this.resultCache.get(cacheKey);
+        }
+        // In real implementation, would call native FFI
+        const complexity = 0.5;
+        this.setCached(cacheKey, complexity);
+        return complexity;
+    }
+    /**
+     * Gets most common content type
+     * Matches: Python getMostCommonContentType(), Java getMostCommonContentType(), C# GetMostCommonContentType()
+     */
+    async getMostCommonContentType() {
+        const cacheKey = 'ml:common_content_type';
+        if (this.resultCache.has(cacheKey)) {
+            return this.resultCache.get(cacheKey);
+        }
+        // In real implementation, would call native FFI
+        const contentType = ContentType.TextImages;
+        this.setCached(cacheKey, contentType);
+        return contentType;
+    }
+    /**
+     * Estimates total document processing time
+     * Matches: Python estimateProcessingTime(), Java estimateProcessingTime(), C# EstimateProcessingTime()
+     */
+    async estimateProcessingTime() {
+        const cacheKey = 'ml:estimated_time';
+        if (this.resultCache.has(cacheKey)) {
+            return this.resultCache.get(cacheKey);
+        }
+        // In real implementation, would call native FFI
+        const time = 1000;
+        this.setCached(cacheKey, time);
+        return time;
+    }
+    /**
+     * Clears the result cache
+     * Matches: Python clearCache(), Java clearCache(), C# ClearCache()
+     */
+    clearCache() {
+        this.resultCache.clear();
+        this.emit('cacheCleared');
+    }
+    /**
+     * Gets cache statistics
+     * Matches: Python getCacheStats(), Java getCacheStats(), C# GetCacheStats()
+     */
+    getCacheStats() {
+        return {
+            cacheSize: this.resultCache.size,
+            maxCacheSize: this.maxCacheSize,
+            entries: Array.from(this.resultCache.keys()),
+        };
+    }
+    // Private helper methods
+    setCached(key, value) {
+        this.resultCache.set(key, value);
+        // Simple LRU eviction
+        if (this.resultCache.size > this.maxCacheSize) {
+            const firstKey = this.resultCache.keys().next().value;
+            if (firstKey !== undefined) {
+                this.resultCache.delete(firstKey);
+            }
+        }
+    }
+}
+export default HybridMLManager;

package/lib/index.d.ts

@@ -0,0 +1,205 @@
+import { Align, AnnotationBuilder, ConversionOptionsBuilder, DocumentBuilder, EmbeddedFont, MetadataBuilder, PageBuilder, PdfBuilder, SearchOptionsBuilder, StreamingTable } from './builders/index';
+import { DocumentEditor } from './document-editor';
+import { AccessibilityException, CertificateLoadFailed, ComplianceException, EncryptionException, ErrorCategory, ErrorSeverity, InvalidStateException, IoException, mapFfiErrorCode, OcrException, OptimizationException, ParseException, PdfException, RedactionException, RenderingException, SearchException, SignatureException, SigningFailed, UnknownError, UnsupportedFeatureException, ValidationException, wrapAsyncMethod, wrapError, wrapMethod } from './errors';
+import { AnnotationManager, type BatchDocument, BatchManager, type BatchOptions, type BatchProgress, type BatchResult, type BatchStatistics, createExtractionStream, createMetadataStream, createSearchStream, ExtractionManager, ExtractionStream, LayerManager, MetadataManager, MetadataStream, OutlineManager, RenderingManager, SearchManager, SearchStream, SecurityManager } from './managers/index';
+import type { Column, SpanCell, StreamingTableConfig, Table, TableMode, TableSpec } from './types/common.js';
+import type { WorkerResult, WorkerTask } from './workers/index';
+import { WorkerPool, workerPool } from './workers/index';
+declare const OcrManager: any, OCRManager: any, OCRDetectionMode: any, ComplianceManager: any, PdfALevel: any, PdfXLevel: any, PdfUALevel: any, ComplianceIssueType: any, IssueSeverity: any, SignatureManager: any, SignatureAlgorithm: any, DigestAlgorithm: any, BarcodeManager: any, BarcodeFormat: any, BarcodeErrorCorrection: any, FormFieldManager: any, FormFieldType: any, FieldVisibility: any, ResultAccessorsManager: any, SearchResultProperties: any, FontProperties: any, ImageProperties: any, AnnotationProperties: any, ThumbnailManager: any, ThumbnailSize: any, ImageFormat: any, HybridMLManager: any, PageComplexity: any, ContentType: any, XfaManager: any, XfaFormType: any, XfaFieldType: any, CacheManager: any, EditingManager: any, AccessibilityManager: any, OptimizationManager: any, EnterpriseManager: any;
+declare const OCRLanguage: any;
+/**
+ * Options mirroring Rust's `RenderOptions` struct
+ * (see `src/rendering/page_renderer.rs:41`). Used by
+ * {@link PdfDocumentImpl.renderPageWithOptions}.
+ */
+export interface RenderOptions {
+    /** Resolution (default 150). */
+    dpi?: number;
+    /** Output format (default PNG). */
+    format?: 'png' | 'jpeg';
+    /** RGBA 0..=1 tuple (default opaque white). */
+    background?: [number, number, number, number];
+    /** Drop background fill entirely (overrides `background`). */
+    transparentBackground?: boolean;
+    /** Render annotation layer (default true). */
+    renderAnnotations?: boolean;
+    /** JPEG quality 1..=100 (default 85). */
+    jpegQuality?: number;
+}
+/**
+ * Raw premultiplied RGBA8888 pixel buffer. Layout: row-major, top-left origin,
+ * 4 bytes (R,G,B,A) per pixel, `data.length === width * height * 4`.
+ * Alpha is premultiplied (PDF spec §11 transparency model).
+ */
+export interface RgbaPixmap {
+    data: Buffer;
+    width: number;
+    height: number;
+}
+declare class PdfDocumentImpl {
+    private _handle;
+    private _closed;
+    /** Promise-cached mutex; single Promise ensures no race on concurrent first calls. */
+    private _muPromise;
+    constructor(handle: any);
+    static open(path: string): PdfDocumentImpl;
+    static openFromBuffer(buffer: Buffer | Uint8Array): PdfDocumentImpl;
+    static openWithPassword(path: string, password: string): PdfDocumentImpl;
+    private ensureOpen;
+    get handle(): any;
+    pageCount(): number;
+    getPageCount(): number;
+    get PageCount(): number;
+    extractText(pageIndex: number): string;
+    toMarkdown(pageIndex: number): string;
+    toHtml(pageIndex: number): string;
+    toPlainText(pageIndex: number): string;
+    toMarkdownAll(): string;
+    extractAllText(): string;
+    toHtmlAll(): string;
+    toPlainTextAll(): string;
+    getVersion(): {
+        major: number;
+        minor: number;
+    };
+    hasStructureTree(): boolean;
+    hasXFA(): boolean;
+    getPageWidth(pageIndex: number): number;
+    getPageHeight(pageIndex: number): number;
+    getPageRotation(pageIndex: number): number;
+    searchPage(pageIndex: number, query: string, caseSensitive?: boolean): any;
+    searchAll(query: string, caseSensitive?: boolean): any;
+    getFormFields(): any;
+    getOutline(): any;
+    getPageAnnotations(pageIndex: number): any;
+    getEmbeddedFonts(pageIndex: number): any;
+    getEmbeddedImages(pageIndex: number): any;
+    extractWords(pageIndex: number): any;
+    extractTextLines(pageIndex: number): any;
+    extractTables(pageIndex: number): Table[];
+    extractPaths(pageIndex: number): any;
+    ocrExtractText(pageIndex: number, engineHandle: any): any;
+    /**
+     * Render a page with the full Rust `RenderOptions` surface
+     * (DPI, format, RGBA background, transparency, annotation toggle,
+     * JPEG quality). Returns the image bytes.
+     */
+    renderPageWithOptions(pageIndex: number, options?: RenderOptions): Uint8Array;
+    /**
+     * Estimate render time (milliseconds) for a page at a given DPI.
+     * Thin wrapper around the existing `estimateRenderTime` N-API
+     * export — exposed in TS for the first time as part of gap L.
+     */
+    estimateRenderTime(pageIndex: number, dpi?: number): number;
+    /**
+     * Render a page to fit inside a `width × height` pixel box, preserving
+     * aspect ratio. Picks the largest DPI such that both rendered
+     * dimensions are ≤ the target box, so the output may be smaller than
+     * `width × height` on one axis. Issue #448.
+     *
+     * @param pageIndex   zero-based page index
+     * @param width       target box width (pixels, must be > 0)
+     * @param height      target box height (pixels, must be > 0)
+     * @param format      `'png'` (default) or `'jpeg'`
+     */
+    renderPageFit(pageIndex: number, width: number, height: number, format?: 'png' | 'jpeg'): Uint8Array;
+    /** Lazy-initialises the per-instance Mutex (avoids a hard dep at load time). */
+    private _getMutex;
+    /**
+     * Async variant of {@link renderPageWithOptions} serialised through a
+     * per-instance mutex. Use when calling from `worker_threads` or `Promise.all`.
+     */
+    renderPageWithOptionsAsync(pageIndex: number, options?: RenderOptions): Promise<Uint8Array>;
+    /**
+     * Async variant of {@link renderPageFit} serialised through a per-instance mutex.
+     */
+    renderPageFitAsync(pageIndex: number, width: number, height: number, format?: 'png' | 'jpeg'): Promise<Uint8Array>;
+    /**
+     * Renders a page as raw premultiplied RGBA8888 pixels. No PNG/JPEG encoding
+     * overhead — useful for direct handoff to image-processing libraries.
+     * @param pageIndex Zero-based page index.
+     * @param dpi Resolution in dots per inch (default 150).
+     */
+    renderToPixmap(pageIndex: number, dpi?: number): RgbaPixmap;
+    /**
+     * Async variant of {@link renderToPixmap} serialised through a per-instance mutex.
+     */
+    renderToPixmapAsync(pageIndex: number, dpi?: number): Promise<RgbaPixmap>;
+    page(index: number): Page;
+    [Symbol.iterator](): Iterator<Page>;
+    /**
+     * Async iteration over the document's pages — issue #447. The body
+     * is identical to the sync iterator (page handles are constructed
+     * synchronously) but exposing this surface lets consumers `for await`
+     * uniformly with other async resources without an explicit
+     * `Promise.resolve(...)`.
+     */
+    [Symbol.asyncIterator](): AsyncIterator<Page>;
+    /**
+     * Validate PDF/A conformance at a given level.
+     * @param level - "1a"|"1b"|"2a"|"2b"|"2u"|"3a"|"3b"|"3u" (default "2b")
+     */
+    validatePdfA(level?: '1a' | '1b' | '2a' | '2b' | '2u' | '3a' | '3b' | '3u'): {
+        compliant: boolean;
+        errors: string[];
+        warnings: string[];
+    };
+    /**
+     * Convert document to PDF/A conformance in-place.
+     * @param level - "1b"|"2b"|"2u"|"3b" etc. (default "2b")
+     * @returns true if the document is fully PDF/A-compliant after conversion (false if errors remain, e.g. fonts not embeddable without the rendering feature)
+     */
+    convertToPdfA(level?: '1a' | '1b' | '2a' | '2b' | '2u' | '3a' | '3b' | '3u'): boolean;
+    /**
+     * Return the current document bytes (including any in-place modifications
+     * made by convertToPdfA).
+     */
+    toBuffer(): Buffer;
+    close(): void;
+    [Symbol.dispose](): void;
+}
+declare class Page {
+    private _doc;
+    private _index;
+    private _cache;
+    constructor(doc: PdfDocumentImpl, index: number);
+    get index(): number;
+    get width(): number;
+    get height(): number;
+    get rotation(): number;
+    text(): string;
+    markdown(): string;
+    html(): string;
+    plainText(): string;
+    words(): any;
+    lines(): any;
+    tables(): Table[];
+    images(): any;
+    paths(): any;
+    annotations(): any;
+    fonts(): any;
+    search(query: string, caseSensitive?: boolean): any;
+    toString(): string;
+}
+declare function generateBarcodeSvg(data: string, format?: number, sizePx?: number): string;
+declare function generateQrCodeSvg(data: string, errorCorrection?: number, sizePx?: number): string;
+declare const getVersion: any;
+declare const getPdfOxideVersion: any;
+declare const getActiveCryptoProvider: any;
+declare const isFipsCryptoAvailable: any;
+declare const useFipsCryptoProvider: any;
+declare const PdfDocument: any;
+declare const Pdf: any;
+declare const PdfError: typeof PdfException;
+declare const PageSize: any;
+declare const Rect: any;
+declare const Point: any;
+declare const Color: any;
+declare const ConversionOptions: any;
+declare const SearchOptions: any;
+declare const SearchResult: any;
+declare const TextSearcher: any;
+export { Timestamp, TimestampHashAlgorithm } from './timestamp.js';
+export { TsaClient, type TsaClientOptions } from './tsa-client.js';
+export type { BatchDocument, BatchOptions, BatchProgress, BatchResult, BatchStatistics, Column, SpanCell, StreamingTableConfig, Table, TableMode, TableSpec, WorkerResult, WorkerTask, };
+export { AccessibilityException, AccessibilityManager, Align, AnnotationBuilder, AnnotationManager, AnnotationProperties, BarcodeErrorCorrection, BarcodeFormat, BarcodeManager, BatchManager, CacheManager, CertificateLoadFailed, Color, ComplianceException, ComplianceIssueType, ComplianceManager, ContentType, ConversionOptions, ConversionOptionsBuilder, createExtractionStream, createMetadataStream, createSearchStream, DigestAlgorithm, DocumentBuilder, DocumentEditor, EditingManager, EmbeddedFont, EncryptionException, EnterpriseManager, ErrorCategory, ErrorSeverity, ExtractionManager, ExtractionStream, FieldVisibility, FontProperties, FormFieldManager, FormFieldType, generateBarcodeSvg, generateQrCodeSvg, getActiveCryptoProvider, getPdfOxideVersion, getVersion, HybridMLManager, ImageFormat, ImageProperties, InvalidStateException, IoException, IssueSeverity, isFipsCryptoAvailable, LayerManager, MetadataBuilder, MetadataManager, MetadataStream, mapFfiErrorCode, OCRDetectionMode, OCRLanguage, OCRManager, OcrException, OcrManager, OptimizationException, OptimizationManager, OutlineManager, Page, PageBuilder, PageComplexity, PageSize, ParseException, Pdf, PdfALevel, PdfBuilder, PdfDocument, PdfError, PdfException, PdfUALevel, PdfXLevel, Point, Rect, RedactionException, RenderingException, RenderingManager, ResultAccessorsManager, SearchException, SearchManager, SearchOptions, SearchOptionsBuilder, SearchResult, SearchResultProperties, SearchStream, SecurityManager, SignatureAlgorithm, SignatureException, SignatureManager, SigningFailed, StreamingTable, TextSearcher, ThumbnailManager, ThumbnailSize, UnknownError, UnsupportedFeatureException, useFipsCryptoProvider, ValidationException, WorkerPool, workerPool, wrapAsyncMethod, wrapError, wrapMethod, XfaFieldType, XfaFormType, XfaManager, };