pdf-oxide-fips 0.3.47

package/lib/builders/search-options-builder.js

@@ -0,0 +1,129 @@
+/**
+ * Builder for text search options
+ *
+ * Configures how text search is performed in PDF documents,
+ * including case sensitivity, whole word matching, and regex support.
+ *
+ * @example
+ * ```typescript
+ * import { SearchOptionsBuilder } from 'pdf_oxide';
+ *
+ * const options = SearchOptionsBuilder.create()
+ *   .caseSensitive(false)
+ *   .wholeWords(true)
+ *   .useRegex(false)
+ *   .build();
+ *
+ * const results = doc.search('pattern', 0, options);
+ * ```
+ */
+export class SearchOptionsBuilder {
+    /**
+     * Creates a new SearchOptionsBuilder instance
+     * @private
+     */
+    constructor() {
+        this._caseSensitive = false;
+        this._wholeWords = false;
+        this._useRegex = false;
+        this._ignoreAccents = false;
+        this._maxResults = 1000;
+        this._searchAnnotations = false;
+    }
+    /**
+     * Creates a new SearchOptionsBuilder instance
+     * @returns New builder instance
+     */
+    static create() {
+        return new SearchOptionsBuilder();
+    }
+    /**
+     * Creates options with default search settings (case-insensitive, no regex)
+     * @returns Search options with default preset
+     */
+    static default() {
+        return SearchOptionsBuilder.create().build();
+    }
+    /**
+     * Creates options with strict search settings (case-sensitive, whole words, no regex)
+     * @returns Search options with strict preset
+     */
+    static strict() {
+        return SearchOptionsBuilder.create()
+            .caseSensitive(true)
+            .wholeWords(true)
+            .useRegex(false)
+            .build();
+    }
+    /**
+     * Creates options with regex search settings
+     * @returns Search options with regex preset
+     */
+    static regex() {
+        return SearchOptionsBuilder.create()
+            .useRegex(true)
+            .caseSensitive(false)
+            .wholeWords(false)
+            .build();
+    }
+    caseSensitive(sensitive) {
+        if (typeof sensitive !== 'boolean') {
+            throw new Error('caseSensitive must be a boolean');
+        }
+        this._caseSensitive = sensitive;
+        return this;
+    }
+    wholeWords(wholeOnly) {
+        if (typeof wholeOnly !== 'boolean') {
+            throw new Error('wholeWords must be a boolean');
+        }
+        this._wholeWords = wholeOnly;
+        return this;
+    }
+    useRegex(regex) {
+        if (typeof regex !== 'boolean') {
+            throw new Error('useRegex must be a boolean');
+        }
+        this._useRegex = regex;
+        return this;
+    }
+    ignoreAccents(ignore) {
+        if (typeof ignore !== 'boolean') {
+            throw new Error('ignoreAccents must be a boolean');
+        }
+        this._ignoreAccents = ignore;
+        return this;
+    }
+    maxResults(max) {
+        if (typeof max !== 'number' || max <= 0) {
+            throw new Error('maxResults must be a positive number');
+        }
+        this._maxResults = Math.floor(max);
+        return this;
+    }
+    searchAnnotations(search) {
+        if (typeof search !== 'boolean') {
+            throw new Error('searchAnnotations must be a boolean');
+        }
+        this._searchAnnotations = search;
+        return this;
+    }
+    build() {
+        return {
+            caseSensitive: this._caseSensitive,
+            wholeWords: this._wholeWords,
+            useRegex: this._useRegex,
+            ignoreAccents: this._ignoreAccents,
+            maxResults: this._maxResults,
+            searchAnnotations: this._searchAnnotations,
+        };
+    }
+}
+/**
+ * Create a new SearchOptionsBuilder with static factory
+ * @deprecated Use SearchOptionsBuilder.create() instead
+ * @returns New builder instance
+ */
+export function createSearchOptionsBuilder() {
+    return SearchOptionsBuilder.create();
+}

