pdf-oxide-fips 0.3.47

package/lib/types/common.d.ts

@@ -0,0 +1,189 @@
+/**
+ * Common type definitions and utilities
+ */
+/** A table extracted from a PDF page. */
+export interface Table {
+    /** Number of rows. */
+    rows: number;
+    /** Number of columns. */
+    cols: number;
+    /** True if the first row is a header row. */
+    hasHeader: boolean;
+    /** Cell text: cells[row][col]. Individual cells may be `null` when the
+     *  native binding has no text for that position (missing cell, decoding
+     *  failure, etc.). */
+    cells: (string | null)[][];
+}
+export type { Annotation, CircleAnnotation, Color, DocumentInfo, EmbeddedFile, HighlightAnnotation, InkAnnotation, LineAnnotation, LinkAnnotation, Metadata, NativePdf, NativePdfDocument, NativePdfPage, PdfElement, PdfImage, PdfPath, PdfTable, PdfTableCell, PdfText, Point, PolygonAnnotation, Rect, SearchOptions, SearchResult, SquareAnnotation, TextAnnotation, } from './native-bindings';
+/**
+ * Page range specification for document operations
+ */
+export interface PageRange {
+    startPage?: number;
+    endPage?: number;
+    pages?: number[];
+}
+/**
+ * Generic extraction result with metadata
+ */
+export interface ExtractionResult<T> {
+    data: T;
+    pageIndex: number;
+    timestamp: Date;
+    processingTimeMs?: number;
+}
+/**
+ * Async operation callback function type
+ */
+export type AsyncOperationCallback<T> = (err: Error | null, result?: T) => void;
+/**
+ * Manager configuration interface for all managers
+ */
+export interface ManagerConfig {
+    maxCacheSize?: number;
+    cacheExpirationMs?: number;
+    enableCaching?: boolean;
+    timeout?: number;
+    retryAttempts?: number;
+    retryDelayMs?: number;
+}
+/**
+ * Batch operation options
+ */
+export interface BatchOptions {
+    batchSize?: number;
+    parallel?: boolean;
+    maxParallel?: number;
+    progressCallback?: (processed: number, total: number) => void;
+    continueOnError?: boolean;
+}
+/**
+ * Error details for exception context
+ */
+export interface PdfErrorDetails {
+    timestamp?: string;
+    operation?: string;
+    context?: Record<string, any>;
+    originalError?: Error;
+    stack?: string;
+}
+/**
+ * Optional content (layers) information
+ */
+export interface OptionalContent {
+    id: string;
+    name: string;
+    visible: boolean;
+    locked?: boolean;
+    printable?: boolean;
+    exportable?: boolean;
+    viewState?: string;
+}
+/**
+ * Form field value map for filling forms
+ */
+export type FormFieldValues = Record<string, string | number | boolean | string[]>;
+/**
+ * Type for validation result
+ */
+export interface ValidationResult {
+    isValid: boolean;
+    errors: string[];
+    warnings: string[];
+}
+/**
+ * Stream operation callback
+ */
+export type StreamCallback<T> = (data: T) => void;
+/**
+ * Stream error callback
+ */
+export type StreamErrorCallback = (error: Error) => void;
+/**
+ * Stream end callback
+ */
+export type StreamEndCallback = () => void;
+/**
+ * Horizontal alignment for wrapped text and table cells.
+ * Matches the C FFI integer encoding used by
+ * `pdf_page_builder_text_in_rect` and `pdf_page_builder_table`.
+ */
+export declare enum Align {
+    Left = 0,
+    Center = 1,
+    Right = 2
+}
+/**
+ * Column descriptor for {@link TableSpec} / {@link StreamingTableConfig}.
+ */
+export interface Column {
+    /** Header label rendered in bold (used only when `hasHeader`/`repeatHeader`). */
+    header: string;
+    /** Column width in PDF points. */
+    width: number;
+    /** Cell alignment (default {@link Align.Left}). */
+    align?: Align;
+}
+/**
+ * Buffered-table spec passed to `PageBuilder.table(...)`.
+ *
+ * All rows are held in JS memory and flushed to the native
+ * `pdf_page_builder_table` call in a single step.
+ */
+export interface TableSpec {
+    /** Column layout — widths, alignments, and header labels. */
+    columns: Column[];
+    /** Body rows, each row has `columns.length` cells (nullable = empty). */
+    rows: Array<Array<string | null | undefined>>;
+    /** Promote the column headers to a styled first row. Defaults to true. */
+    hasHeader?: boolean;
+}
+/**
+ * Column-sizing strategy for streaming tables (issue #400).
+ *
+ * - `fixed` — use the `width` from each `Column` as-is (default).
+ * - `sample` — buffer the first N rows, measure content, then freeze
+ *   column widths automatically.  Supply `sampleRows`, `minColWidth`,
+ *   and `maxColWidth` to tune.
+ */
+export type TableMode = {
+    kind: 'fixed';
+} | {
+    kind: 'sample';
+    sampleRows?: number;
+    minColWidthPt?: number;
+    maxColWidthPt?: number;
+};
+/**
+ * Configuration for the managed streaming-table adapter.
+ */
+export interface StreamingTableConfig {
+    /** Column layout — widths, alignments, and header labels. */
+    columns: Column[];
+    /**
+     * Whether to repeat the header row on every page break. Defaults to true.
+     */
+    repeatHeader?: boolean;
+    /**
+     * Column-sizing mode. Defaults to `{ kind: 'fixed' }`.
+     */
+    mode?: TableMode;
+    /**
+     * Maximum rowspan a cell may carry.  0 or 1 (default) disables rowspan.
+     * Set to ≥2 to allow `pushRowSpan` cells to span multiple rows.
+     */
+    maxRowspan?: number;
+    /**
+     * Maximum rows to buffer before an automatic batch flush in the native
+     * layer. 0 or unset defaults to 256.
+     */
+    batchSize?: number;
+}
+/**
+ * A single cell value for `StreamingTable.pushRowSpan`.
+ * `rowspan == 1` is equivalent to a normal cell.
+ */
+export interface SpanCell {
+    text: string;
+    rowspan: number;
+}

