A fast, helpful, and open-source document parser
import {
native,
type LiteParseNative,
type LiteParseNativeConfig,
type NativeParseResult,
type NativeParsedPage,
type NativePageInput,
type NativeTextItem,
type NativeExtractedImage,
type NativeStructureTreeElement,
type NativePageComplexityStats,
type NativeScreenshotResult,
} from "./native.js";
import { WorkerPool, ParseTimeoutError } from "./pool.js";
export { ParseTimeoutError };
// ---------------------------------------------------------------------------
// Public types — match the existing TypeScript API
// ---------------------------------------------------------------------------
export type LiteParseInput = string | Buffer | Uint8Array;
export type OutputFormat = "json" | "text" | "markdown";
export type ImageMode = "off" | "placeholder" | "embed";
/** Options for pool mode: parsing in persistent, killable worker processes. */
export 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;
}
export interface LiteParseConfig {
ocrLanguage: string;
ocrEnabled: boolean;
ocrServerUrl?: string;
/** Extra HTTP headers sent with every request to `ocrServerUrl`. */
ocrServerHeaders?: Record<string, string>;
tessdataPath?: string;
maxPages: number;
targetPages?: string;
/** Render parsed pages to PNG and return them in `ParseResult.screenshots`. */
extractScreenshots: boolean;
/** Continue after page-level extraction failures and collect `pageErrors`. */
continueOnPageError: boolean;
dpi: number;
outputFormat: OutputFormat;
/** How to surface raster images in markdown output (default: "placeholder"). */
imageMode: ImageMode;
/** Extract embedded image bytes and metadata (default: false). */
extractImages: boolean;
/** Directory where extracted embedded image files are written. Requires `extractImages`. */
imageOutputDir?: string;
/** Render hyperlink annotations as `[text](url)` in markdown output (default: true). */
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 into each parsed page (default: false). */
extractAnnotations: boolean;
/** Extract AcroForm widget fields and values (default: false). */
extractFormFields: boolean;
/** Extract the tagged-PDF logical structure tree (default: false). */
extractStructureTree: boolean;
/**
* Emit each page's classified layout blocks with bounding boxes
* (default: false). This is the same decomposition the Markdown renderer
* consumes, exposed as data; enabling it never changes the rendered Markdown.
*/
extractBlocks: boolean;
/** Extract raw XFA packets (name + XML content) into `ParseResult.xfaPackets` (default: false). */
extractXfaPackets: boolean;
/**
* Collect document provenance metadata into `result.docMeta`. Default
* false: Absent for inputs converted from a non-PDF format.
*/
extractDocumentMetadata: boolean;
/** Emit each page's `contentBounds` (union bbox of top-level content objects) (default: false). */
extractContentBounds: boolean;
/** Detect solid rectangles/lines in rendered page screenshots (default: false). */
detectScreenshotRects: boolean;
/** Draw AcroForm field appearances into rendered rasters (screenshots and OCR inputs; runs document open/JS actions; default: false). */
renderFormFields: boolean;
preserveVerySmallText: boolean;
password?: string;
quiet: boolean;
numWorkers: number;
/**
* Whether a systemic OCR failure (every OCR task failed and at least one was
* a text-sparse page) aborts the whole parse (default: true). Set false to
* keep already-recovered native text and return partial results instead of
* rejecting — for callers that prefer a degraded document over a hard failure.
*/
ocrFailureFatal: boolean;
/**
* OCR request-hedging schedule (ms). Empty (default) = no hedging. Multiple
* delays (e.g. `[0, 5000, 10000, 15000, 20000]`) fire duplicate requests per
* OCR attempt and take the first success — lower tail latency on a slow/stuck
* OCR pod, at the cost of extra OCR-server load. HTTP OCR engine only.
*/
ocrHedgeDelaysMs: number[];
/**
* Emit per-word sub-boxes on each text item ({@link TextItem.words}).
* Default false. Word boxes roughly double the text-item payload (size + napi
* marshalling), so enable only when doing 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 away from that side (top-left origin), so `{ left: 0.5 }`
* discards the left half. A text item survives only when it lies entirely
* inside the remaining rectangle. Undefined (default) keeps the whole page.
* Applied after OCR merge, so OCR text outside the region is dropped too.
*/
cropBox?: CropBox;
/**
* Drop diagonal text — items whose rotation is more than 2° off the nearest
* right angle (0/90/180/270). Default false. Use to exclude rotated
* watermarks/stamps from the output.
*/
skipDiagonalText: boolean;
/**
* Per-page orientation corrections from an upstream orientation classifier
* (one that saw the rendered page). Each entry names a 1-based page and the
* clockwise angle (0/90/180/270) by which that page's content *appears*
* rotated in its viewport; LiteParse counter-rotates the page before
* extraction, so text coordinates, reading order, page dimensions and OCR
* rasters all come out upright. Applied on top of the PDF's own `/Rotate`.
* Pages not listed, or past the end of the document, are left unchanged.
* Default: none.
*/
pageOrientationCorrections?: PageOrientationCorrection[];
/**
* Compute per-page complexity signals during {@link LiteParse.parse} and
* attach them to each page as {@link ParsedPage.complexity} (the same signals
* {@link LiteParse.isComplex} returns). Default false; enabling it runs an
* extra vector-text detection pass.
*/
includeComplexity: boolean;
/** Expose page-scoped vector shapes and merged H/V line segments. Default false. */
extractVectorGraphics: boolean;
}
/**
* A page sub-region expressed as the fraction cropped from each side
* (top-left origin, each value in `[0, 1]`).
*/
export interface CropBox {
top: number;
right: number;
bottom: number;
left: number;
}
/**
* One page's orientation correction (see
* {@link LiteParseConfig.pageOrientationCorrections}).
*/
export interface PageOrientationCorrection {
/** 1-based document page number. */
page: number;
/** Clockwise degrees the content appears rotated: 0, 90, 180 or 270. */
angle: 0 | 90 | 180 | 270;
}
/**
* 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 {
text: string;
x: number;
y: number;
width: number;
height: number;
}
export interface TextItem {
text: string;
x: number;
y: number;
width: number;
height: number;
fontName?: string;
fontSize?: number;
/** Font size after applying the text matrix's vertical scale. */
fontHeight?: number;
fontAscent?: number;
fontDescent?: number;
fontWeight?: number;
/** Sum of source glyph widths in points. */
textWidth?: number;
fontIsBuggy?: boolean;
/** Marked-content ID from the PDF structure tree. */
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?: 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 within this item. A text item groups several words
* together (breaking only at line/column boundaries), so this carries the
* finer word-level geometry for bbox attribution. Empty/undefined for items
* with no word split (e.g. OCR-sourced or single-token items).
*/
words?: WordBox[];
}
/**
* A vector-graphic primitive supplied to {@link LiteParse.parsePages}. `kind`
* selects the variant: `"stroke"` (uses `x1/y1/x2/y2`) or `"rect"` (uses
* `x/y/width/height`, top-left origin). Coordinates are viewport space (72 DPI),
* matching the text items. `hasFill`/`hasStroke` carry the paint intent even
* when the color is unknown, so ruled-table edge detection still treats a
* colorless stroked rect as stroked.
*/
export interface Graphic {
kind: "stroke" | "rect";
x1?: number;
y1?: number;
x2?: number;
y2?: number;
x?: number;
y?: number;
width?: number;
height?: number;
hasFill?: boolean;
hasStroke?: boolean;
fillColor?: string;
strokeColor?: string;
lineWidth?: number;
}
/**
* A page of pre-extracted text supplied to {@link LiteParse.parsePages}.
* 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 {
pageNumber: number;
pageWidth: number;
pageHeight: number;
textItems: TextItem[];
graphics?: Graphic[];
}
export interface Rect {
x: number;
y: number;
width: number;
height: number;
}
export interface ParsedPage {
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, so fall back to `pageNum` 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.
*/
/** Present only when `extractContentBounds` is enabled. */
contentBounds?: Rect;
text: string;
markdown: string;
textItems: TextItem[];
/**
* Per-page complexity signals (the same {@link LiteParse.isComplex} returns).
* Present only when parsing with `includeComplexity: true`; `undefined`
* otherwise.
*/
complexity?: PageComplexityStats;
/** Present only when parsing with `extractVectorGraphics: true`. */
vectorGraphics?: VectorGraphics;
/** Present only when `extractAnnotations` is enabled. */
annotations?: DocumentAnnotation[];
/** Present only when `extractFormFields` is enabled. */
formFields?: FormField[];
/** Present only when `extractStructureTree` is enabled. */
structureTree?: StructureTree;
/**
* Classified layout blocks in reading order — the same blocks, in the same
* order, the page's Markdown is built from. Present only when
* `extractBlocks` is enabled.
*/
blocks?: LayoutBlock[];
}
/** One table cell: its text and the region of the page it was read from. */
export interface LayoutCell {
text: string;
/**
* Absent for cells with no ink behind them — padding inserted to square off
* a ragged grid, or halves of a merged run split at an estimated position.
*/
bbox?: Rect;
}
/** A classified block of page content, discriminated by `kind`. */
export interface LayoutBlock {
kind:
| "heading"
| "paragraph"
| "list_item"
| "code"
| "table"
| "grid_fallback"
| "rule"
| "figure";
/** Rendered text for `heading`, `paragraph`, and `list_item`. */
text?: string;
/** Heading level (1-6), or list nesting depth for `list_item`. */
level?: number;
bold?: boolean;
italic?: boolean;
/** `list_item` only. `marker` is the marker as it appeared on the page. */
ordered?: boolean;
marker?: string;
/** Verbatim source lines for `code` and `grid_fallback`. */
lines?: string[];
/** Best-effort language hint for `code`. */
lang?: string;
/** `table` only. */
header?: LayoutCell[];
rows?: LayoutCell[][];
/** `figure` only, matching the `img_{id}.{format}` Markdown target. */
id?: string;
format?: string;
/**
* Region this block occupies, in the same top-left 72-DPI viewport space as
* `textItems`. The union of every source line that fed the block.
*/
bbox?: Rect;
}
export type StructureAttributeValue = boolean | number | string;
export interface StructureTree {
roots: StructureTreeElement[];
}
export interface StructureTreeElement {
type: string;
id?: string;
actualText?: string;
altText?: string;
title?: string;
attributes: Record<string, StructureAttributeValue>;
markedContentIds: number[];
children: StructureTreeElement[];
annotations: DocumentAnnotation[];
}
export interface VectorGraphics {
shapes: VectorShape[];
lines: VectorLine[];
}
export interface VectorShape {
bbox: { x: number; y: number; width: number; height: number };
stroke: boolean;
strokeColor?: string;
fill: boolean;
fillColor?: string;
hasCurve: boolean;
}
export interface VectorLine {
x1: number; y1: number; x2: number; y2: number;
stroke: boolean;
strokeWidth?: number;
strokeColor?: string;
fill: boolean;
fillColor?: string;
}
export interface AnnotationRect {
x: number;
y: number;
width: number;
height: number;
}
export interface DocumentAnnotation {
subtype: string;
contents?: string;
created?: string;
modified?: string;
title?: string;
rect?: AnnotationRect;
quadpointRects: AnnotationRect[];
uri?: string;
}
export interface FormField {
id: string;
type: 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?: AnnotationRect;
options: string[];
selectedOptions: string[];
}
export interface ExtractedImage {
/** Reference id used in the markdown output (e.g. `` → `"p1_1"`). */
id: string;
/** File name used when `imageOutputDir` is configured. */
name: string;
/** Written file path, absent for in-memory-only extraction. */
path?: string;
page: number;
/** Placement on the page in viewport coordinates (top-left origin, 72 DPI). */
bbox: { x: number; y: number; width: number; height: number };
/** Intrinsic pixel dimensions of the image resource. */
width: number;
height: number;
/** Clockwise page-object rotation in degrees. */
rotation: number;
format: string;
/** First occurrence with identical encoded source data, when duplicated. */
duplicateOf?: string;
bytes: Buffer;
}
export interface ParseResult {
/** Total source-document pages before `targetPages` or `maxPages` filtering. */
totalPages: number;
pages: ParsedPage[];
/** Page-level PDFium extraction failures when tolerance is enabled. */
pageErrors: Array<{ pageNum: number; message: string }>;
text: string;
/** Populated only when `extractImages` is true. */
images: ExtractedImage[];
/** PNG screenshots of parsed pages when `extractScreenshots` is enabled. */
screenshots: ScreenshotResult[];
/** Embedded image objects that PDFium could not render or encode. */
imageErrorCount: number;
/** PDFium form type, present only when `extractFormFields` is enabled. */
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 from PDFium and the source PDF.
* Present only when `extractDocumentMetadata` is enabled and the input was
* a real PDF (not converted from DOCX/XLSX/an image).
*/
docMeta?: DocumentMetadata;
/** Raw XFA packets; present only when `extractXfaPackets` is enabled. */
xfaPackets?: XfaPacket[];
}
export interface ParseBatchOptions {
/** Pages materialized in one batch. Default: 25. */
batchSize?: number;
}
export interface ParseBatch {
/** First source page in this batch (1-indexed). */
startPage: number;
/** Last source page in this batch (1-indexed, inclusive). */
endPage: number;
/** Total source-document pages, before the parser's `maxPages` cap. */
totalPages: number;
result: ParseResult;
}
/** Provenance and tamper-analysis facts extracted from the source PDF. */
export interface DocumentMetadata {
creationDate?: string;
modDate?: string;
/** Encoded PDF version (`14` means PDF 1.4). */
fileVersion?: number;
isEncrypted?: boolean;
securityHandlerRevision?: number;
permissions?: number;
eofSectionCount?: number;
startxrefCount?: number;
trailerIdPairDiffers?: boolean;
rawFileSize?: number;
/**
* The document catalog's `/Metadata` XMP packet, capped at 64 KiB. Absent
* when the document has none, when it is too large to resolve cheaply, or
* in WASM builds.
*/
xmp?: string;
/** True when the catalog's XMP stream exceeded the 64 KiB cap. */
xmpTruncated?: boolean;
signatureCount?: number;
/** False when bytes were appended after a readable signature byte range. */
signatureByteRangeReachesEof?: boolean;
}
/** One raw packet from an XFA form document's `/XFA` array. */
export interface XfaPacket {
index: number;
name?: string;
contentLength: number;
/** Packet content (usually XML), lossily decoded as UTF-8. */
content?: string;
}
export interface ScreenshotResult {
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 with `detectScreenshotRects`. */
rects: ScreenshotRect[];
}
/** One solid rectangle (or line) detected in a rendered page bitmap. */
export interface ScreenshotRect {
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;
}
/**
* Per-page complexity signals from {@link LiteParse.isComplex}, used to decide
* whether a document needs OCR or other advanced parsing.
*/
export interface PageComplexityStats {
pageNumber: number;
textLength: number;
/** Fraction of the page area covered by native text (0–1). */
textCoverage: number;
hasSubstantialImages: boolean;
/**
* Number of counted raster images — inline figures only; full-page
* backgrounds are excluded (see {@link 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
* {@link fullPageImage} for that.
*/
imageCoverage: number;
/**
* Largest single *counted* image's area over page area, clamped to 1. Same
* exclusion as {@link imageCoverage}: a full-page raster contributes 0.
*/
largestImageCoverage: number;
/**
* A single raster covers ≥90% of the page. Full-page backgrounds are excluded
* from the image coverage fields, so this is the only signal that tells a scan
* apart from a blank page — both otherwise report no text and no images.
*/
fullPageImage: boolean;
/**
* Filled vector-outline area not covered by native text, in pt². `undefined`
* when a cheaper signal already decided the page, so this walk was skipped.
*/
uncoveredVectorArea?: number;
isGarbled: boolean;
pageArea: number;
/** Verdict: whether this page needs more than the cheap text-only path. */
needsOcr: boolean;
/**
* Every reason the page was flagged (e.g. `"scanned"`, `"sparse-text"`,
* `"garbled"`). Empty exactly when `needsOcr` is false. This is the value to
* route on; new reasons may be added over time.
*/
reasons: string[];
/**
* Layout-difficulty signals (columns, tables, dense graphics). Orthogonal to
* `needsOcr`: none of these imply OCR — they signal that the text-only path
* may mangle reading order or structure. Present in `isComplex()` results
* and `includeComplexity` parses.
*/
layout?: LayoutComplexityStats;
}
/**
* Layout-difficulty signals for one page, computed from the real
* grid-projection pass.
*/
export interface LayoutComplexityStats {
/** Side-by-side text columns found by the layout pass (1 = single column). */
columnCount: number;
/** Ruled-table grids detected on the page. */
ruledTableCount: number;
/** Combined ruled-table area over page area, clamped to 1. */
ruledTableCoverage: number;
/**
* Borderless table runs found by track-aligned text detection (description
* lists excluded). Ruled tables can appear here too — don't sum with
* `ruledTableCount`; the two discriminate ruled from borderless.
*/
textTableRunCount: number;
/** Figure regions clustered from vector graphics. */
figureCount: number;
/** Combined figure area over page area, clamped to 1. */
figureCoverage: number;
/** Verdict: whether any layout reason fired. */
isComplex: boolean;
/**
* Every layout reason (e.g. `"multi-column"`, `"table-likely"`,
* `"dense-graphics"`). Empty exactly when `isComplex` is false; new reasons
* may be added over time.
*/
reasons: string[];
}
// ---------------------------------------------------------------------------
// LiteParse class
// ---------------------------------------------------------------------------
export class LiteParse {
private _native: LiteParseNative;
private _config: LiteParseConfig;
private _pool: WorkerPool | null = null;
constructor(userConfig: Partial<LiteParseConfig> & PoolOptions = {}) {
const nativeConfig: LiteParseNativeConfig = {
ocrLanguage: userConfig.ocrLanguage,
ocrEnabled: userConfig.ocrEnabled,
ocrServerUrl: userConfig.ocrServerUrl,
ocrServerHeaders: userConfig.ocrServerHeaders,
tessdataPath: userConfig.tessdataPath,
maxPages: userConfig.maxPages,
targetPages: userConfig.targetPages,
extractScreenshots: userConfig.extractScreenshots,
continueOnPageError: userConfig.continueOnPageError,
dpi: userConfig.dpi,
outputFormat: userConfig.outputFormat,
imageMode: userConfig.imageMode,
extractImages: userConfig.extractImages,
imageOutputDir: userConfig.imageOutputDir,
extractLinks: userConfig.extractLinks,
keepHeadersFooters: userConfig.keepHeadersFooters,
extractAnnotations: userConfig.extractAnnotations,
extractFormFields: userConfig.extractFormFields,
extractStructureTree: userConfig.extractStructureTree,
extractBlocks: userConfig.extractBlocks,
extractXfaPackets: userConfig.extractXfaPackets,
extractDocumentMetadata: userConfig.extractDocumentMetadata,
extractContentBounds: userConfig.extractContentBounds,
detectScreenshotRects: userConfig.detectScreenshotRects,
renderFormFields: userConfig.renderFormFields,
preserveVerySmallText: userConfig.preserveVerySmallText,
password: userConfig.password,
quiet: userConfig.quiet,
numWorkers: userConfig.numWorkers,
ocrFailureFatal: userConfig.ocrFailureFatal,
ocrHedgeDelaysMs: userConfig.ocrHedgeDelaysMs,
emitWordBoxes: userConfig.emitWordBoxes,
extractTextMetadata: userConfig.extractTextMetadata,
cropBox: userConfig.cropBox,
skipDiagonalText: userConfig.skipDiagonalText,
pageOrientationCorrections: userConfig.pageOrientationCorrections,
includeComplexity: userConfig.includeComplexity,
extractVectorGraphics: userConfig.extractVectorGraphics,
};
this._native = new native.LiteParse(nativeConfig);
if (
userConfig.parseTimeoutMs !== undefined &&
userConfig.poolSize === undefined
) {
throw new Error(
"parseTimeoutMs requires poolSize"
);
}
if (userConfig.poolSize !== undefined) {
this._pool = new WorkerPool(
nativeConfig as unknown as Record<string, unknown>,
userConfig.poolSize,
userConfig.parseTimeoutMs,
);
}
// Read back the resolved config from the native side
const resolved = this._native.config;
this._config = {
ocrLanguage: resolved.ocrLanguage ?? "eng",
ocrEnabled: resolved.ocrEnabled ?? true,
ocrServerUrl: resolved.ocrServerUrl ?? undefined,
ocrServerHeaders: resolved.ocrServerHeaders ?? undefined,
tessdataPath: resolved.tessdataPath ?? undefined,
maxPages: resolved.maxPages ?? 1000,
targetPages: resolved.targetPages ?? undefined,
extractScreenshots: resolved.extractScreenshots ?? false,
continueOnPageError: resolved.continueOnPageError ?? false,
dpi: resolved.dpi ?? 150,
outputFormat: (resolved.outputFormat as OutputFormat) ?? "json",
imageMode: (resolved.imageMode as ImageMode) ?? "placeholder",
extractImages: resolved.extractImages ?? false,
imageOutputDir: resolved.imageOutputDir ?? undefined,
extractLinks: resolved.extractLinks ?? true,
keepHeadersFooters: resolved.keepHeadersFooters ?? false,
extractAnnotations: resolved.extractAnnotations ?? false,
extractFormFields: resolved.extractFormFields ?? false,
extractStructureTree: resolved.extractStructureTree ?? false,
extractBlocks: resolved.extractBlocks ?? false,
extractXfaPackets: resolved.extractXfaPackets ?? false,
extractDocumentMetadata: resolved.extractDocumentMetadata ?? false,
extractContentBounds: resolved.extractContentBounds ?? false,
detectScreenshotRects: resolved.detectScreenshotRects ?? false,
renderFormFields: resolved.renderFormFields ?? false,
preserveVerySmallText: resolved.preserveVerySmallText ?? false,
password: resolved.password ?? undefined,
quiet: resolved.quiet ?? false,
numWorkers: resolved.numWorkers ?? 1,
ocrFailureFatal: resolved.ocrFailureFatal ?? true,
ocrHedgeDelaysMs: resolved.ocrHedgeDelaysMs ?? [],
emitWordBoxes: resolved.emitWordBoxes ?? false,
extractTextMetadata: resolved.extractTextMetadata ?? false,
cropBox: resolved.cropBox ?? undefined,
skipDiagonalText: resolved.skipDiagonalText ?? false,
pageOrientationCorrections:
(resolved.pageOrientationCorrections as PageOrientationCorrection[] | undefined) ?? undefined,
includeComplexity: resolved.includeComplexity ?? false,
extractVectorGraphics: resolved.extractVectorGraphics ?? false,
};
}
async parse(input: LiteParseInput): Promise<ParseResult> {
// Convert Uint8Array to Buffer for the native side
const nativeInput =
typeof input === "string" ? input : Buffer.from(input);
if (this._pool !== null) {
const source =
typeof nativeInput === "string"
? nativeInput
: `<${nativeInput.byteLength} bytes>`;
return this._pool.parse(nativeInput, source);
}
const result: NativeParseResult = await this._native.parse(nativeInput);
return toParseResult(result);
}
/**
* 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.
*/
async warmUp(): Promise<void> {
if (this._pool !== null) await this._pool.warmUp();
}
/**
* 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 {
if (this._pool !== null) this._pool.close();
}
/**
* Parse a document in bounded-memory page batches of `batchSize` pages.
*
* Each yielded result is independent and becomes collectible once the caller
* advances the iterator, so a consumer that does not retain batches never
* holds more than one batch of pages in memory. A non-PDF source is
* converted once when the iterator starts, not once per batch; its temporary
* file is released when iteration ends — including an early `break` or
* `throw`, which run the generator's cleanup.
*
* Cross-page passes see only the pages in their own batch, so repeated
* header/footer removal and image deduplication are batch-local and the
* output can differ from `parse()`. Prefer `parse()` unless the size of the
* materialized result is the problem.
*
* As with any async generator, work starts on the first `next()` call, so
* errors (an unreadable file, or a parser configured with `targetPages` —
* ambiguous with generated batch ranges) surface on the first iteration
* rather than when `parseBatches()` itself is called.
*/
async *parseBatches(
input: LiteParseInput,
options: ParseBatchOptions = {},
): AsyncGenerator<ParseBatch> {
const nativeInput = typeof input === "string" ? input : Buffer.from(input);
const session = await this._native.openBatchSession(
nativeInput,
options.batchSize,
);
try {
const totalPages = session.totalPages;
for (;;) {
const batch = await session.nextBatch();
if (batch == null) {
return;
}
yield {
startPage: batch.startPage,
endPage: batch.endPage,
totalPages,
result: toParseResult(batch.result),
};
}
} finally {
// Frees the session's converted-PDF temp file now instead of at GC —
// this runs on normal exhaustion and when the consumer abandons the
// loop early.
await session.close();
}
}
/**
* Parse from pre-extracted pages, skipping PDFium text extraction. Runs only
* grid projection + the configured output formatter, so the caller's own
* text-extraction / font-recovery owns the text content. Synchronous: no
* PDFium load and no OCR on this path.
*/
parsePages(pages: PageInput[]): ParseResult {
const nativePages: NativePageInput[] = pages.map((p) => ({
pageNumber: p.pageNumber,
pageWidth: p.pageWidth,
pageHeight: p.pageHeight,
textItems: p.textItems,
graphics: p.graphics,
}));
const result = this._native.parsePages(nativePages);
return toParseResult(result);
}
/**
* Determine per-page complexity without running a full parse. Returns one
* entry per page with signals and a `needsOcr` verdict — a cheap pre-OCR
* check to decide whether a document needs advanced parsing.
*/
async isComplex(input: LiteParseInput): Promise<PageComplexityStats[]> {
const nativeInput =
typeof input === "string" ? input : Buffer.from(input);
const stats: NativePageComplexityStats[] =
await this._native.isComplex(nativeInput);
return stats.map(toComplexity);
}
async screenshot(
input: LiteParseInput,
pageNumbers?: number[],
): Promise<ScreenshotResult[]> {
const nativeInput =
typeof input === "string" ? input : Buffer.from(input);
const results = await this._native.screenshot(
nativeInput,
pageNumbers ?? null,
);
return results.map((r) => ({
pageNum: r.pageNum,
width: r.width,
height: r.height,
imageBuffer: r.imageBuffer,
isSolidFill: r.isSolidFill,
rects: r.rects,
}));
}
getConfig(): LiteParseConfig {
return { ...this._config };
}
}
function toComplexity(s: NativePageComplexityStats): PageComplexityStats {
return {
pageNumber: s.pageNumber,
textLength: s.textLength,
textCoverage: s.textCoverage,
hasSubstantialImages: s.hasSubstantialImages,
imageBlockCount: s.imageBlockCount,
imageCoverage: s.imageCoverage,
largestImageCoverage: s.largestImageCoverage,
fullPageImage: s.fullPageImage,
uncoveredVectorArea: s.uncoveredVectorArea ?? undefined,
isGarbled: s.isGarbled,
pageArea: s.pageArea,
needsOcr: s.needsOcr,
reasons: s.reasons,
layout: s.layout
? {
columnCount: s.layout.columnCount,
ruledTableCount: s.layout.ruledTableCount,
ruledTableCoverage: s.layout.ruledTableCoverage,
textTableRunCount: s.layout.textTableRunCount,
figureCount: s.layout.figureCount,
figureCoverage: s.layout.figureCoverage,
isComplex: s.layout.isComplex,
reasons: s.layout.reasons,
}
: undefined,
};
}
/** @internal Exported for pool-worker.ts only; not public API. */
export function toParseResult(result: NativeParseResult): ParseResult {
return {
totalPages: result.totalPages,
pages: result.pages.map(toPage),
pageErrors: result.pageErrors ?? [],
text: result.text,
images: (result.images ?? []).map(toImage),
screenshots: (result.screenshots ?? []).map(toScreenshot),
imageErrorCount: result.imageErrorCount ?? 0,
formType: result.formType,
creator: result.creator,
producer: result.producer,
docMeta: result.docMeta,
xfaPackets: result.xfaPackets,
};
}
function toPage(p: NativeParsedPage): ParsedPage {
return {
pageNum: p.pageNum,
pageLabel: p.pageLabel ?? undefined,
width: p.width,
height: p.height,
contentBounds: p.contentBounds,
text: p.text,
markdown: p.markdown,
textItems: p.textItems.map(toTextItem),
complexity: p.complexity ? toComplexity(p.complexity) : undefined,
vectorGraphics: p.vectorGraphics ?? undefined,
annotations: p.annotations,
formFields: p.formFields?.map((field) => ({
id: field.id,
type: field.fieldType,
page: field.page,
annotationIndex: field.annotationIndex,
widgetIndex: field.widgetIndex,
objectNumber: field.objectNumber,
name: field.name,
alternateName: field.alternateName,
value: field.value,
exportValue: field.exportValue,
fieldFlags: field.fieldFlags,
controlCount: field.controlCount,
controlIndex: field.controlIndex,
checked: field.checked,
rect: field.rect,
options: field.options,
selectedOptions: field.selectedOptions,
})),
structureTree: p.structureTree
? { roots: p.structureTree.roots.map(toStructureTreeElement) }
: undefined,
blocks: p.blocks as LayoutBlock[] | undefined,
};
}
function toStructureTreeElement(
element: NativeStructureTreeElement,
): StructureTreeElement {
const attributes: Record<string, StructureAttributeValue> = {};
for (const attribute of element.attributes) {
if (attribute.booleanValue !== undefined) {
attributes[attribute.name] = attribute.booleanValue;
} else if (attribute.numberValue !== undefined) {
attributes[attribute.name] = attribute.numberValue;
} else if (attribute.stringValue !== undefined) {
attributes[attribute.name] = attribute.stringValue;
}
}
return {
type: element.elementType,
id: element.id,
actualText: element.actualText,
altText: element.altText,
title: element.title,
attributes,
markedContentIds: element.markedContentIds,
children: element.children.map(toStructureTreeElement),
annotations: element.annotations,
};
}
function toImage(img: NativeExtractedImage): ExtractedImage {
return {
id: img.id,
name: img.name,
path: img.path,
page: img.page,
bbox: img.bbox,
width: img.width,
height: img.height,
rotation: img.rotation,
format: img.format,
duplicateOf: img.duplicateOf,
bytes: img.bytes,
};
}
function toScreenshot(result: NativeScreenshotResult): ScreenshotResult {
return {
pageNum: result.pageNum,
width: result.width,
height: result.height,
imageBuffer: result.imageBuffer,
isSolidFill: result.isSolidFill,
rects: result.rects,
};
}
function toTextItem(item: NativeTextItem): TextItem {
return {
text: item.text,
x: item.x,
y: item.y,
width: item.width,
height: item.height,
fontName: item.fontName,
fontSize: item.fontSize,
fontHeight: item.fontHeight,
fontAscent: item.fontAscent,
fontDescent: item.fontDescent,
fontWeight: item.fontWeight,
textWidth: item.textWidth,
fontIsBuggy: item.fontIsBuggy,
mcid: item.mcid,
fillColor: item.fillColor,
strokeColor: item.strokeColor,
charCodes: item.charCodes,
trailingSpaceGenerated: item.trailingSpaceGenerated,
confidence: item.confidence,
rotation: item.rotation,
words: item.words,
};
}
// ---------------------------------------------------------------------------
// searchItems — standalone utility
// ---------------------------------------------------------------------------
export interface SearchItemsOptions {
phrase: string;
caseSensitive?: boolean;
}
export function searchItems(
items: TextItem[],
options: SearchItemsOptions,
): TextItem[] {
const nativeResults = native.searchItems(
items,
options.phrase,
options.caseSensitive ?? false,
);
return nativeResults.map(toTextItem);
}
export default LiteParse;