package/lib/builders/streaming-table.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Streaming-table adapter backed by the native row-at-a-time FFI
+ * (`pdf_page_builder_streaming_table_begin_v2` / `_push_row` / `_finish`).
+ *
+ * @example
+ * ```typescript
+ * const t = page.streamingTable({
+ *   columns: [
+ *     { header: 'SKU',  width: 72 },
+ *     { header: 'Item', width: 200 },
+ *     { header: 'Qty',  width: 48, align: Align.Right },
+ *   ],
+ *   repeatHeader: true,
+ *   mode: { kind: 'sample', sampleRows: 30 },
+ * });
+ * for await (const row of readRowsFromDb()) {
+ *   t.pushRow([row.sku, row.item, String(row.qty)]);
+ * }
+ * await t.finish();
+ * ```
+ */
+import type { SpanCell, StreamingTableConfig } from '../types/common.js';
+import type { PageBuilder } from './document-builder.js';
+export declare class StreamingTable {
+    private _page;
+    private _columns;
+    private _opened;
+    private _finished;
+    private _rowCount;
+    /** @internal — constructed via `PageBuilder.streamingTable(...)`. */
+    constructor(page: PageBuilder, config: StreamingTableConfig);
+    /**
+     * Number of rows pushed since the last batch boundary.
+     * Backed by the Rust FFI layer.
+     */
+    get pendingRowCount(): number;
+    /** Number of complete batches recorded by the native layer so far. */
+    get batchCount(): number;
+    /**
+     * Explicitly mark a batch boundary in the native layer.
+     * Also triggered automatically when the configured batch size is reached.
+     */
+    flush(): this;
+    /** Total rows pushed so far (monotonically increasing). */
+    get rowCount(): number;
+    /** Push a single row (all rowspan=1). Throws if `cells.length !== columns.length`. */
+    pushRow(cells: Array<string | null | undefined>): this;
+    /**
+     * Push a single row with per-cell rowspan values. Each element is either
+     * a `SpanCell` (`{ text, rowspan }`) or a plain string (rowspan=1).
+     * Requires `maxRowspan ≥ 2` in the `StreamingTableConfig`.
+     */
+    pushRowSpan(cells: Array<SpanCell | string | null | undefined>): this;
+    /**
+     * Convenience: consume a sync or async iterable and push each row.
+     */
+    pushAll(rows: Iterable<Array<string | null | undefined>> | AsyncIterable<Array<string | null | undefined>>): Promise<this>;
+    /**
+     * Close the streaming table and return the parent PageBuilder for chaining.
+     */
+    finish(): Promise<PageBuilder>;
+    /** Number of the columns this table was opened with. */
+    get columnCount(): number;
+}

package/lib/builders/streaming-table.js

