pdf-oxide-fips 0.3.47

package/lib/managers/page-manager.js

@@ -0,0 +1,235 @@
+/**
+ * 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 class PageManager {
+    /**
+     * Creates a new PageManager 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;
+        this._cache = new Map();
+    }
+    /**
+     * Clears the page cache
+     */
+    clearCache() {
+        this._cache.clear();
+    }
+    /**
+     * Gets the total number of pages in the document
+     * @returns Number of pages
+     */
+    getPageCount() {
+        const cacheKey = 'page:count';
+        if (this._cache.has(cacheKey)) {
+            return this._cache.get(cacheKey);
+        }
+        try {
+            const count = this._document.pageCount || 0;
+            this._cache.set(cacheKey, count);
+            return count;
+        }
+        catch (error) {
+            return 0;
+        }
+    }
+    /**
+     * 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) {
+        if (pageIndex < 0) {
+            return false;
+        }
+        return pageIndex < this.getPageCount();
+    }
+    /**
+     * 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) {
+        const cacheKey = `page:info:${pageIndex}`;
+        if (this._cache.has(cacheKey)) {
+            return this._cache.get(cacheKey);
+        }
+        if (!this.isValidPageIndex(pageIndex)) {
+            throw new Error(`Invalid page index: ${pageIndex}`);
+        }
+        try {
+            const page = this._document.getPage(pageIndex);
+            const info = {
+                index: pageIndex,
+                width: page?.width || 0,
+                height: page?.height || 0,
+            };
+            this._cache.set(cacheKey, info);
+            return info;
+        }
+        catch (error) {
+            return {
+                index: pageIndex,
+                width: 0,
+                height: 0,
+            };
+        }
+    }
+    /**
+     * 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() {
+        const cacheKey = 'page:info:all';
+        if (this._cache.has(cacheKey)) {
+            return this._cache.get(cacheKey);
+        }
+        const count = this.getPageCount();
+        const pages = [];
+        for (let i = 0; i < count; i++) {
+            pages.push(this.getPageInfo(i));
+        }
+        this._cache.set(cacheKey, pages);
+        return pages;
+    }
+    /**
+     * Checks if the document has no pages
+     * @returns True if the document has no pages
+     */
+    isEmpty() {
+        return this.getPageCount() === 0;
+    }
+    /**
+     * Checks if the document has more than one page
+     * @returns True if document has multiple pages
+     */
+    hasMultiplePages() {
+        return this.getPageCount() > 1;
+    }
+    /**
+     * 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() {
+        const count = this.getPageCount();
+        if (count === 0) {
+            return { firstPage: 0, lastPage: -1 };
+        }
+        return { firstPage: 0, lastPage: count - 1 };
+    }
+    /**
+     * 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() {
+        const pages = this.getAllPageInfo();
+        if (pages.length === 0) {
+            return {
+                count: 0,
+                minWidth: 0,
+                maxWidth: 0,
+                minHeight: 0,
+                maxHeight: 0,
+                averageWidth: 0,
+                averageHeight: 0,
+                hasVariableSizes: false,
+            };
+        }
+        const widths = pages.map((p) => p.width);
+        const heights = pages.map((p) => p.height);
+        const minWidth = Math.min(...widths);
+        const maxWidth = Math.max(...widths);
+        const minHeight = Math.min(...heights);
+        const maxHeight = Math.max(...heights);
+        const averageWidth = widths.reduce((a, b) => a + b, 0) / widths.length;
+        const averageHeight = heights.reduce((a, b) => a + b, 0) / heights.length;
+        return {
+            count: pages.length,
+            minWidth,
+            maxWidth,
+            minHeight,
+            maxHeight,
+            averageWidth,
+            averageHeight,
+            hasVariableSizes: minWidth !== maxWidth || minHeight !== maxHeight,
+        };
+    }
+    /**
+     * 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, maxWidth, minHeight, maxHeight) {
+        const pages = this.getAllPageInfo();
+        return pages.filter((p) => p.width >= minWidth && p.width <= maxWidth && p.height >= minHeight && p.height <= maxHeight);
+    }
+    /**
+     * Gets landscape pages
+     * @returns Array of landscape PageInfo objects
+     */
+    getLandscapePages() {
+        const pages = this.getAllPageInfo();
+        return pages.filter((p) => p.width > p.height);
+    }
+    /**
+     * Gets portrait pages
+     * @returns Array of portrait PageInfo objects
+     */
+    getPortraitPages() {
+        const pages = this.getAllPageInfo();
+        return pages.filter((p) => p.height > p.width);
+    }
+}

package/lib/managers/pattern-detection.d.ts

