@llamaindex/liteparse 2.13.0 → 2.14.0

package/dist/lib.d.ts

@@ -1,7 +1,289 @@
-export type LiteParseInput = string | Buffer | Uint8Array;
-export type OutputFormat = "json" | "text" | "markdown";
-export type ImageMode = "off" | "placeholder" | "embed";
-export interface LiteParseConfig {
+interface NativeWordBox {
+    text: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface NativeTextItem {
+    text: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    fontName?: string;
+    fontSize?: number;
+    fontHeight?: number;
+    fontAscent?: number;
+    fontDescent?: number;
+    fontWeight?: number;
+    textWidth?: number;
+    fontIsBuggy?: boolean;
+    mcid?: number;
+    fillColor?: string;
+    strokeColor?: string;
+    charCodes?: number[];
+    trailingSpaceGenerated?: boolean;
+    confidence?: number;
+    rotation?: number;
+    words?: NativeWordBox[];
+}
+interface NativeRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface NativeParsedPage {
+    pageNum: number;
+    width: number;
+    height: number;
+    contentBounds?: NativeRect;
+    text: string;
+    markdown: string;
+    textItems: NativeTextItem[];
+    complexity?: NativePageComplexityStats;
+    vectorGraphics?: NativeVectorGraphics;
+    annotations?: NativeDocumentAnnotation[];
+    formFields?: NativeFormField[];
+    structureTree?: NativeStructureTree;
+    blocks?: NativeLayoutBlock[];
+}
+interface NativeLayoutCell {
+    text: string;
+    bbox?: NativeRect;
+}
+interface NativeLayoutBlock {
+    kind: string;
+    text?: string;
+    level?: number;
+    bold?: boolean;
+    italic?: boolean;
+    ordered?: boolean;
+    marker?: string;
+    lines?: string[];
+    lang?: string;
+    header?: NativeLayoutCell[];
+    rows?: NativeLayoutCell[][];
+    id?: string;
+    format?: string;
+    bbox?: NativeRect;
+}
+interface NativeStructureAttribute {
+    name: string;
+    booleanValue?: boolean;
+    numberValue?: number;
+    stringValue?: string;
+}
+interface NativeStructureTree {
+    roots: NativeStructureTreeElement[];
+}
+interface NativeStructureTreeElement {
+    elementType: string;
+    id?: string;
+    actualText?: string;
+    altText?: string;
+    title?: string;
+    attributes: NativeStructureAttribute[];
+    markedContentIds: number[];
+    children: NativeStructureTreeElement[];
+    annotations: NativeDocumentAnnotation[];
+}
+interface NativeVectorGraphics {
+    shapes: Array<{
+        bbox: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+        stroke: boolean;
+        strokeColor?: string;
+        fill: boolean;
+        fillColor?: string;
+        hasCurve: boolean;
+    }>;
+    lines: Array<{
+        x1: number;
+        y1: number;
+        x2: number;
+        y2: number;
+        stroke: boolean;
+        strokeWidth?: number;
+        strokeColor?: string;
+        fill: boolean;
+        fillColor?: string;
+    }>;
+}
+interface NativeAnnotationRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface NativeDocumentAnnotation {
+    subtype: string;
+    contents?: string;
+    created?: string;
+    modified?: string;
+    title?: string;
+    rect?: NativeAnnotationRect;
+    quadpointRects: NativeAnnotationRect[];
+    uri?: string;
+}
+interface NativeFormField {
+    id: string;
+    fieldType: string;
+    page: number;
+    annotationIndex: number;
+    widgetIndex: number;
+    objectNumber?: number;
+    name?: string;
+    alternateName?: string;
+    value?: string;
+    exportValue?: string;
+    fieldFlags: number;
+    controlCount?: number;
+    controlIndex?: number;
+    checked?: boolean;
+    rect?: NativeAnnotationRect;
+    options: string[];
+    selectedOptions: string[];
+}
+interface NativeExtractedImage {
+    id: string;
+    name: string;
+    path?: string;
+    page: number;
+    bbox: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    width: number;
+    height: number;
+    rotation: number;
+    format: string;
+    duplicateOf?: string;
+    bytes: Buffer;
+}
+interface NativeParseResult {
+    totalPages: number;
+    pages: NativeParsedPage[];
+    pageErrors: Array<{
+        pageNum: number;
+        message: string;
+    }>;
+    text: string;
+    images: NativeExtractedImage[];
+    screenshots: NativeScreenshotResult[];
+    imageErrorCount: number;
+    formType?: number;
+    creator?: string;
+    producer?: string;
+    docMeta?: NativeDocumentMetadata;
+    xfaPackets?: NativeXfaPacket[];
+}
+interface NativeDocumentMetadata {
+    creationDate?: string;
+    modDate?: string;
+    fileVersion?: number;
+    isEncrypted?: boolean;
+    securityHandlerRevision?: number;
+    permissions?: number;
+    eofSectionCount?: number;
+    startxrefCount?: number;
+    trailerIdPairDiffers?: boolean;
+    rawFileSize?: number;
+    xmp?: string;
+    xmpTruncated?: boolean;
+    signatureCount?: number;
+    signatureByteRangeReachesEof?: boolean;
+}
+interface NativeXfaPacket {
+    index: number;
+    name?: string;
+    contentLength: number;
+    content?: string;
+}
+interface NativeScreenshotResult {
+    pageNum: number;
+    width: number;
+    height: number;
+    imageBuffer: Buffer;
+    isSolidFill: boolean;
+    rects: NativeScreenshotRect[];
+}
+interface NativeScreenshotRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    color: string;
+    isLine: boolean;
+}
+interface NativeLayoutComplexityStats {
+    columnCount: number;
+    ruledTableCount: number;
+    ruledTableCoverage: number;
+    textTableRunCount: number;
+    figureCount: number;
+    figureCoverage: number;
+    isComplex: boolean;
+    reasons: string[];
+}
+interface NativePageComplexityStats {
+    pageNumber: number;
+    textLength: number;
+    textCoverage: number;
+    hasSubstantialImages: boolean;
+    imageBlockCount: number;
+    imageCoverage: number;
+    largestImageCoverage: number;
+    fullPageImage: boolean;
+    uncoveredVectorArea?: number;
+    isGarbled: boolean;
+    pageArea: number;
+    needsOcr: boolean;
+    reasons: string[];
+    layout?: NativeLayoutComplexityStats;
+}
+
+/** A pooled parse exceeded `parseTimeoutMs` and its worker was killed.
+ *
+ * Only thrown in pool mode, where the deadline is enforced by killing the
+ * worker process — the timed-out parse is guaranteed dead, not still running
+ * in the background. `source` names the document (file path, or `<N bytes>`
+ * for byte inputs); log it to identify the documents that stall your
+ * pipeline.
+ */
+declare class ParseTimeoutError extends Error {
+    readonly source: string;
+    readonly timeoutMs: number;
+    constructor(message: string, source: string, timeoutMs: number);
+}
+
+type LiteParseInput = string | Buffer | Uint8Array;
+type OutputFormat = "json" | "text" | "markdown";
+type ImageMode = "off" | "placeholder" | "embed";
+/** Options for pool mode: parsing in persistent, killable worker processes. */
+interface PoolOptions {
+    /**
+     * Route `parse()` through a pool of this many persistent worker processes.
+     * Call `close()` when done (an idle pool never keeps the event loop alive,
+     * but explicit shutdown frees workers immediately).
+     */
+    poolSize?: number;
+    /**
+     * Hard per-parse deadline in milliseconds. Requires `poolSize`.
+     * The pool enforces the deadline by SIGKILLing the worker. On expiry
+     * the parse rejects with {@link ParseTimeoutError} (naming the document)
+     * and a fresh worker replaces the killed one.
+     */
+    parseTimeoutMs?: number;
+}
+interface LiteParseConfig {
     ocrLanguage: string;
     ocrEnabled: boolean;
     ocrServerUrl?: string;
@@ -105,7 +387,7 @@ export interface LiteParseConfig {
  * A page sub-region expressed as the fraction cropped from each side
  * (top-left origin, each value in `[0, 1]`).
  */
-export interface CropBox {
+interface CropBox {
     top: number;
     right: number;
     bottom: number;
@@ -115,14 +397,14 @@ export interface CropBox {
  * One word's bounding box within a {@link TextItem}, in the same viewport space
  * (top-left origin, 72 DPI). `text` excludes inter-word spaces.
  */
-export interface WordBox {
+interface WordBox {
     text: string;
     x: number;
     y: number;
     width: number;
     height: number;
 }
-export interface TextItem {
+interface TextItem {
     text: string;
     x: number;
     y: number;
@@ -168,7 +450,7 @@ export interface TextItem {
  * when the color is unknown, so ruled-table edge detection still treats a
  * colorless stroked rect as stroked.
  */
-export interface Graphic {
+interface Graphic {
     kind: "stroke" | "rect";
     x1?: number;
     y1?: number;
@@ -189,20 +471,20 @@ export interface Graphic {
  * Coordinates are viewport space (top-left origin, 72 DPI). `graphics` is
  * optional; when supplied it enables ruled-table and horizontal-rule detection.
  */
-export interface PageInput {
+interface PageInput {
     pageNumber: number;
     pageWidth: number;
     pageHeight: number;
     textItems: TextItem[];
     graphics?: Graphic[];
 }
-export interface Rect {
+interface Rect {
     x: number;
     y: number;
     width: number;
     height: number;
 }
-export interface ParsedPage {
+interface ParsedPage {
     pageNum: number;
     width: number;
     height: number;
@@ -237,7 +519,7 @@ export interface ParsedPage {
     blocks?: LayoutBlock[];
 }
 /** One table cell: its text and the region of the page it was read from. */
-export interface LayoutCell {
+interface LayoutCell {
     text: string;
     /**
      * Absent for cells with no ink behind them — padding inserted to square off
@@ -246,7 +528,7 @@ export interface LayoutCell {
     bbox?: Rect;
 }
 /** A classified block of page content, discriminated by `kind`. */
-export interface LayoutBlock {
+interface LayoutBlock {
     kind: "heading" | "paragraph" | "list_item" | "code" | "table" | "grid_fallback" | "rule" | "figure";
     /** Rendered text for `heading`, `paragraph`, and `list_item`. */
     text?: string;
@@ -273,11 +555,11 @@ export interface LayoutBlock {
      */
     bbox?: Rect;
 }
-export type StructureAttributeValue = boolean | number | string;
-export interface StructureTree {
+type StructureAttributeValue = boolean | number | string;
+interface StructureTree {
     roots: StructureTreeElement[];
 }
-export interface StructureTreeElement {
+interface StructureTreeElement {
     type: string;
     id?: string;
     actualText?: string;
@@ -288,11 +570,11 @@ export interface StructureTreeElement {
     children: StructureTreeElement[];
     annotations: DocumentAnnotation[];
 }
-export interface VectorGraphics {
+interface VectorGraphics {
     shapes: VectorShape[];
     lines: VectorLine[];
 }
-export interface VectorShape {
+interface VectorShape {
     bbox: {
         x: number;
         y: number;
@@ -305,7 +587,7 @@ export interface VectorShape {
     fillColor?: string;
     hasCurve: boolean;
 }
-export interface VectorLine {
+interface VectorLine {
     x1: number;
     y1: number;
     x2: number;
@@ -316,13 +598,13 @@ export interface VectorLine {
     fill: boolean;
     fillColor?: string;
 }
-export interface AnnotationRect {
+interface AnnotationRect {
     x: number;
     y: number;
     width: number;
     height: number;
 }
-export interface DocumentAnnotation {
+interface DocumentAnnotation {
     subtype: string;
     contents?: string;
     created?: string;
@@ -332,7 +614,7 @@ export interface DocumentAnnotation {
     quadpointRects: AnnotationRect[];
     uri?: string;
 }
-export interface FormField {
+interface FormField {
     id: string;
     type: string;
     page: number;
@@ -351,7 +633,7 @@ export interface FormField {
     options: string[];
     selectedOptions: string[];
 }
-export interface ExtractedImage {
+interface ExtractedImage {
     /** Reference id used in the markdown output (e.g. `![](img_p1_1.png)` → `"p1_1"`). */
     id: string;
     /** File name used when `imageOutputDir` is configured. */
@@ -376,7 +658,7 @@ export interface ExtractedImage {
     duplicateOf?: string;
     bytes: Buffer;
 }
-export interface ParseResult {
+interface ParseResult {
     /** Total source-document pages before `targetPages` or `maxPages` filtering. */
     totalPages: number;
     pages: ParsedPage[];
@@ -407,11 +689,11 @@ export interface ParseResult {
     /** Raw XFA packets; present only when `extractXfaPackets` is enabled. */
     xfaPackets?: XfaPacket[];
 }
-export interface ParseBatchOptions {
+interface ParseBatchOptions {
     /** Pages materialized in one batch. Default: 25. */
     batchSize?: number;
 }
-export interface ParseBatch {
+interface ParseBatch {
     /** First source page in this batch (1-indexed). */
     startPage: number;
     /** Last source page in this batch (1-indexed, inclusive). */
@@ -421,7 +703,7 @@ export interface ParseBatch {
     result: ParseResult;
 }
 /** Provenance and tamper-analysis facts extracted from the source PDF. */
-export interface DocumentMetadata {
+interface DocumentMetadata {
     creationDate?: string;
     modDate?: string;
     /** Encoded PDF version (`14` means PDF 1.4). */
@@ -446,14 +728,14 @@ export interface DocumentMetadata {
     signatureByteRangeReachesEof?: boolean;
 }
 /** One raw packet from an XFA form document's `/XFA` array. */
-export interface XfaPacket {
+interface XfaPacket {
     index: number;
     name?: string;
     contentLength: number;
     /** Packet content (usually XML), lossily decoded as UTF-8. */
     content?: string;
 }
-export interface ScreenshotResult {
+interface ScreenshotResult {
     pageNum: number;
     width: number;
     height: number;
@@ -464,7 +746,7 @@ export interface ScreenshotResult {
     rects: ScreenshotRect[];
 }
 /** One solid rectangle (or line) detected in a rendered page bitmap. */
-export interface ScreenshotRect {
+interface ScreenshotRect {
     x: number;
     y: number;
     width: number;
@@ -478,7 +760,7 @@ export interface ScreenshotRect {
  * Per-page complexity signals from {@link LiteParse.isComplex}, used to decide
  * whether a document needs OCR or other advanced parsing.
  */
-export interface PageComplexityStats {
+interface PageComplexityStats {
     pageNumber: number;
     textLength: number;
     /** Fraction of the page area covered by native text (0–1). */
@@ -533,7 +815,7 @@ export interface PageComplexityStats {
  * Layout-difficulty signals for one page, computed from the real
  * grid-projection pass.
  */
-export interface LayoutComplexityStats {
+interface LayoutComplexityStats {
     /** Side-by-side text columns found by the layout pass (1 = single column). */
     columnCount: number;
     /** Ruled-table grids detected on the page. */
@@ -559,11 +841,28 @@ export interface LayoutComplexityStats {
      */
     reasons: string[];
 }
-export declare class LiteParse {
+declare class LiteParse {
     private _native;
     private _config;
-    constructor(userConfig?: Partial<LiteParseConfig>);
+    private _pool;
+    constructor(userConfig?: Partial<LiteParseConfig> & PoolOptions);
     parse(input: LiteParseInput): Promise<ParseResult>;
+    /**
+     * Resolves once every pool worker is initialized. No-op without `poolSize`.
+     *
+     * Optional: the first parse on each worker waits for its init anyway. Call
+     * this before latency-sensitive traffic to avoid paying worker startup on
+     * the first request.
+     */
+    warmUp(): Promise<void>;
+    /**
+     * Shut down pool workers, if pool mode is enabled. Idempotent.
+     *
+     * Without `poolSize` this is a no-op. An idle pool never keeps the event
+     * loop alive and workers exit when the parent does, so forgetting to call
+     * this leaks nothing past process exit.
+     */
+    close(): void;
     /**
      * Parse a document in bounded-memory page batches of `batchSize` pages.
      *
@@ -601,10 +900,12 @@ export declare class LiteParse {
     screenshot(input: LiteParseInput, pageNumbers?: number[]): Promise<ScreenshotResult[]>;
     getConfig(): LiteParseConfig;
 }
-export interface SearchItemsOptions {
+/** @internal Exported for pool-worker.ts only; not public API. */
+declare function toParseResult(result: NativeParseResult): ParseResult;
+interface SearchItemsOptions {
     phrase: string;
     caseSensitive?: boolean;
 }
-export declare function searchItems(items: TextItem[], options: SearchItemsOptions): TextItem[];
-export default LiteParse;
-//# sourceMappingURL=lib.d.ts.map
+declare function searchItems(items: TextItem[], options: SearchItemsOptions): TextItem[];
+
+export { type AnnotationRect, type CropBox, type DocumentAnnotation, type DocumentMetadata, type ExtractedImage, type FormField, type Graphic, type ImageMode, type LayoutBlock, type LayoutCell, type LayoutComplexityStats, LiteParse, type LiteParseConfig, type LiteParseInput, type OutputFormat, type PageComplexityStats, type PageInput, type ParseBatch, type ParseBatchOptions, type ParseResult, ParseTimeoutError, type ParsedPage, type PoolOptions, type Rect, type ScreenshotRect, type ScreenshotResult, type SearchItemsOptions, type StructureAttributeValue, type StructureTree, type StructureTreeElement, type TextItem, type VectorGraphics, type VectorLine, type VectorShape, type WordBox, type XfaPacket, LiteParse as default, searchItems, toParseResult };