@@ -0,0 +1,140 @@
+/**
+ * Streaming-table adapter backed by the native row-at-a-time FFI
+ * (`pdf_page_builder_streaming_table_begin_v2` / `_push_row` / `_finish`).
+ *
+ * @example
+ * ```typescript
+ * const t = page.streamingTable({
+ *   columns: [
+ *     { header: 'SKU',  width: 72 },
+ *     { header: 'Item', width: 200 },
+ *     { header: 'Qty',  width: 48, align: Align.Right },
+ *   ],
+ *   repeatHeader: true,
+ *   mode: { kind: 'sample', sampleRows: 30 },
+ * });
+ * for await (const row of readRowsFromDb()) {
+ *   t.pushRow([row.sku, row.item, String(row.qty)]);
+ * }
+ * await t.finish();
+ * ```
+ */
+export class StreamingTable {
+    /** @internal — constructed via `PageBuilder.streamingTable(...)`. */
+    constructor(page, config) {
+        this._opened = false;
+        this._finished = false;
+        this._rowCount = 0;
+        if (!config || !Array.isArray(config.columns) || config.columns.length === 0) {
+            throw new Error('StreamingTable requires at least one column');
+        }
+        this._page = page;
+        this._columns = config.columns;
+        const headers = config.columns.map((c) => c.header ?? '');
+        const widths = config.columns.map((c) => c.width);
+        const aligns = config.columns.map((c) => (c.align ?? 0));
+        const repeat = config.repeatHeader !== false;
+        const maxRowspan = config.maxRowspan != null && config.maxRowspan >= 2 ? config.maxRowspan : 1;
+        this._page._streamingTableBeginV2(headers, widths, aligns, repeat, config.mode, maxRowspan);
+        this._opened = true;
+        const batchSize = config.batchSize != null && config.batchSize > 0 ? config.batchSize : 256;
+        this._page._streamingTableSetBatchSize(batchSize);
+    }
+    /**
+     * Number of rows pushed since the last batch boundary.
+     * Backed by the Rust FFI layer.
+     */
+    get pendingRowCount() {
+        return this._page._streamingTablePendingRowCount();
+    }
+    /** Number of complete batches recorded by the native layer so far. */
+    get batchCount() {
+        return this._page._streamingTableBatchCount();
+    }
+    /**
+     * Explicitly mark a batch boundary in the native layer.
+     * Also triggered automatically when the configured batch size is reached.
+     */
+    flush() {
+        if (this._finished)
+            throw new Error('StreamingTable already finished');
+        this._page._streamingTableFlush();
+        return this;
+    }
+    /** Total rows pushed so far (monotonically increasing). */
+    get rowCount() {
+        return this._rowCount;
+    }
+    /** Push a single row (all rowspan=1). Throws if `cells.length !== columns.length`. */
+    pushRow(cells) {
+        if (this._finished) {
+            throw new Error('StreamingTable already finished');
+        }
+        if (cells.length !== this._columns.length) {
+            throw new Error(`row width ${cells.length} does not match column count ${this._columns.length}`);
+        }
+        this._page._streamingTablePushRow(cells.map((c) => (c == null ? null : String(c))));
+        this._rowCount++;
+        return this;
+    }
+    /**
+     * Push a single row with per-cell rowspan values. Each element is either
+     * a `SpanCell` (`{ text, rowspan }`) or a plain string (rowspan=1).
+     * Requires `maxRowspan ≥ 2` in the `StreamingTableConfig`.
+     */
+    pushRowSpan(cells) {
+        if (this._finished) {
+            throw new Error('StreamingTable already finished');
+        }
+        if (cells.length !== this._columns.length) {
+            throw new Error(`row width ${cells.length} does not match column count ${this._columns.length}`);
+        }
+        const normalized = cells.map((c) => {
+            if (c == null)
+                return [null, 1];
+            if (typeof c === 'string')
+                return [c, 1];
+            return [c.text, c.rowspan];
+        });
+        this._page._streamingTablePushRowV2(normalized);
+        this._rowCount++;
+        return this;
+    }
+    /**
+     * Convenience: consume a sync or async iterable and push each row.
+     */
+    async pushAll(rows) {
+        if (this._finished) {
+            throw new Error('StreamingTable already finished');
+        }
+        const anyRows = rows;
+        if (typeof anyRows[Symbol.asyncIterator] === 'function') {
+            for await (const row of rows) {
+                this.pushRow(row);
+            }
+        }
+        else {
+            for (const row of rows) {
+                this.pushRow(row);
+            }
+        }
+        return this;
+    }
+    /**
+     * Close the streaming table and return the parent PageBuilder for chaining.
+     */
+    async finish() {
+        if (this._finished) {
+            throw new Error('StreamingTable already finished');
+        }
+        this._finished = true;
+        if (this._opened) {
+            this._page._streamingTableFinish();
+        }
+        return this._page;
+    }
+    /** Number of the columns this table was opened with. */
+    get columnCount() {
+        return this._columns.length;
+    }
+}

package/lib/document-editor-manager.d.ts

