pdf-oxide-fips 0.3.47

package/lib/managers/streams.d.ts

@@ -0,0 +1,262 @@
+/**
+ * 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';
+/**
+ * SearchResult emitted by SearchStream
+ */
+export interface SearchResultData {
+    text?: string;
+    pageIndex?: number;
+    position?: number;
+    boundingBox?: Record<string, number>;
+}
+/**
+ * ExtractionProgress emitted by ExtractionStream
+ */
+export interface ExtractionProgressData {
+    pageIndex: number;
+    totalPages: number;
+    extractedText: string;
+    extractionType: 'text' | 'markdown' | 'html';
+    progress: number;
+}
+/**
+ * PageMetadata emitted by MetadataStream
+ */
+export interface PageMetadataData {
+    pageIndex: number;
+    width: number;
+    height: number;
+    fontCount: number;
+    imageCount: number;
+    rotation: number;
+}
+/**
+ * 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 declare class SearchStream extends Readable {
+    private searchManager;
+    private searchTerm;
+    private options;
+    private pageIndex;
+    private caseSensitive;
+    private wholeWords;
+    private maxResults;
+    private _results;
+    private _currentIndex;
+    private _resultCount;
+    private _initialized;
+    private _ended;
+    /**
+     * 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: any, searchTerm: string, options?: Record<string, any>);
+    /**
+     * Initialize results (lazy initialization)
+     * @private
+     */
+    private _initialize;
+    /**
+     * Implement _read() for readable stream
+     * @private
+     */
+    _read(): void;
+    /**
+     * Implement async iteration protocol for `for await...of` support
+     * @returns AsyncIterator for iterating over search results
+     */
+    [Symbol.asyncIterator](): AsyncGenerator<SearchResultData, undefined, unknown>;
+}
+/**
+ * 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 declare class ExtractionStream extends Readable {
+    private extractionManager;
+    private startPage;
+    private endPage;
+    private extractionType;
+    private options;
+    private _currentPage;
+    private _totalPages;
+    private _ended;
+    /**
+     * 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: any, startPage: number, endPage: number, extractionType?: 'text' | 'markdown' | 'html', options?: Record<string, any>);
+    /**
+     * Implement _read() for readable stream
+     * @private
+     */
+    _read(): void;
+    /**
+     * Implement async iteration protocol for `for await...of` support
+     * @returns AsyncGenerator for iterating over extraction progress
+     */
+    [Symbol.asyncIterator](): AsyncGenerator<ExtractionProgressData, undefined, unknown>;
+}
+/**
+ * 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 declare class MetadataStream extends Readable {
+    private renderingManager;
+    private startPage;
+    private endPage;
+    private _currentPage;
+    private _ended;
+    /**
+     * 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: any, startPage: number, endPage: number);
+    /**
+     * Implement _read() for readable stream
+     * @private
+     */
+    _read(): void;
+    /**
+     * Implement async iteration protocol for `for await...of` support
+     * @returns AsyncGenerator for iterating over page metadata
+     */
+    [Symbol.asyncIterator](): AsyncGenerator<PageMetadataData, undefined, unknown>;
+}
+/**
+ * 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 declare function createSearchStream(searchManager: any, searchTerm: string, options?: Record<string, any>): SearchStream;
+/**
+ * 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 declare function createExtractionStream(extractionManager: any, startPage: number, endPage: number, extractionType?: 'text' | 'markdown' | 'html', options?: Record<string, any>): ExtractionStream;
+/**
+ * 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 declare function createMetadataStream(renderingManager: any, startPage: number, endPage: number): MetadataStream;