A fast, helpful, and open-source document parser
/* tslint:disable */
/* eslint-disable */
/* auto-generated by NAPI-RS */
export interface JsLiteParseConfig {
/** OCR language code (e.g., "eng", "fra"). */
ocrLanguage?: string
/** Whether OCR is enabled. */
ocrEnabled?: boolean
/** HTTP OCR server URL. If set, uses HTTP OCR instead of Tesseract. */
ocrServerUrl?: string
/**
* Extra HTTP headers sent with every request to `ocrServerUrl`
* (e.g. `{ Authorization: "Bearer <token>" }`).
*/
ocrServerHeaders?: Record<string, string>
/** Path to tessdata directory for Tesseract. */
tessdataPath?: string
/** Maximum number of pages to parse. */
maxPages?: number
/** Specific pages to parse (e.g., "1-5,10,15-20"). */
targetPages?: string
/**
* Render parsed pages to PNG and return them in `ParseResult.screenshots`.
* Default false; PNG payloads can be large.
*/
extractScreenshots?: boolean
/**
* Continue after page-level extraction failures and return them in
* `ParseResult.pageErrors`. Default false.
*/
continueOnPageError?: boolean
/** DPI for rendering pages (used for OCR and screenshots). */
dpi?: number
/** Output format: "json", "text", or "markdown". */
outputFormat?: string
/** Keep very small text that would normally be filtered out. */
preserveVerySmallText?: boolean
/** Password for encrypted/protected documents. */
password?: string
/** Suppress progress output. */
quiet?: boolean
/** Number of concurrent OCR workers (default: CPU cores - 1). */
numWorkers?: number
/**
* How to surface raster images in markdown output: "off", "placeholder"
* (default; emits `` references with no bytes), or
* "embed" (same presentation as placeholder; extraction is independent).
*/
imageMode?: string
/** Extract embedded image bytes and metadata (default false). */
extractImages?: boolean
/**
* Directory where embedded image files are written. Requires
* `extractImages` to be true.
*/
imageOutputDir?: string
/**
* Render hyperlink annotations as `[text](url)` in markdown output
* (default true). Set false for plain anchor text.
*/
extractLinks?: boolean
/**
* Keep running headers/footers in markdown output instead of stripping
* repeated page-band lines and page chrome (default false).
*/
keepHeadersFooters?: boolean
/** Extract all PDF annotations as page-scoped structured data. */
extractAnnotations?: boolean
/**
* Emit each page's classified layout blocks (headings, paragraphs, list
* items, tables with per-cell boxes, code, rules, figures) with bounding
* boxes as `ParsedPage.blocks`. Default false.
*/
extractBlocks?: boolean
/** Extract AcroForm widget fields and values. */
extractFormFields?: boolean
/** Extract the tagged-PDF logical structure tree. */
extractStructureTree?: boolean
/**
* Extract raw XFA packets (name + XML content) into
* `ParseResult.xfaPackets`. Default false.
*/
extractXfaPackets?: boolean
/**
* Collect document provenance metadata into `ParseResult.docMeta`.
* Default false: it streams the whole source file once. Absent for
* inputs converted from a non-PDF format.
*/
extractDocumentMetadata?: boolean
/**
* Emit each page's `contentBounds` (union bbox of top-level content
* objects, viewport coords). Default false.
*/
extractContentBounds?: boolean
/**
* Detect solid rectangles/lines in rendered page screenshots and attach
* them to each screenshot result. Default false.
*/
detectScreenshotRects?: boolean
/**
* Draw AcroForm field appearances into rendered rasters (screenshots and
* OCR inputs). Runs the document's open/JS actions. Default false.
*/
renderFormFields?: boolean
/**
* Whether a systemic OCR failure aborts the whole parse (default true).
* Set false to keep already-recovered native text and return partial
* results when OCR is unavailable, instead of rejecting.
*/
ocrFailureFatal?: boolean
/**
* OCR request-hedging schedule (ms). Empty/unset = no hedging. Multiple
* delays (e.g. `[0, 5000, 10000]`) fire duplicate requests per attempt and
* take the first success — lower tail latency at the cost of extra load.
*/
ocrHedgeDelaysMs?: Array<number>
/**
* Emit per-word sub-boxes on each text item (`TextItem.words`). Default
* false. Word boxes roughly double the text-item payload, so enable only
* for word-level bbox attribution.
*/
emitWordBoxes?: boolean
/** Include rich PDF text metadata on returned text items. Default false. */
extractTextMetadata?: boolean
/**
* Restrict output to a page sub-region. Each field is the fraction of the
* page cropped from that side; a text item survives only if it lies
* entirely inside the remaining rectangle. Unset keeps the whole page.
*/
cropBox?: JsCropBox
/**
* Drop diagonal text (rotation >2° off the nearest right angle). Default
* false. Use to exclude rotated watermarks/stamps from the output.
*/
skipDiagonalText?: boolean
/**
* Per-page orientation corrections from an upstream orientation
* classifier. Each entry names a 1-based page and the clockwise angle
* (0/90/180/270) by which its content appears rotated; LiteParse
* counter-rotates that page before extraction so text, reading order,
* page size and OCR rasters come out upright. Applied on top of the PDF's
* own /Rotate. Unlisted or out-of-range pages are left unchanged.
*/
pageOrientationCorrections?: Array<JsPageOrientationCorrection>
/**
* Compute per-page complexity signals during parse and attach them to each
* page as `ParsedPage.complexity` (the same signals `isComplex` returns).
* Default false; enabling it runs an extra vector-text detection pass.
*/
includeComplexity?: boolean
/** Expose page-scoped vector path extraction. Default false. */
extractVectorGraphics?: boolean
}
/**
* One page's orientation correction: `page` is 1-based, `angle` is the
* clockwise degrees (0/90/180/270) the content appears rotated.
*/
export interface JsPageOrientationCorrection {
page: number
angle: number
}
/**
* A page sub-region as the fraction cropped from each side (top-left origin,
* each in `[0, 1]`).
*/
export interface JsCropBox {
top: number
right: number
bottom: number
left: number
}
/** One word's sub-box within a `JsTextItem`, in the same viewport space. */
export interface JsWordBox {
text: string
x: number
y: number
width: number
height: number
}
export interface JsTextItem {
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
/** Fill color as an eight-character ARGB hex string. */
fillColor?: string
/** Stroke color as an eight-character ARGB hex string. */
strokeColor?: string
/** Raw PDF content-stream character codes for the source glyphs. */
charCodes?: Array<number>
/** True when the trailing source space was synthesized by PDFium. */
trailingSpaceGenerated?: boolean
/** OCR confidence score (0.0-1.0). Undefined for native PDF text. */
confidence?: number
/** Rotation in degrees (viewport space). Defaults to 0 when omitted. */
rotation?: number
/**
* Per-word sub-boxes for attribution. Empty for items with no word split
* (e.g. OCR-sourced or single-token items).
*/
words: Array<JsWordBox>
}
/**
* A vector-graphic primitive supplied by an external extractor. `kind` selects
* the variant: `"stroke"` (uses `x1/y1/x2/y2`) or `"rect"` (uses
* `x/y/width/height`). Coordinates are viewport space (top-left origin, 72
* DPI), matching the text items. `has_fill`/`has_stroke` carry the paint
* intent even when no color is known, so ruled-table edge detection still
* treats a colorless stroked rect as stroked.
*/
export interface JsGraphic {
/** "stroke" or "rect". Anything else is dropped. */
kind: string
x1?: number
y1?: number
x2?: number
y2?: number
x?: number
y?: number
width?: number
height?: number
/** Whether the path is filled. Drives Rect `fill` presence. */
hasFill?: boolean
/** Whether the path is stroked. Drives Rect `stroke` presence. */
hasStroke?: boolean
/** Fill color as ARGB hex (e.g. "ff000000"). May be absent even when filled. */
fillColor?: string
/** Stroke color as ARGB hex. May be absent even when stroked. */
strokeColor?: string
/** Stroke line width in points. */
lineWidth?: number
}
/**
* A page of pre-extracted text supplied by an external extractor. Coordinates
* are viewport space (top-left origin, 72 DPI). `graphics` enables ruled-table
* and horizontal-rule detection; struct nodes are still unsupported on this
* path, so tagged-heading detection remains unavailable until they are added.
*/
export interface JsPageInput {
pageNumber: number
pageWidth: number
pageHeight: number
textItems: Array<JsTextItem>
graphics?: Array<JsGraphic>
}
export interface JsParsedPage {
pageNum: number
/**
* The document's `/PageLabels` label for this page ("iv", "A-1"), absent
* when the PDF defines none. This is what a reader displays for the page
* and is not always its position; fall back to `page_num` when absent.
*/
pageLabel?: string
width: number
height: number
/**
* Union bbox of the page's top-level content objects in viewport
* coords (visible content extent). Absent for empty pages.
*/
contentBounds?: JsRect
text: string
markdown: string
textItems: Array<JsTextItem>
complexity?: JsPageComplexityStats
vectorGraphics?: JsVectorGraphics
annotations?: Array<JsDocumentAnnotation>
/**
* Classified layout blocks in reading order; present only when
* `extractBlocks` is enabled.
*/
blocks?: Array<JsLayoutBlock>
formFields?: Array<JsFormField>
structureTree?: JsStructureTree
}
export interface JsStructureAttribute {
name: string
booleanValue?: boolean
numberValue?: number
stringValue?: string
}
export interface JsStructureTree {
roots: Array<JsStructureTreeElement>
}
export interface JsStructureTreeElement {
elementType: string
id?: string
actualText?: string
altText?: string
title?: string
attributes: Array<JsStructureAttribute>
markedContentIds: Array<number>
children: Array<JsStructureTreeElement>
annotations: Array<JsDocumentAnnotation>
}
export interface JsVectorShape {
bbox: JsRect
stroke: boolean
strokeColor?: string
fill: boolean
fillColor?: string
hasCurve: boolean
}
export interface JsRect {
x: number
y: number
width: number
height: number
}
export interface JsAnnotationRect {
x: number
y: number
width: number
height: number
}
export interface JsVectorLine {
x1: number
y1: number
x2: number
y2: number
stroke: boolean
strokeWidth?: number
strokeColor?: string
fill: boolean
fillColor?: string
}
export interface JsVectorGraphics {
shapes: Array<JsVectorShape>
lines: Array<JsVectorLine>
}
export interface JsDocumentAnnotation {
subtype: string
contents?: string
created?: string
modified?: string
title?: string
rect?: JsAnnotationRect
quadpointRects: Array<JsAnnotationRect>
uri?: string
}
export interface JsFormField {
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?: JsAnnotationRect
options: Array<string>
selectedOptions: Array<string>
}
/**
* One table cell: its rendered text and the region it occupied. `bbox` is
* absent for cells with no ink behind them (padding for a ragged grid, or a
* merged run split at an estimated boundary).
*/
export interface JsLayoutCell {
text: string
bbox?: JsAnnotationRect
}
/**
* A classified block plus where it sits on the page. Flat by design — `kind`
* discriminates the block and every field that doesn't apply to that kind is
* absent.
*/
export interface JsLayoutBlock {
/**
* One of `heading`, `paragraph`, `list_item`, `code`, `table`,
* `grid_fallback`, `rule`, `figure`.
*/
kind: string
/**
* Rendered text for the text-bearing kinds (`heading`, `paragraph`,
* `list_item`). Table text lives in `header`/`rows`; code and grid text in
* `lines`.
*/
text?: string
/** Heading level (1–6), or list nesting depth for `list_item`. */
level?: number
/**
* Whether the block's text is uniformly bold / italic. `paragraph` and
* `list_item` only; false otherwise.
*/
bold: boolean
italic: boolean
/**
* `list_item`: whether the list is ordered, and the original marker as it
* appeared on the page (`138.`, `iii)`, `•`).
*/
ordered?: boolean
marker?: string
/** Verbatim source lines for `code` and `grid_fallback`. */
lines?: Array<string>
/** Best-effort language hint for `code`. */
lang?: string
/** `table`: the header row, when one was detected. */
header?: Array<JsLayoutCell>
/** `table`: the body rows. */
rows?: Array<Array<JsLayoutCell>>
/**
* `figure`: the image's page-scoped id and encoded format, matching the
* `img_{id}.{format}` target the markdown renderer emits.
*/
id?: string
format?: string
/**
* Region of the page this block occupies, in the same viewport space as
* `textItems`. Absent when the block has no page geometry behind it.
*/
bbox?: JsAnnotationRect
}
export interface JsParseResult {
/** Total source-document pages before target/max-page filtering. */
totalPages: number
pages: Array<JsParsedPage>
pageErrors: Array<JsPageError>
text: string
images: Array<JsExtractedImage>
screenshots: Array<JsScreenshotResult>
imageErrorCount: number
formType?: number
/** The document's `/Info` `Creator` entry, when present. */
creator?: string
/** The document's `/Info` `Producer` entry, when present. */
producer?: string
/**
* Document-level provenance metadata; present only when
* `extractDocumentMetadata` is enabled and the input was a real PDF.
*/
docMeta?: JsDocumentMetadata
/** Raw XFA packets; present only when `extractXfaPackets` is enabled. */
xfaPackets?: Array<JsXfaPacket>
}
/** One batch of pages from a `ParseSession`. */
export interface JsParseBatch {
/** First source page in this batch, 1-indexed. */
startPage: number
/** Last source page in this batch, 1-indexed and inclusive. */
endPage: number
/** The pages in `startPage..=endPage`, as an ordinary parse result. */
result: JsParseResult
}
export interface JsPageError {
pageNum: number
message: string
}
export interface JsDocumentMetadata {
creationDate?: string
modDate?: string
fileVersion?: number
isEncrypted?: boolean
securityHandlerRevision?: number
permissions?: number
eofSectionCount?: number
startxrefCount?: number
trailerIdPairDiffers?: boolean
rawFileSize?: number
xmp?: string
/** True when the catalog's XMP stream exceeded the 64 KiB cap. */
xmpTruncated?: boolean
signatureCount?: number
signatureByteRangeReachesEof?: boolean
}
/** One raw packet from an XFA form document's `/XFA` array. */
export interface JsXfaPacket {
index: number
name?: string
contentLength: number
/** Packet content (usually XML), lossily decoded as UTF-8. */
content?: string
}
export interface JsImageRect {
x: number
y: number
width: number
height: number
}
export interface JsExtractedImage {
id: string
name: string
path?: string
page: number
bbox: JsImageRect
width: number
height: number
rotation: number
format: string
duplicateOf?: string
bytes: Buffer
}
export interface JsScreenshotResult {
pageNum: number
width: number
height: number
imageBuffer: Buffer
/** True when every pixel has the same color (blank page after render). */
isSolidFill: boolean
/**
* Solid rectangles/lines detected in the raster (viewport coords).
* Populated only when `detectScreenshotRects` is enabled.
*/
rects: Array<JsScreenshotRect>
}
/**
* One solid rectangle (or line) detected in a rendered page bitmap, in
* viewport coords (top-left origin, 72 DPI).
*/
export interface JsScreenshotRect {
x: number
y: number
width: number
height: number
/** Fill color as ARGB hex string (e.g. "ff1a2b3c"). */
color: string
/** True when the region is a solid line rather than a filled area. */
isLine: boolean
}
export interface JsLayoutComplexityStats {
columnCount: number
ruledTableCount: number
ruledTableCoverage: number
textTableRunCount: number
figureCount: number
figureCoverage: number
isComplex: boolean
reasons: Array<string>
}
export interface JsPageComplexityStats {
pageNumber: number
textLength: number
textCoverage: number
hasSubstantialImages: boolean
/**
* Number of counted raster images — inline figures only; full-page
* backgrounds are excluded (see `fullPageImage`).
*/
imageBlockCount: number
/**
* Summed image-bbox area over page area, clamped to 1. Counts inline
* figures only: a full-page scan raster contributes 0 here — check
* `fullPageImage` for that.
*/
imageCoverage: number
/**
* Largest single counted image's area over page area, clamped to 1. Same
* exclusion as `imageCoverage`: a full-page raster contributes 0.
*/
largestImageCoverage: number
/**
* A single raster covering ≥90% of the page is present. Such full-page
* backgrounds are excluded from `imageCoverage`/`largestImageCoverage`
* (they're not inline figures), so this flag is the only signal that
* distinguishes a scan from a genuinely blank page — both otherwise
* report no text and no counted images.
*/
fullPageImage: boolean
uncoveredVectorArea?: number
isGarbled: boolean
pageArea: number
needsOcr: boolean
reasons: Array<string>
layout?: JsLayoutComplexityStats
}
/** Search text items for phrase matches, returning merged items with combined bounding boxes. */
export declare function searchItems(items: Array<JsTextItem>, phrase: string, caseSensitive?: boolean | undefined | null): Array<JsTextItem>
/** Main LiteParse parser class. */
export declare class LiteParse {
/**
* Create a new LiteParse instance with optional configuration.
* Any fields not provided will use defaults.
*/
constructor(config?: JsLiteParseConfig | undefined | null)
/** Parse a document. Accepts a file path (string) or raw PDF bytes (Buffer). */
parse(input: string | Buffer): Promise<JsParseResult>
/**
* Open a document for bounded-memory batch parsing. Internal plumbing
* for the JS wrapper's `parseBatches()` — prefer that; it also closes
* the session for you.
*
* Converts a non-PDF source once, then yields `batchSize` pages at a time
* via `nextBatch()` (default 25). Cross-page passes (repeated
* header/footer removal, image deduplication) see only the pages in their
* own batch, so output can differ from a whole-document `parse()`.
*/
openBatchSession(input: string | Buffer, batchSize?: number | undefined | null): Promise<ParseSession>
/**
* Parse from pre-extracted pages, skipping PDFium text extraction.
*
* The caller supplies pages already populated with text items in viewport
* space (top-left origin, 72 DPI). Runs only grid projection + the
* configured output formatter, so it never loads PDFium. Use when an
* external extractor owns text extraction (e.g. to keep its own
* font-recovery pipeline).
*/
parsePages(pages: Array<JsPageInput>): JsParseResult
/**
* Determine per-page complexity. Returns one entry per parsed page with
* signals (text coverage, images, garbled text, vector area) and a
* `needsOcr` verdict — a cheap pre-OCR check to decide whether a document
* needs advanced parsing. Accepts a file path (string) or raw PDF bytes.
*/
isComplex(input: string | Buffer): Promise<Array<JsPageComplexityStats>>
/**
* Take screenshots of document pages. Returns PNG image buffers.
*
* Non-PDF files are automatically converted to PDF before rendering when
* LibreOffice/ImageMagick are available.
*/
screenshot(input: string | Buffer, pageNumbers?: Array<number> | undefined | null): Promise<Array<JsScreenshotResult>>
/** Get the current configuration. */
get config(): JsLiteParseConfig
}
/**
* A document opened once and parsed in bounded page batches. Internal
* plumbing for the JS wrapper's `parseBatches()` — prefer that.
*
* Created by `LiteParse.openBatchSession()`. The converted-PDF temporary
* file for a non-PDF source lives as long as the session, so conversion is
* paid once no matter how many batches are consumed. Call `close()` when
* abandoning the session early — otherwise that temp file waits for GC.
*/
export declare class ParseSession {
/** Total pages in the source document, before `maxPages` or batching. */
get totalPages(): number
/**
* Parse and return the next batch, or `null` once every page within
* `maxPages` has been yielded. Rejects if the session is closed.
*/
nextBatch(): Promise<JsParseBatch | null>
/**
* Release the session's resources now — most importantly the converted
* temporary PDF for a non-PDF source, which otherwise lives until the
* JS object is garbage collected. Idempotent; `nextBatch()` rejects
* afterwards.
*/
close(): Promise<void>
}