@@ -0,0 +1,139 @@
+/**
+ * DocumentEditorManager for PDF document editing operations
+ *
+ * Provides methods to edit and modify PDF documents including page operations,
+ * content manipulation, and document merging. API is consistent with Python,
+ * Java, C#, Go, and Swift implementations.
+ */
+import { EventEmitter } from 'events';
+/**
+ * Page rotation options
+ */
+export declare enum PageRotation {
+    None = 0,
+    Rotate90 = 90,
+    Rotate180 = 180,
+    Rotate270 = 270
+}
+/**
+ * Configuration for page insertion
+ */
+export interface InsertConfig {
+    pageIndex: number;
+    width?: number;
+    height?: number;
+    content?: Buffer;
+}
+/**
+ * Configuration for page extraction
+ */
+export interface ExtractConfig {
+    startPage: number;
+    endPage: number;
+    outputPath?: string;
+}
+/**
+ * Configuration for document merging
+ */
+export interface MergeConfig {
+    documents: any[];
+    outputPath?: string;
+    preserveOutlines?: boolean;
+    preserveAnnotations?: boolean;
+}
+/**
+ * Edit operation record
+ */
+export interface EditOperation {
+    type: string;
+    timestamp: Date;
+    details: Record<string, any>;
+}
+/**
+ * Document Editor Manager for document manipulation
+ *
+ * Provides methods to:
+ * - Delete, insert, and reorder pages
+ * - Rotate pages
+ * - Extract page ranges to new documents
+ * - Merge multiple documents
+ * - Track edit history
+ */
+export declare class DocumentEditorManager extends EventEmitter {
+    private document;
+    private editHistory;
+    private hasUnsavedChanges;
+    constructor(document: any);
+    /**
+     * Deletes a page from the document
+     * Matches: Python deletePage(), Java deletePage(), C# DeletePage()
+     */
+    deletePage(pageIndex: number): Promise<void>;
+    /**
+     * Deletes multiple pages from the document
+     * Matches: Python deletePages(), Java deletePages(), C# DeletePages()
+     */
+    deletePages(pageIndices: number[]): Promise<void>;
+    /**
+     * Inserts a blank page at the specified position
+     * Matches: Python insertBlankPage(), Java insertBlankPage(), C# InsertBlankPage()
+     */
+    insertBlankPage(pageIndex: number, width?: number, height?: number): Promise<void>;
+    /**
+     * Rotates a page by the specified angle
+     * Matches: Python rotatePage(), Java rotatePage(), C# RotatePage()
+     */
+    rotatePage(pageIndex: number, rotation: PageRotation): Promise<void>;
+    /**
+     * Rotates multiple pages
+     * Matches: Python rotatePages(), Java rotatePages(), C# RotatePages()
+     */
+    rotatePages(pageIndices: number[], rotation: PageRotation): Promise<void>;
+    /**
+     * Moves a page to a new position
+     * Matches: Python movePage(), Java movePage(), C# MovePage()
+     */
+    movePage(fromIndex: number, toIndex: number): Promise<void>;
+    /**
+     * Extracts pages to a new document
+     * Matches: Python extractPages(), Java extractPages(), C# ExtractPages()
+     */
+    extractPages(config: ExtractConfig): Promise<any>;
+    /**
+     * Merges multiple documents into one
+     * Matches: Python mergeDocuments(), Java mergeDocuments(), C# MergeDocuments()
+     */
+    static mergeDocuments(config: MergeConfig): Promise<any>;
+    /**
+     * Saves the document with all modifications
+     * Matches: Python save(), Java save(), C# Save()
+     */
+    save(outputPath?: string): Promise<void>;
+    /**
+     * Gets the edit history
+     * Matches: Python getEditHistory(), Java getEditHistory(), C# GetEditHistory()
+     */
+    getEditHistory(): EditOperation[];
+    /**
+     * Checks if there are unsaved changes
+     * Matches: Python hasUnsavedChanges(), Java hasUnsavedChanges(), C# HasUnsavedChanges()
+     */
+    hasChanges(): boolean;
+    /**
+     * Undoes the last operation (if supported)
+     * Matches: Python undo(), Java undo(), C# Undo()
+     */
+    undo(): Promise<boolean>;
+    /**
+     * Clears the edit history
+     * Matches: Python clearHistory(), Java clearHistory(), C# ClearHistory()
+     */
+    clearHistory(): void;
+    /**
+     * Gets the page count after modifications
+     */
+    getPageCount(): number;
+    private validatePageIndex;
+    private recordOperation;
+}
+export default DocumentEditorManager;