pdf-oxide-fips 0.3.47

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

@@ -0,0 +1,246 @@
+/**
+ * Manager for content extraction from PDF documents
+ *
+ * Caching is handled automatically at the Rust FFI layer, eliminating
+ * the need for duplicate cache implementations in the binding.
+ *
+ * @example
+ * ```typescript
+ * import { ExtractionManager, ConversionOptionsBuilder } from 'pdf_oxide';
+ *
+ * const doc = PdfDocument.open('document.pdf');
+ * const extractionManager = new ExtractionManager(doc);
+ *
+ * // Extract text from a single page
+ * const text = extractionManager.extractText(0);
+ * console.log(text);
+ *
+ * // Extract all text
+ * const allText = extractionManager.extractAllText();
+ *
+ * // Extract with custom options
+ * const options = ConversionOptionsBuilder.highQuality().build();
+ * const markdown = extractionManager.extractMarkdown(0, options);
+ * ```
+ */
+export interface ContentStatistics {
+    pageCount: number;
+    wordCount: number;
+    characterCount: number;
+    averageWordsPerPage: number;
+    averageCharactersPerPage: number;
+}
+export interface SearchMatch {
+    pageIndex: number;
+    pageNumber: number;
+    matchIndex: number;
+    snippet: string;
+    matchText: string;
+}
+export declare class ExtractionManager {
+    private _document;
+    /**
+     * Creates a new ExtractionManager for the given document
+     * @param document - The PDF document
+     * @throws Error if document is null or undefined
+     */
+    constructor(document: any);
+    /**
+     * Extracts text from a single page.
+     *
+     * The native layer produces UTF-8 bytes, which Node decodes into a JS
+     * `string` (UTF-16 code units internally). As a result,
+     * `text.length` reports UTF-16 code units, not bytes — so a 648-byte
+     * UTF-8 string containing two accented letters reads as 646 in JS. Use
+     * `Buffer.byteLength(text, 'utf8')` if you need the byte count (e.g. to
+     * compare against Go's `len(string)` or Rust's `String::len()`).
+     *
+     * Results are automatically cached at the FFI layer.
+     *
+     * @param pageIndex - Zero-based page index
+     * @param options - Conversion options
+     * @returns Extracted text (UTF-16 code units)
+     * @throws Error if page index is invalid
+     *
+     * @example
+     * ```typescript
+     * const text = manager.extractText(0);
+     * console.log(`Page 1: ${text.length} UTF-16 code units`);
+     * console.log(`         ${Buffer.byteLength(text, 'utf8')} UTF-8 bytes`);
+     * ```
+     */
+    extractText(pageIndex: number, options?: Record<string, any>): string;
+    /**
+     * Extracts text from all pages
+     * @param options - Conversion options
+     * @returns All extracted text concatenated
+     *
+     * @example
+     * ```typescript
+     * const allText = manager.extractAllText();
+     * console.log(`Total characters: ${allText.length}`);
+     * ```
+     */
+    extractAllText(options?: Record<string, any>): string;
+    /**
+     * Extracts text from a range of pages
+     * @param startPageIndex - Zero-based start page index
+     * @param endPageIndex - Zero-based end page index (inclusive)
+     * @param options - Conversion options
+     * @returns Extracted text from pages in range
+     *
+     * @example
+     * ```typescript
+     * const text = manager.extractTextRange(0, 10);
+     * console.log(`Text from pages 1-11: ${text}`);
+     * ```
+     */
+    extractTextRange(startPageIndex: number, endPageIndex: number, options?: Record<string, any>): string;
+    /**
+     * Extracts text from specific page indices (non-contiguous)
+     * @param pageIndices - Array of zero-based page indices
+     * @param options - Conversion options
+     * @returns Extracted text from specified pages concatenated with newlines
+     * @throws Error if page indices are invalid
+     *
+     * @example
+     * ```typescript
+     * const text = manager.extractTextBatch([0, 2, 5]); // Extract pages 1, 3, 6
+     * console.log(text);
+     * ```
+     */
+    extractTextBatch(pageIndices: number[], options?: Record<string, any>): string;
+    /**
+     * Extracts text from pages as an array (one entry per page)
+     * @param startPageIndex - Zero-based start page index
+     * @param endPageIndex - Zero-based end page index (inclusive)
+     * @param options - Conversion options
+     * @returns Array of extracted text, one per page
+     *
+     * @example
+     * ```typescript
+     * const pages = manager.extractTextArray(0, 5);
+     * pages.forEach((text, i) => console.log(`Page ${i}: ${text.length} chars`));
+     * ```
+     */
+    extractTextArray(startPageIndex: number, endPageIndex: number, options?: Record<string, any>): string[];
+    /**
+     * Extracts page as Markdown.
+     * Results are automatically cached at the FFI layer.
+     * @param pageIndex - Zero-based page index
+     * @param options - Conversion options
+     * @returns Page content as Markdown
+     * @throws Error if page index is invalid
+     *
+     * @example
+     * ```typescript
+     * const markdown = manager.extractMarkdown(0);
+     * console.log(markdown); // Markdown formatted content
+     * ```
+     */
+    extractMarkdown(pageIndex: number, options?: Record<string, any>): string;
+    /**
+     * Extracts all pages as Markdown
+     * @param options - Conversion options
+     * @returns All pages as Markdown
+     *
+     * @example
+     * ```typescript
+     * const markdown = manager.extractAllMarkdown();
+     * // Write to file
+     * fs.writeFileSync('output.md', markdown);
+     * ```
+     */
+    extractAllMarkdown(options?: Record<string, any>): string;
+    /**
+     * Extracts markdown from a range of pages
+     * @param startPageIndex - Zero-based start page index
+     * @param endPageIndex - Zero-based end page index (inclusive)
+     * @param options - Conversion options
+     * @returns Extracted markdown from pages in range
+     */
+    extractMarkdownRange(startPageIndex: number, endPageIndex: number, options?: Record<string, any>): string;
+    /**
+     * Gets word count for a page
+     * @param pageIndex - Zero-based page index
+     * @returns Estimated word count
+     */
+    getPageWordCount(pageIndex: number): number;
+    /**
+     * Gets total word count for all pages
+     * @returns Total word count across all pages
+     */
+    getTotalWordCount(): number;
+    /**
+     * Gets character count for a page
+     * @param pageIndex - Zero-based page index
+     * @returns Character count (including whitespace)
+     */
+    getPageCharacterCount(pageIndex: number): number;
+    /**
+     * Gets total character count for all pages
+     * @returns Total character count
+     */
+    getTotalCharacterCount(): number;
+    /**
+     * Gets line count for a page
+     * @param pageIndex - Zero-based page index
+     * @returns Estimated line count
+     */
+    getPageLineCount(pageIndex: number): number;
+    /**
+     * Gets statistics for extracted content
+     * @returns Content statistics object
+     *
+     * @example
+     * ```typescript
+     * const stats = manager.getContentStatistics();
+     * console.log(`Total pages: ${stats.pageCount}`);
+     * console.log(`Total words: ${stats.wordCount}`);
+     * console.log(`Average page length: ${stats.averagePageLength}`);
+     * ```
+     */
+    getContentStatistics(): ContentStatistics;
+    /**
+     * Searches for text across all pages and returns matching snippets
+     * @param searchText - Text to search for
+     * @param contextLength - Characters of context around match
+     * @returns Array of match objects with page and snippet
+     *
+     * @example
+     * ```typescript
+     * const matches = manager.searchContent('keyword', 50);
+     * matches.forEach(match => {
+     *   console.log(`Page ${match.pageIndex + 1}: ...${match.snippet}...`);
+     * });
+     * ```
+     */
+    searchContent(searchText: string, contextLength?: number): SearchMatch[];
+    /**
+     * Extract text from a page in a worker thread (non-blocking)
+     * @param documentPath - Path to the PDF document
+     * @param pageIndex - Page index to extract from
+     * @param options - Optional extraction options
+     * @param timeout - Optional timeout in milliseconds
+     * @returns Promise resolving to extracted text
+     */
+    extractTextInWorker(documentPath: string, pageIndex: number, options?: Record<string, any>, timeout?: number): Promise<string>;
+    /**
+     * Extract markdown from a page in a worker thread (non-blocking)
+     * @param documentPath - Path to the PDF document
+     * @param pageIndex - Page index to extract from
+     * @param options - Optional extraction options
+     * @param timeout - Optional timeout in milliseconds
+     * @returns Promise resolving to extracted markdown
+     */
+    extractMarkdownInWorker(documentPath: string, pageIndex: number, options?: Record<string, any>, timeout?: number): Promise<string>;
+    /**
+     * Extract HTML from a page in a worker thread (non-blocking)
+     * @param documentPath - Path to the PDF document
+     * @param pageIndex - Page index to extract from
+     * @param options - Optional extraction options
+     * @param timeout - Optional timeout in milliseconds
+     * @returns Promise resolving to extracted HTML
+     */
+    extractHtmlInWorker(documentPath: string, pageIndex: number, options?: Record<string, any>, timeout?: number): Promise<string>;
+}