package/lib/types/common.js

@@ -0,0 +1,17 @@
+/**
+ * Common type definitions and utilities
+ */
+// ============================================================================
+// DocumentBuilder — table primitives (v0.3.39, issue #393)
+// ============================================================================
+/**
+ * Horizontal alignment for wrapped text and table cells.
+ * Matches the C FFI integer encoding used by
+ * `pdf_page_builder_text_in_rect` and `pdf_page_builder_table`.
+ */
+export var Align;
+(function (Align) {
+    Align[Align["Left"] = 0] = "Left";
+    Align[Align["Center"] = 1] = "Center";
+    Align[Align["Right"] = 2] = "Right";
+})(Align || (Align = {}));

package/lib/types/document-types.d.ts

@@ -0,0 +1,352 @@
+/**
+ * PdfDocument - TypeScript type definitions for pdf_oxide
+ *
+ * Provides complete type definitions for the PdfDocument class and related types.
+ * These types ensure type safety when using the pdf_oxide library in TypeScript.
+ *
+ * @example
+ * ```typescript
+ * import { PdfDocument } from 'pdf_oxide';
+ *
+ * const doc = await PdfDocument.open('document.pdf');
+ * const pageCount = await doc.pageCount();
+ * const text = await doc.extractText(0);
+ * ```
+ */
+/**
+ * Represents a rectangle in PDF coordinate space (origin at bottom-left)
+ */
+export interface Rect {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+/**
+ * Represents a point in PDF coordinate space
+ */
+export interface Point {
+    readonly x: number;
+    readonly y: number;
+}
+/**
+ * Represents a color (RGBA)
+ */
+export interface Color {
+    readonly r: number;
+    readonly g: number;
+    readonly b: number;
+    readonly a?: number;
+}
+/**
+ * Standard page sizes
+ */
+export declare enum PageSizeType {
+    LETTER = "letter",
+    LEGAL = "legal",
+    A4 = "a4",
+    A3 = "a3",
+    A5 = "a5",
+    B4 = "b4",
+    TABLOID = "tabloid"
+}
+/**
+ * Page size dimensions
+ */
+export interface PageSize {
+    readonly type?: PageSizeType;
+    readonly width: number;
+    readonly height: number;
+}
+/**
+ * PDF document metadata
+ */
+export interface DocumentMetadata {
+    readonly title?: string;
+    readonly author?: string;
+    readonly subject?: string;
+    readonly keywords?: string;
+    readonly creator?: string;
+    readonly producer?: string;
+    readonly creationDate?: Date;
+    readonly modificationDate?: Date;
+    readonly pageCount: number;
+    readonly format?: string;
+    readonly version?: string;
+    readonly isEncrypted?: boolean;
+    readonly hasXfa?: boolean;
+}
+/**
+ * Form field type enumeration
+ */
+export declare enum FormFieldType {
+    TEXT = "text",
+    CHECKBOX = "checkbox",
+    RADIO = "radio",
+    COMBOBOX = "combobox",
+    LISTBOX = "listbox",
+    SIGNATURE = "signature",
+    DATE = "date",
+    BUTTON = "button"
+}
+/**
+ * Form field information
+ */
+export interface FormField {
+    readonly name: string;
+    readonly type: FormFieldType;
+    readonly value: string;
+    readonly pageIndex: number;
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+    readonly required?: boolean;
+    readonly readonly?: boolean;
+}
+/**
+ * Text content on a page
+ */
+export interface TextContent {
+    readonly text: string;
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+    readonly fontName?: string;
+    readonly fontSize?: number;
+    readonly confidence?: number;
+}
+/**
+ * Image content on a page
+ */
+export interface ImageContent {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+    readonly imageType?: string;
+    readonly bitsPerComponent?: number;
+    readonly colorSpace?: string;
+}
+/**
+ * Annotation type enumeration
+ */
+export declare enum AnnotationType {
+    TEXT = "text",
+    LINK = "link",
+    HIGHLIGHT = "highlight",
+    UNDERLINE = "underline",
+    STRIKEOUT = "strikeout",
+    SQUIGGLY = "squiggly",
+    STAMP = "stamp",
+    CARET = "caret",
+    INK = "ink",
+    POPUP = "popup",
+    FILE_ATTACHMENT = "file_attachment",
+    SOUND = "sound",
+    MOVIE = "movie",
+    WIDGET = "widget",
+    SCREEN = "screen",
+    PRINTER_MARK = "printer_mark",
+    TRAP_NET = "trap_net",
+    WATERMARK = "watermark",
+    REDACT = "redact"
+}
+/**
+ * Annotation information
+ */
+export interface Annotation {
+    readonly type: AnnotationType;
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+    readonly contents?: string;
+    readonly author?: string;
+    readonly creationDate?: Date;
+    readonly modificationDate?: Date;
+    readonly color?: Color;
+}
+/**
+ * Search options
+ */
+export interface SearchOptions {
+    readonly caseSensitive?: boolean;
+    readonly wholeWord?: boolean;
+    readonly regex?: boolean;
+    readonly maxResults?: number;
+    readonly pageRange?: {
+        start: number;
+        end: number;
+    };
+}
+/**
+ * Search result
+ */
+export interface SearchResult {
+    readonly pageIndex: number;
+    readonly text: string;
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+    readonly context?: string;
+}
+/**
+ * Markdown conversion options
+ */
+export interface MarkdownOptions {
+    readonly includeImages?: boolean;
+    readonly includeLinks?: boolean;
+    readonly preserveLayout?: boolean;
+    readonly pageRange?: {
+        start: number;
+        end: number;
+    };
+}
+/**
+ * HTML conversion options
+ */
+export interface HtmlOptions {
+    readonly includeStyles?: boolean;
+    readonly includeImages?: boolean;
+    readonly embedImages?: boolean;
+    readonly pageRange?: {
+        start: number;
+        end: number;
+    };
+}
+/**
+ * Represents a single page in a PDF document
+ */
+export interface PdfPage {
+    readonly index: number;
+    readonly width: number;
+    readonly height: number;
+    readonly rotation: number;
+    readonly mediaBox: Rect;
+    readonly cropBox?: Rect;
+    readonly bleedBox?: Rect;
+    readonly trimBox?: Rect;
+    readonly artBox?: Rect;
+}
+/**
+ * Main PDF document class
+ *
+ * Provides access to PDF document content, metadata, and structure.
+ * All operations are async to support non-blocking I/O.
+ *
+ * @example
+ * ```typescript
+ * // Open a document
+ * const doc = await PdfDocument.open('file.pdf');
+ *
+ * // Get page count
+ * const pages = await doc.pageCount();
+ *
+ * // Extract text from first page
+ * const text = await doc.extractText(0);
+ *
+ * // Get metadata
+ * const metadata = await doc.getMetadata();
+ *
+ * // Convert to markdown
+ * const markdown = await doc.toMarkdown();
+ * ```
+ */
+export interface PdfDocument {
+    /**
+     * Open a PDF document from a file path
+     */
+    /**
+     * Open a PDF document from a buffer
+     */
+    /**
+     * Get the number of pages in the document
+     */
+    pageCount(): Promise<number>;
+    /**
+     * Get document metadata
+     */
+    getMetadata(): Promise<DocumentMetadata>;
+    /**
+     * Get page information
+     */
+    getPage(pageIndex: number): Promise<PdfPage>;
+    /**
+     * Extract text from a specific page
+     */
+    extractText(pageIndex: number): Promise<string>;
+    /**
+     * Extract text from a range of pages
+     */
+    extractTextRange(startPage: number, endPage: number): Promise<string[]>;
+    /**
+     * Extract all text from the document
+     */
+    extractAllText(): Promise<string>;
+    /**
+     * Get all form fields in the document
+     */
+    extractFormFields(): Promise<FormField[]>;
+    /**
+     * Get form field by name
+     */
+    getFormField(fieldName: string): Promise<FormField | undefined>;
+    /**
+     * Set form field value
+     */
+    setFormFieldValue(fieldName: string, value: string): Promise<boolean>;
+    /**
+     * Get annotations on a specific page
+     */
+    getAnnotations(pageIndex: number): Promise<Annotation[]>;
+    /**
+     * Get all annotations in the document
+     */
+    getAllAnnotations(): Promise<Annotation[]>;
+    /**
+     * Search for text in the document
+     */
+    search(query: string, options?: SearchOptions): Promise<SearchResult[]>;
+    /**
+     * Convert document to markdown
+     */
+    toMarkdown(options?: MarkdownOptions): Promise<string>;
+    /**
+     * Convert document to HTML
+     */
+    toHtml(options?: HtmlOptions): Promise<string>;
+    /**
+     * Close the document and release resources
+     */
+    close(): Promise<void>;
+    /**
+     * Check if document is open
+     */
+    isOpen(): boolean;
+}
+/**
+ * PdfDocument static methods (factory pattern)
+ */
+export interface PdfDocumentStatic {
+    /**
+     * Open a PDF document from a file path
+     */
+    open(path: string, password?: string): Promise<PdfDocument>;
+    /**
+     * Open a PDF document from a buffer
+     */
+    openBuffer(buffer: Buffer, password?: string): Promise<PdfDocument>;
+    /**
+     * Create a new empty PDF document
+     */
+    create(): Promise<PdfDocument>;
+}
+/**
+ * Re-export PdfDocument from the main nodejs module
+ * This provides the actual implementation with full type safety
+ */
+export { PdfDocument } from '../index.js';
+export default PdfDocument;

package/lib/types/document-types.js

@@ -0,0 +1,82 @@
+/**
+ * PdfDocument - TypeScript type definitions for pdf_oxide
+ *
+ * Provides complete type definitions for the PdfDocument class and related types.
+ * These types ensure type safety when using the pdf_oxide library in TypeScript.
+ *
+ * @example
+ * ```typescript
+ * import { PdfDocument } from 'pdf_oxide';
+ *
+ * const doc = await PdfDocument.open('document.pdf');
+ * const pageCount = await doc.pageCount();
+ * const text = await doc.extractText(0);
+ * ```
+ */
+/**
+ * Standard page sizes
+ */
+export var PageSizeType;
+(function (PageSizeType) {
+    PageSizeType["LETTER"] = "letter";
+    PageSizeType["LEGAL"] = "legal";
+    PageSizeType["A4"] = "a4";
+    PageSizeType["A3"] = "a3";
+    PageSizeType["A5"] = "a5";
+    PageSizeType["B4"] = "b4";
+    PageSizeType["TABLOID"] = "tabloid";
+})(PageSizeType || (PageSizeType = {}));
+// ============================================================================
+// Form Fields
+// ============================================================================
+/**
+ * Form field type enumeration
+ */
+export var FormFieldType;
+(function (FormFieldType) {
+    FormFieldType["TEXT"] = "text";
+    FormFieldType["CHECKBOX"] = "checkbox";
+    FormFieldType["RADIO"] = "radio";
+    FormFieldType["COMBOBOX"] = "combobox";
+    FormFieldType["LISTBOX"] = "listbox";
+    FormFieldType["SIGNATURE"] = "signature";
+    FormFieldType["DATE"] = "date";
+    FormFieldType["BUTTON"] = "button";
+})(FormFieldType || (FormFieldType = {}));
+// ============================================================================
+// Annotations
+// ============================================================================
+/**
+ * Annotation type enumeration
+ */
+export var AnnotationType;
+(function (AnnotationType) {
+    AnnotationType["TEXT"] = "text";
+    AnnotationType["LINK"] = "link";
+    AnnotationType["HIGHLIGHT"] = "highlight";
+    AnnotationType["UNDERLINE"] = "underline";
+    AnnotationType["STRIKEOUT"] = "strikeout";
+    AnnotationType["SQUIGGLY"] = "squiggly";
+    AnnotationType["STAMP"] = "stamp";
+    AnnotationType["CARET"] = "caret";
+    AnnotationType["INK"] = "ink";
+    AnnotationType["POPUP"] = "popup";
+    AnnotationType["FILE_ATTACHMENT"] = "file_attachment";
+    AnnotationType["SOUND"] = "sound";
+    AnnotationType["MOVIE"] = "movie";
+    AnnotationType["WIDGET"] = "widget";
+    AnnotationType["SCREEN"] = "screen";
+    AnnotationType["PRINTER_MARK"] = "printer_mark";
+    AnnotationType["TRAP_NET"] = "trap_net";
+    AnnotationType["WATERMARK"] = "watermark";
+    AnnotationType["REDACT"] = "redact";
+})(AnnotationType || (AnnotationType = {}));
+// ============================================================================
+// Export PdfDocument (dynamically loaded from native module)
+// ============================================================================
+/**
+ * Re-export PdfDocument from the main nodejs module
+ * This provides the actual implementation with full type safety
+ */
+export { PdfDocument } from '../index.js';
+export default PdfDocument;

package/lib/types/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Type definitions index - re-exports all types for easy consumption
+ */
+export * from './common';
+export * from './native-bindings';

package/lib/types/index.js

@@ -0,0 +1,5 @@
+/**
+ * Type definitions index - re-exports all types for easy consumption
+ */
+export * from './common.js';
+export * from './native-bindings.js';