pdf-oxide-fips 0.3.47

package/lib/managers/streams.js

@@ -0,0 +1,477 @@
+/**
+ * Stream API support for PDF Oxide Node.js
+ *
+ * Provides Readable streams for search results, text extraction, and page metadata.
+ * Supports backpressure handling and proper Node.js stream semantics.
+ *
+ * Phase 2.4 implementation for idiomatic Node.js patterns with Stream API.
+ */
+import { Readable } from 'node:stream';
+/**
+ * Readable stream for search results
+ *
+ * Emits search results one at a time with proper backpressure handling.
+ * Supports searching either a specific page or the entire document.
+ *
+ * Supports both traditional stream API (.on('data')) and async iteration (for await...of).
+ *
+ * @example
+ * ```typescript
+ * // Traditional stream API
+ * const stream = new SearchStream(searchManager, 'keyword');
+ * stream.on('data', (result) => {
+ *   console.log(`Found on page ${result.pageIndex}: ${result.text}`);
+ * });
+ *
+ * // Async iteration
+ * const stream = new SearchStream(searchManager, 'keyword');
+ * for await (const result of stream) {
+ *   console.log(`Found on page ${result.pageIndex}: ${result.text}`);
+ * }
+ * ```
+ */
+export class SearchStream extends Readable {
+    /**
+     * Creates a new SearchStream
+     * @param searchManager - The search manager instance
+     * @param searchTerm - Text to search for
+     * @param options - Search options
+     * @throws Error if parameters are invalid
+     */
+    constructor(searchManager, searchTerm, options = {}) {
+        super({ objectMode: true });
+        if (!searchManager) {
+            throw new Error('SearchManager is required');
+        }
+        if (!searchTerm || typeof searchTerm !== 'string') {
+            throw new Error('Search term must be a non-empty string');
+        }
+        this.searchManager = searchManager;
+        this.searchTerm = searchTerm;
+        this.options = options;
+        this.pageIndex = options.pageIndex;
+        this.caseSensitive = options.caseSensitive ?? false;
+        this.wholeWords = options.wholeWords ?? false;
+        this.maxResults = options.maxResults ?? Infinity;
+        this._results = null;
+        this._currentIndex = 0;
+        this._resultCount = 0;
+        this._initialized = false;
+        this._ended = false;
+    }
+    /**
+     * Initialize results (lazy initialization)
+     * @private
+     */
+    _initialize() {
+        if (this._initialized)
+            return;
+        this._initialized = true;
+        try {
+            // Perform search
+            if (this.pageIndex !== undefined) {
+                this._results = (this.searchManager.search(this.searchTerm, this.pageIndex, {
+                    caseSensitive: this.caseSensitive,
+                    wholeWords: this.wholeWords,
+                }) || []);
+            }
+            else {
+                this._results = (this.searchManager.searchAll(this.searchTerm, {
+                    caseSensitive: this.caseSensitive,
+                    wholeWords: this.wholeWords,
+                }) || []);
+            }
+            // Apply max results limit
+            if (this._results && this._results.length > this.maxResults) {
+                this._results = this._results.slice(0, this.maxResults);
+            }
+        }
+        catch (error) {
+            this.destroy(error);
+        }
+    }
+    /**
+     * Implement _read() for readable stream
+     * @private
+     */
+    _read() {
+        // Initialize on first read
+        if (!this._initialized) {
+            this._initialize();
+        }
+        // Check if we have results to emit
+        if (!this._results || this._currentIndex >= this._results.length) {
+            // All results emitted
+            if (!this._ended) {
+                this._ended = true;
+                this.push(null);
+            }
+            return;
+        }
+        // Emit next result
+        const result = this._results[this._currentIndex];
+        this._currentIndex++;
+        // Format the result
+        const data = {
+            text: result.text || result.getText?.(),
+            pageIndex: result.pageIndex || result.page || 0,
+            position: result.position || 0,
+            boundingBox: result.boundingBox,
+        };
+        this.push(data);
+    }
+    /**
+     * Implement async iteration protocol for `for await...of` support
+     * @returns AsyncIterator for iterating over search results
+     */
+    async *[Symbol.asyncIterator]() {
+        // Initialize on first iteration
+        if (!this._initialized) {
+            this._initialize();
+        }
+        // Yield results one by one
+        while (this._results && this._currentIndex < this._results.length) {
+            const result = this._results[this._currentIndex];
+            this._currentIndex++;
+            const data = {
+                text: result.text || result.getText?.(),
+                pageIndex: result.pageIndex || result.page || 0,
+                position: result.position || 0,
+                boundingBox: result.boundingBox,
+            };
+            yield data;
+        }
+        if (!this._ended) {
+            this._ended = true;
+            this.destroy();
+        }
+    }
+}
+/**
+ * Readable stream for text extraction with progress tracking
+ *
+ * Emits extraction progress for each page with progress percentage.
+ * Supports multiple extraction formats: text, markdown, html.
+ * Supports both traditional stream API and async iteration.
+ *
+ * @example
+ * ```typescript
+ * // Traditional stream API
+ * const stream = new ExtractionStream(extractionManager, 0, 10, 'markdown');
+ * stream.on('data', (progress) => {
+ *   console.log(`Progress: ${Math.round(progress.progress * 100)}%`);
+ *   console.log(`Page ${progress.pageIndex + 1}: ${progress.extractedText.length} chars`);
+ * });
+ *
+ * // Async iteration
+ * const stream = new ExtractionStream(extractionManager, 0, 10, 'markdown');
+ * for await (const progress of stream) {
+ *   console.log(`Progress: ${Math.round(progress.progress * 100)}%`);
+ * }
+ * ```
+ */
+export class ExtractionStream extends Readable {
+    /**
+     * Creates a new ExtractionStream
+     * @param extractionManager - The extraction manager instance
+     * @param startPage - Starting page index (inclusive)
+     * @param endPage - Ending page index (exclusive)
+     * @param extractionType - 'text', 'markdown', or 'html'
+     * @param options - Additional extraction options
+     * @throws Error if parameters are invalid
+     */
+    constructor(extractionManager, startPage, endPage, extractionType = 'text', options = {}) {
+        super({ objectMode: true });
+        if (!extractionManager) {
+            throw new Error('ExtractionManager is required');
+        }
+        if (typeof startPage !== 'number' || startPage < 0) {
+            throw new Error('Start page must be a non-negative number');
+        }
+        if (typeof endPage !== 'number' || endPage <= startPage) {
+            throw new Error('End page must be greater than start page');
+        }
+        if (!['text', 'markdown', 'html'].includes(extractionType)) {
+            throw new Error("Extraction type must be 'text', 'markdown', or 'html'");
+        }
+        this.extractionManager = extractionManager;
+        this.startPage = startPage;
+        this.endPage = endPage;
+        this.extractionType = extractionType;
+        this.options = options;
+        this._currentPage = startPage;
+        this._totalPages = endPage - startPage;
+        this._ended = false;
+    }
+    /**
+     * Implement _read() for readable stream
+     * @private
+     */
+    _read() {
+        // Check if we've processed all pages
+        if (this._currentPage >= this.endPage) {
+            if (!this._ended) {
+                this._ended = true;
+                this.push(null);
+            }
+            return;
+        }
+        try {
+            // Extract current page
+            let extractedText;
+            if (this.extractionType === 'markdown') {
+                extractedText = this.extractionManager.extractMarkdown(this._currentPage, this.options);
+            }
+            else if (this.extractionType === 'html') {
+                extractedText = this.extractionManager.extractHtml(this._currentPage, this.options);
+            }
+            else {
+                extractedText = this.extractionManager.extractText(this._currentPage, this.options);
+            }
+            // Emit progress object
+            const progress = {
+                pageIndex: this._currentPage,
+                totalPages: this._totalPages,
+                extractedText: extractedText || '',
+                extractionType: this.extractionType,
+                progress: (this._currentPage - this.startPage + 1) / this._totalPages,
+            };
+            this._currentPage++;
+            this.push(progress);
+        }
+        catch (error) {
+            this.destroy(error);
+        }
+    }
+    /**
+     * Implement async iteration protocol for `for await...of` support
+     * @returns AsyncGenerator for iterating over extraction progress
+     */
+    async *[Symbol.asyncIterator]() {
+        // Process each page
+        while (this._currentPage < this.endPage) {
+            try {
+                // Extract current page
+                let extractedText;
+                if (this.extractionType === 'markdown') {
+                    extractedText = this.extractionManager.extractMarkdown(this._currentPage, this.options);
+                }
+                else if (this.extractionType === 'html') {
+                    extractedText = this.extractionManager.extractHtml(this._currentPage, this.options);
+                }
+                else {
+                    extractedText = this.extractionManager.extractText(this._currentPage, this.options);
+                }
+                // Create progress object
+                const progress = {
+                    pageIndex: this._currentPage,
+                    totalPages: this._totalPages,
+                    extractedText: extractedText || '',
+                    extractionType: this.extractionType,
+                    progress: (this._currentPage - this.startPage + 1) / this._totalPages,
+                };
+                this._currentPage++;
+                yield progress;
+            }
+            catch (error) {
+                this.destroy(error);
+                return;
+            }
+        }
+        if (!this._ended) {
+            this._ended = true;
+            this.destroy();
+        }
+    }
+}
+/**
+ * Readable stream for page metadata retrieval
+ *
+ * Emits page metadata (dimensions, fonts, images) for each page in range.
+ * Supports lazy loading of metadata per page.
+ * Supports both traditional stream API and async iteration.
+ *
+ * @example
+ * ```typescript
+ * // Traditional stream API
+ * const stream = new MetadataStream(renderingManager, 0, 10);
+ * stream.on('data', (metadata) => {
+ *   console.log(`Page ${metadata.pageIndex + 1}: ${metadata.width}x${metadata.height}`);
+ *   console.log(`  Fonts: ${metadata.fontCount}, Images: ${metadata.imageCount}`);
+ * });
+ *
+ * // Async iteration
+ * const stream = new MetadataStream(renderingManager, 0, 10);
+ * for await (const metadata of stream) {
+ *   console.log(`Page ${metadata.pageIndex + 1}: ${metadata.width}x${metadata.height}`);
+ * }
+ * ```
+ */
+export class MetadataStream extends Readable {
+    /**
+     * Creates a new MetadataStream
+     * @param renderingManager - The rendering manager instance
+     * @param startPage - Starting page index (inclusive)
+     * @param endPage - Ending page index (exclusive)
+     * @throws Error if parameters are invalid
+     */
+    constructor(renderingManager, startPage, endPage) {
+        super({ objectMode: true });
+        if (!renderingManager) {
+            throw new Error('RenderingManager is required');
+        }
+        if (typeof startPage !== 'number' || startPage < 0) {
+            throw new Error('Start page must be a non-negative number');
+        }
+        if (typeof endPage !== 'number' || endPage <= startPage) {
+            throw new Error('End page must be greater than start page');
+        }
+        this.renderingManager = renderingManager;
+        this.startPage = startPage;
+        this.endPage = endPage;
+        this._currentPage = startPage;
+        this._ended = false;
+    }
+    /**
+     * Implement _read() for readable stream
+     * @private
+     */
+    _read() {
+        // Check if we've processed all pages
+        if (this._currentPage >= this.endPage) {
+            if (!this._ended) {
+                this._ended = true;
+                this.push(null);
+            }
+            return;
+        }
+        try {
+            // Get page dimensions
+            const dimensions = this.renderingManager.getPageDimensions(this._currentPage);
+            // Get embedded resources
+            const fonts = this.renderingManager.getEmbeddedFonts?.(this._currentPage) || [];
+            const images = this.renderingManager.getEmbeddedImages?.(this._currentPage) || [];
+            // Get rotation
+            const rotation = dimensions?.rotation || 0;
+            // Emit metadata object
+            const metadata = {
+                pageIndex: this._currentPage,
+                width: dimensions?.width || 0,
+                height: dimensions?.height || 0,
+                fontCount: Array.isArray(fonts) ? fonts.length : 0,
+                imageCount: Array.isArray(images) ? images.length : 0,
+                rotation: rotation,
+            };
+            this._currentPage++;
+            this.push(metadata);
+        }
+        catch (error) {
+            this.destroy(error);
+        }
+    }
+    /**
+     * Implement async iteration protocol for `for await...of` support
+     * @returns AsyncGenerator for iterating over page metadata
+     */
+    async *[Symbol.asyncIterator]() {
+        // Process each page
+        while (this._currentPage < this.endPage) {
+            try {
+                // Get page dimensions
+                const dimensions = this.renderingManager.getPageDimensions(this._currentPage);
+                // Get embedded resources
+                const fonts = this.renderingManager.getEmbeddedFonts?.(this._currentPage) || [];
+                const images = this.renderingManager.getEmbeddedImages?.(this._currentPage) || [];
+                // Get rotation
+                const rotation = dimensions?.rotation || 0;
+                // Create metadata object
+                const metadata = {
+                    pageIndex: this._currentPage,
+                    width: dimensions?.width || 0,
+                    height: dimensions?.height || 0,
+                    fontCount: Array.isArray(fonts) ? fonts.length : 0,
+                    imageCount: Array.isArray(images) ? images.length : 0,
+                    rotation: rotation,
+                };
+                this._currentPage++;
+                yield metadata;
+            }
+            catch (error) {
+                this.destroy(error);
+                return;
+            }
+        }
+        if (!this._ended) {
+            this._ended = true;
+            this.destroy();
+        }
+    }
+}
+/**
+ * Creates a readable stream for search results
+ *
+ * Convenience function to create a SearchStream instance.
+ *
+ * @param searchManager - The search manager
+ * @param searchTerm - Text to search for
+ * @param options - Search options
+ * @returns A readable stream of search results
+ *
+ * @example
+ * ```typescript
+ * createSearchStream(manager, 'error')
+ *   .pipe(through2.obj((result, enc, cb) => {
+ *     console.log(`Found: ${result.text}`);
+ *     cb();
+ *   }));
+ * ```
+ */
+export function createSearchStream(searchManager, searchTerm, options = {}) {
+    return new SearchStream(searchManager, searchTerm, options);
+}
+/**
+ * Creates a readable stream for extraction with progress
+ *
+ * Convenience function to create an ExtractionStream instance.
+ *
+ * @param extractionManager - The extraction manager
+ * @param startPage - Starting page index
+ * @param endPage - Ending page index
+ * @param extractionType - Extraction format
+ * @param options - Additional options
+ * @returns A readable stream of extraction progress
+ *
+ * @example
+ * ```typescript
+ * createExtractionStream(manager, 0, 10, 'markdown')
+ *   .pipe(through2.obj((progress, enc, cb) => {
+ *     console.log(`${Math.round(progress.progress * 100)}% complete`);
+ *     cb();
+ *   }));
+ * ```
+ */
+export function createExtractionStream(extractionManager, startPage, endPage, extractionType = 'text', options = {}) {
+    return new ExtractionStream(extractionManager, startPage, endPage, extractionType, options);
+}
+/**
+ * Creates a readable stream for page metadata
+ *
+ * Convenience function to create a MetadataStream instance.
+ *
+ * @param renderingManager - The rendering manager
+ * @param startPage - Starting page index
+ * @param endPage - Ending page index
+ * @returns A readable stream of page metadata
+ *
+ * @example
+ * ```typescript
+ * createMetadataStream(manager, 0, 10)
+ *   .pipe(through2.obj((metadata, enc, cb) => {
+ *     console.log(`Page ${metadata.pageIndex}: ${metadata.width}x${metadata.height}`);
+ *     cb();
+ *   }));
+ * ```
+ */
+export function createMetadataStream(renderingManager, startPage, endPage) {
+    return new MetadataStream(renderingManager, startPage, endPage);
+}

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