@@ -0,0 +1,169 @@
+/**
+ * Pattern Detection Manager - TypeScript/Node.js Implementation
+ *
+ * Provides ML-powered pattern detection for PDF analysis:
+ * - Table detection and extraction
+ * - Column detection and analysis
+ * - Barcode detection and decoding
+ * - Form field detection
+ * - Layout pattern recognition
+ */
+import type { PdfDocument } from '../types/document-types.js';
+/**
+ * Represents a detected table region on a page.
+ */
+export interface TableRegion {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+    readonly rowCount?: number;
+    readonly columnCount?: number;
+    readonly confidence?: number;
+}
+/**
+ * Represents a detected column region on a page.
+ */
+export interface ColumnRegion {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+    readonly columnIndex?: number;
+    readonly confidence?: number;
+}
+/**
+ * Represents a detected barcode.
+ */
+export interface BarcodeRegion {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+    readonly format: string;
+    readonly value: string;
+    readonly confidence?: number;
+}
+/**
+ * Represents a detected form field.
+ */
+export interface FormFieldRegion {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+    readonly fieldType: string;
+    readonly fieldName?: string;
+    readonly confidence?: number;
+}
+/**
+ * Layout pattern type enumeration.
+ */
+export declare enum LayoutPatternType {
+    SINGLE_COLUMN = "single_column",
+    MULTI_COLUMN = "multi_column",
+    TABLE_BASED = "table_based",
+    FORM_BASED = "form_based",
+    MAGAZINE_STYLE = "magazine_style",
+    COMPLEX_MIXED = "complex_mixed"
+}
+/**
+ * Detected layout pattern.
+ */
+export interface LayoutPattern {
+    readonly pageIndex: number;
+    readonly patternType: LayoutPatternType;
+    readonly confidence: number;
+    readonly regions: Array<TableRegion | ColumnRegion>;
+}
+/**
+ * Pattern Detection Manager for TypeScript/Node.js
+ *
+ * Provides detection and analysis of common patterns in PDF documents.
+ */
+export declare class PatternDetectionManager {
+    private readonly document;
+    private readonly cache;
+    /**
+     * Create a new PatternDetectionManager.
+     */
+    constructor(document: PdfDocument);
+    /**
+     * Detect tables on a specific page.
+     *
+     * @param pageIndex - Index of the page to analyze
+     * @returns Array of detected table regions
+     */
+    detectTables(pageIndex: number): Promise<TableRegion[]>;
+    /**
+     * Detect columns on a specific page.
+     *
+     * @param pageIndex - Index of the page to analyze
+     * @returns Array of detected column regions
+     */
+    detectColumns(pageIndex: number): Promise<ColumnRegion[]>;
+    /**
+     * Detect barcodes on a specific page.
+     *
+     * @param pageIndex - Index of the page to analyze
+     * @returns Array of detected barcodes
+     */
+    detectBarcodes(pageIndex: number): Promise<BarcodeRegion[]>;
+    /**
+     * Detect form fields on a specific page.
+     *
+     * @param pageIndex - Index of the page to analyze
+     * @returns Array of detected form fields
+     */
+    detectFormFields(pageIndex: number): Promise<FormFieldRegion[]>;
+    /**
+     * Analyze layout pattern of a page.
+     *
+     * @param pageIndex - Index of the page to analyze
+     * @returns Detected layout pattern
+     */
+    analyzeLayoutPattern(pageIndex: number): Promise<LayoutPattern>;
+    /**
+     * Detect all patterns on a specific page.
+     *
+     * @param pageIndex - Index of the page to analyze
+     * @returns Object with all detected patterns
+     */
+    detectAllPatterns(pageIndex: number): Promise<{
+        tables: TableRegion[];
+        columns: ColumnRegion[];
+        barcodes: BarcodeRegion[];
+        formFields: FormFieldRegion[];
+        layout: LayoutPattern;
+    }>;
+    /**
+     * Analyze patterns across entire document.
+     *
+     * @returns Array of layout patterns for each page
+     */
+    analyzeDocumentPatterns(): Promise<LayoutPattern[]>;
+    /**
+     * Find pages with specific pattern type.
+     *
+     * @param patternType - Pattern type to find
+     * @returns Array of page indices with the specified pattern
+     */
+    findPagesWithPattern(patternType: LayoutPatternType): Promise<number[]>;
+    /**
+     * Get pattern statistics for the document.
+     *
+     * @returns Statistics about detected patterns
+     */
+    getPatternStatistics(): Promise<{
+        totalPages: number;
+        pagesWithTables: number;
+        pagesWithColumns: number;
+        avgTablesPerPage: number;
+        avgColumnsPerPage: number;
+    }>;
+    /**
+     * Clear the internal cache.
+     */
+    clearCache(): void;
+}
+export default PatternDetectionManager;