@@ -0,0 +1,227 @@
+/**
+ * XfaManager - Canonical XFA Manager (merged from 3 implementations)
+ *
+ * Consolidates:
+ * - src/xfa-manager.ts XfaManager (detection + parsing + basic conversion)
+ * - src/managers/advanced-features.ts XFAManager (field operations + data import/export)
+ * - src/managers/xfa-creation-manager.ts XfaCreationManager (form creation + scripting)
+ *
+ * Provides complete XFA form operations.
+ */
+import { EventEmitter } from 'events';
+export declare enum XfaFormType {
+    STATIC = "static",
+    DYNAMIC = "dynamic"
+}
+export declare enum XfaFieldType {
+    TEXT = "text",
+    NUMERIC = "numeric",
+    DATE = "date",
+    TIME = "time",
+    DATETIME = "datetime",
+    CHECKBOX = "checkbox",
+    RADIO = "radio",
+    DROPDOWN = "dropdown",
+    LISTBOX = "listbox",
+    BUTTON = "button",
+    SIGNATURE = "signature",
+    IMAGE = "image",
+    BARCODE = "barcode",
+    PASSWORD = "password"
+}
+export declare enum XfaValidationType {
+    NONE = "none",
+    REQUIRED = "required",
+    PATTERN = "pattern",
+    RANGE = "range",
+    CUSTOM = "custom"
+}
+export declare enum XfaBindingType {
+    NORMAL = "normal",
+    NONE = "none",
+    GLOBAL = "global"
+}
+export interface XfaField {
+    readonly name: string;
+    readonly fieldType: XfaFieldType;
+    readonly value?: string;
+}
+export interface XfaDataset {
+    readonly xmlContent: string;
+}
+export interface XFAFormField {
+    fieldName: string;
+    fieldType: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    defaultValue?: string;
+    isReadOnly: boolean;
+}
+export interface XfaFieldConfig {
+    readonly name: string;
+    readonly fieldType: XfaFieldType;
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+    readonly caption?: string;
+    readonly defaultValue?: string;
+    readonly tooltip?: string;
+    readonly isRequired?: boolean;
+    readonly isReadOnly?: boolean;
+    readonly isHidden?: boolean;
+    readonly maxLength?: number;
+    readonly validationType?: XfaValidationType;
+    readonly validationPattern?: string;
+    readonly validationMessage?: string;
+    readonly bindingType?: XfaBindingType;
+    readonly bindingPath?: string;
+    readonly options?: readonly string[];
+    readonly font?: XfaFontConfig;
+    readonly border?: XfaBorderConfig;
+    readonly margin?: XfaMarginConfig;
+}
+export interface XfaFontConfig {
+    readonly family?: string;
+    readonly size?: number;
+    readonly weight?: 'normal' | 'bold';
+    readonly style?: 'normal' | 'italic';
+    readonly color?: string;
+}
+export interface XfaBorderConfig {
+    readonly style?: 'solid' | 'dashed' | 'dotted' | 'none';
+    readonly width?: number;
+    readonly color?: string;
+    readonly radius?: number;
+}
+export interface XfaMarginConfig {
+    readonly top?: number;
+    readonly right?: number;
+    readonly bottom?: number;
+    readonly left?: number;
+}
+export interface XfaTemplateConfig {
+    readonly name: string;
+    readonly formType: XfaFormType;
+    readonly pageWidth?: number;
+    readonly pageHeight?: number;
+    readonly defaultFont?: XfaFontConfig;
+    readonly locale?: string;
+    readonly version?: string;
+}
+export interface XfaSubformConfig {
+    readonly name: string;
+    readonly x?: number;
+    readonly y?: number;
+    readonly width?: number;
+    readonly height?: number;
+    readonly layout?: 'position' | 'table' | 'row' | 'lr-tb' | 'rl-tb' | 'tb';
+    readonly border?: XfaBorderConfig;
+    readonly breakBefore?: 'auto' | 'pageArea' | 'pageEven' | 'pageOdd';
+    readonly breakAfter?: 'auto' | 'pageArea' | 'pageEven' | 'pageOdd';
+}
+export interface XfaScriptConfig {
+    readonly language: 'JavaScript' | 'FormCalc';
+    readonly runAt: 'client' | 'server' | 'both';
+    readonly event: string;
+    readonly code: string;
+}
+export interface XfaCreationResult {
+    readonly success: boolean;
+    readonly formId?: string;
+    readonly fieldCount?: number;
+    readonly error?: string;
+    readonly warnings?: readonly string[];
+}
+export interface XfaDataOptions {
+    readonly format: 'xml' | 'json' | 'xdp';
+    readonly includeEmptyFields?: boolean;
+    readonly includeCalculatedFields?: boolean;
+    readonly validateOnImport?: boolean;
+}
+export interface XfaFieldHandle {
+    readonly fieldId: string;
+    readonly name: string;
+    readonly fieldType: XfaFieldType;
+    readonly pageIndex: number;
+}
+/**
+ * Canonical XFA Manager - all XFA operations in one class.
+ */
+export declare class XfaManager extends EventEmitter {
+    private readonly document;
+    private readonly cache;
+    private readonly maxCacheSize;
+    private readonly createdFields;
+    private formCreated;
+    private currentFormId;
+    constructor(document: any);
+    hasXfa(): boolean;
+    parseXfaForm(): any;
+    extractFieldData(): Record<string, string | undefined>;
+    getDatasetXml(): string;
+    convertToAcroForm(): boolean;
+    getFieldCount(): Promise<number>;
+    getFieldByIndex(index: number): Promise<XFAFormField | null>;
+    getFieldValue(fieldName: string): Promise<string | null>;
+    setFieldValue(fieldName: string, value: string): Promise<boolean>;
+    getFieldType(fieldName: string): Promise<string | null>;
+    isFieldReadOnly(fieldName: string): Promise<boolean>;
+    getFieldBounds(fieldName: string): Promise<[number, number, number, number] | null>;
+    getFormState(): Promise<Record<string, any> | null>;
+    exportData(filePath: string): Promise<boolean>;
+    importData(filePath: string): Promise<boolean>;
+    flattenForm(): Promise<boolean>;
+    createXfaForm(config: XfaTemplateConfig): Promise<XfaCreationResult>;
+    createFromXdpTemplate(xdpContent: string): Promise<XfaCreationResult>;
+    createFromXmlTemplate(xmlTemplate: string): Promise<XfaCreationResult>;
+    addSubform(parentPath: string, config: XfaSubformConfig): Promise<boolean>;
+    removeXfaForm(): Promise<boolean>;
+    addTextField(pageIndex: number, config: XfaFieldConfig): Promise<XfaFieldHandle | null>;
+    addNumericField(pageIndex: number, config: Omit<XfaFieldConfig, 'fieldType'>): Promise<XfaFieldHandle | null>;
+    addDateField(pageIndex: number, config: Omit<XfaFieldConfig, 'fieldType'>): Promise<XfaFieldHandle | null>;
+    addCheckboxField(pageIndex: number, config: Omit<XfaFieldConfig, 'fieldType'>): Promise<XfaFieldHandle | null>;
+    addRadioGroup(pageIndex: number, config: Omit<XfaFieldConfig, 'fieldType'> & {
+        readonly groupName: string;
+        readonly options: readonly string[];
+    }): Promise<XfaFieldHandle | null>;
+    addDropdownField(pageIndex: number, config: Omit<XfaFieldConfig, 'fieldType'> & {
+        readonly options: readonly string[];
+    }): Promise<XfaFieldHandle | null>;
+    addSignatureField(pageIndex: number, config: Omit<XfaFieldConfig, 'fieldType'>): Promise<XfaFieldHandle | null>;
+    addButton(pageIndex: number, config: Omit<XfaFieldConfig, 'fieldType'>): Promise<XfaFieldHandle | null>;
+    private addField;
+    updateField(fieldId: string, updates: Partial<XfaFieldConfig>): Promise<boolean>;
+    removeField(fieldId: string): Promise<boolean>;
+    addFieldValidation(fieldName: string, validationType: XfaValidationType, options: {
+        pattern?: string;
+        message?: string;
+        min?: number;
+        max?: number;
+        script?: string;
+    }): Promise<boolean>;
+    importXfaData(data: string, options: XfaDataOptions): Promise<boolean>;
+    exportXfaData(options: XfaDataOptions): Promise<string | null>;
+    exportAsXdp(): Promise<string | null>;
+    mergeXfaData(sourceData: string, options?: {
+        overwrite?: boolean;
+    }): Promise<boolean>;
+    addFieldScript(fieldName: string, script: XfaScriptConfig): Promise<boolean>;
+    addFormScript(script: XfaScriptConfig): Promise<boolean>;
+    removeFieldScript(fieldName: string, event: string): Promise<boolean>;
+    validateForm(): Promise<{
+        valid: boolean;
+        issues: string[];
+    }>;
+    getCreatedFields(): readonly XfaFieldHandle[];
+    hasForm(): boolean;
+    clearCache(): void;
+    getCacheStats(): Record<string, any>;
+    destroy(): void;
+    private updateCache;
+}
+/** @deprecated Use XfaManager instead */
+export declare const XFAManager: typeof XfaManager;
+export default XfaManager;