Node.js API Reference
The pdf-oxide npm package provides a native N-API addon with full TypeScript type definitions. Prebuilt platform binaries ship via per-platform subpackages, and a thin TypeScript layer adds the class-based, manager, builder, and stream APIs documented below.
npm install pdf-oxide
For the WASM build targeting browsers / Deno / Bun / edge runtimes, see WASM API Reference. For other languages see Python, Golang, C#, or Rust.
Package exports
import {
// Core
PdfDocument, Pdf, DocumentEditor,
// Write-side fluent API
DocumentBuilder, PageBuilder, EmbeddedFont, PdfBuilder,
// Managers
ExtractionManager, SearchManager, MetadataManager, OutlineManager,
AnnotationManager, EditingManager, FormFieldManager, XfaManager,
RenderingManager, ThumbnailManager, RenderOptions,
SecurityManager, ComplianceManager, AccessibilityManager,
OptimizationManager, LayerManager, BarcodeManager, BatchManager,
CacheManager, EnterpriseManager, HybridMLManager,
ResultAccessorsManager, OcrManager, SignatureManager,
// Builders
AnnotationBuilder, MetadataBuilder, SearchOptionsBuilder,
ConversionOptionsBuilder, StreamingTable,
// Streams & workers
SearchStream, ExtractionStream, MetadataStream,
createSearchStream, createExtractionStream, createMetadataStream,
WorkerPool, workerPool,
// Signatures / timestamps
Timestamp, TimestampHashAlgorithm, TsaClient, signPdfBytesPades,
// Value types & enums
Rect, Point, Color, PageSize,
// Errors
PdfError, PdfException,
} from "pdf-oxide";
All native-backed classes expose close() (and Symbol.dispose where appropriate) — use using (Node.js 22+) for automatic cleanup.
Top-level functions
getVersion(): string // binding version string
getPdfOxideVersion(): string // underlying Rust core version
getActiveCryptoProvider(): string // active crypto backend name
isFipsCryptoAvailable(): boolean
useFipsCryptoProvider(): void // switch to the FIPS provider
// Runtime crypto governance (#230)
setCryptoPolicy(spec: string): void // "compat" | "strict" | "fips-strict"[;…]
cryptoPolicy(): string // active policy as its grammar string
cryptoInventory(): string[] // algorithm tokens used this process
cryptoCbom(): string // CycloneDX 1.6 crypto BOM (JSON)
// OCR model provisioning (process-wide, no handle)
prefetchModels(languages?: string[]): string // download models, returns cache dir
modelManifest(): string // air-gapped model manifest (JSON)
prefetchAvailable(): boolean // true if built with `ocr` feature
// Barcode helpers
generateBarcodeSvg(data: string, format?: number, sizePx?: number): string
generateQrCodeSvg(data: string, errorCorrection?: number, sizePx?: number): string
// PAdES signing of raw bytes (#235)
signPdfBytesPades(
pdfData: Buffer | Uint8Array,
cert: { certPem: string; keyPem: string } | { pkcs12: Buffer | Uint8Array; password: string },
level: PadesLevelValue,
opts?: { tsaUrl?: string; reason?: string; location?: string; revocation?: object }
): Buffer
// Stream factories (see Streams)
createSearchStream(manager, term, options?): SearchStream
createExtractionStream(manager, startPage, endPage, type?, options?): ExtractionStream
createMetadataStream(manager, startPage, endPage): MetadataStream
// Error utilities
wrapError(error): PdfError
wrapMethod(fn): Function
wrapAsyncMethod(fn): Function
mapFfiErrorCode(code: number): typeof PdfError
PdfDocument
Read-only access to PDF documents, plus conversion and rendering.
Constructors
PdfDocument.open(path: string): PdfDocument
PdfDocument.openFromBuffer(data: Buffer | Uint8Array): PdfDocument
PdfDocument.openWithPassword(path: string, password: string): PdfDocument
PdfDocument.openFromDocxBytes(data: Buffer | Uint8Array): PdfDocument // Office → PDF in memory
PdfDocument.openFromPptxBytes(data: Buffer | Uint8Array): PdfDocument
PdfDocument.openFromXlsxBytes(data: Buffer | Uint8Array): PdfDocument
Document info
pageCount(): number
getPageCount(): number
getVersion(): { major: number; minor: number }
hasStructureTree(): boolean
hasXFA(): boolean
hasDocumentTimestamp(): boolean
getDocumentSecurityStore(): DocumentSecurityStore | null
getPageWidth(pageIndex: number): number
getPageHeight(pageIndex: number): number
getPageRotation(pageIndex: number): number
close(): void
Pages
page(index: number): Page // lightweight lazy page handle (see Page)
Text extraction
extractText(pageIndex: number): string
extractTextAsync(pageIndex: number): Promise<string>
extractAllText(): string
extractWords(pageIndex: number): Word[]
extractTextLines(pageIndex: number): TextLine[]
extractTables(pageIndex: number): Table[]
extractPaths(pageIndex: number): Path[]
classifyPage(pageIndex: number): string // page content classification
classifyDocument(): string // whole-document classification
extractTextAuto(pageIndex: number): string // auto OCR-or-text per page
extractPageAuto(pageIndex: number, optionsJson?: string): string
ocrExtractText(pageIndex: number, engineHandle: any): string
Conversion
toMarkdown(pageIndex: number, options?: ConversionOptions): string
toMarkdownAsync(pageIndex: number, options?: ConversionOptions): Promise<string>
toMarkdownAll(options?: ConversionOptions): string
toHtml(pageIndex: number, options?: ConversionOptions): string
toHtmlAll(options?: ConversionOptions): string
toPlainText(pageIndex: number): string
toPlainTextAll(): string
toDocxBytes(): Buffer // PDF → DOCX (round-trip)
toPptxBytes(): Buffer
toXlsxBytes(): Buffer
Resources & structure
getFormFields(): FormField[]
getOutline(): OutlineItem[]
getPageAnnotations(pageIndex: number): AnnotationInfo[]
getEmbeddedFonts(pageIndex: number): FontInfo[]
getEmbeddedImages(pageIndex: number): ImageInfo[]
planSplitByBookmarks(options?: SplitByBookmarksOptions): SplitSegment[]
Search
searchPage(pageIndex: number, query: string, caseSensitive?: boolean): SearchResult[]
searchAll(query: string, caseSensitive?: boolean): SearchResult[]
Rendering
renderPageWithOptions(pageIndex: number, options?: RenderOptions): Uint8Array
renderPageWithOptionsAsync(pageIndex: number, options?: RenderOptions): Promise<Uint8Array>
renderPageFit(pageIndex: number, width: number, height: number, format?: "png" | "jpeg"): Uint8Array
renderPageFitAsync(pageIndex: number, width: number, height: number, format?: "png" | "jpeg"): Promise<Uint8Array>
renderToPixmap(pageIndex: number, dpi?: number): RgbaPixmap
renderToPixmapAsync(pageIndex: number, dpi?: number): Promise<RgbaPixmap>
estimateRenderTime(pageIndex: number, dpi?: number): number
RenderOptions (object literal): { dpi?, format?: "png" | "jpeg", jpegQuality?, background?: [r,g,b,a], renderAnnotations?, transparentBackground? }.
Compliance
validatePdfA(level?: "1a" | "1b" | "2a" | "2b" | "2u" | "3a" | "3b" | "3u"): { compliant: boolean; errors: string[]; warnings: string[] }
convertToPdfA(level?: "1a" | "1b" | "2a" | "2b" | "2u" | "3a" | "3b" | "3u"): boolean
toBuffer(): Buffer
Page
A lightweight lazy page handle returned by doc.page(index). Each method dispatches to the parent document.
class Page {
readonly index: number;
readonly width: number;
readonly height: number;
text(): string;
markdown(): string;
html(): string;
plainText(): string;
words(): Word[];
lines(): TextLine[];
tables(): Table[];
images(): ImageInfo[];
paths(): Path[];
annotations(): AnnotationInfo[];
fonts(): FontInfo[];
search(query: string, caseSensitive?: boolean): SearchResult[];
toString(): string;
}
Pdf — creation
Create PDFs from various source formats.
Pdf.fromMarkdown(markdown: string): Pdf
Pdf.fromHtml(html: string): Pdf
Pdf.fromText(text: string): Pdf
Pdf.fromImage(path: string): Pdf
Pdf.fromImageBytes(data: Buffer | Uint8Array): Pdf
Pdf.fromHtmlCss(html: string, css: string, fontBytes: Buffer | Uint8Array): Pdf
Pdf.fromHtmlCssWithFonts(html: string, css: string, fonts: [string, Buffer | Uint8Array][]): Pdf
save(path: string): void
saveToBytes(): Buffer
pageCount(): number
close(): void
DocumentBuilder / PageBuilder / EmbeddedFont
Fluent, low-level document authoring with embedded fonts, annotations, AcroForm widgets, tables, and graphics.
EmbeddedFont
EmbeddedFont.fromFile(path: string): EmbeddedFont
EmbeddedFont.fromBytes(data: Buffer | Uint8Array, name?: string): EmbeddedFont
markConsumed(): void
close(): void
DocumentBuilder
DocumentBuilder.create(): DocumentBuilder
// Metadata & document setup
title(title: string): this
author(author: string): this
subject(subject: string): this
keywords(keywords: string): this
creator(creator: string): this
onOpen(script: string): this // document-open JavaScript
taggedPdfUa1(): this // emit Tagged PDF / PDF-UA-1
language(lang: string): this
roleMap(custom: string, standard: string): this
registerEmbeddedFont(name: string, font: EmbeddedFont): this
// Page factories — return a PageBuilder
a4Page(): PageBuilder
letterPage(): PageBuilder
page(width: number, height: number): PageBuilder
// Output
build(): Buffer
save(path: string): void
saveEncrypted(path: string, userPassword: string, ownerPassword: string): void
toBytesEncrypted(userPassword: string, ownerPassword: string): Buffer
clearOpenPage(): void
close(): void
PageBuilder
Returned by a4Page() / letterPage() / page(w, h). Returns to the parent with done().
// Text & layout
font(name: string, size: number): this
at(x: number, y: number): this
text(text: string): this
heading(level: number, text: string): this
paragraph(text: string): this
space(points: number): this
horizontalRule(): this
columns(columnCount: number, gapPt: number, text: string): this
footnote(refMark: string, noteText: string): this
newline(): this
newPageSameSize(): this
// Inline runs
inline(text: string): this
inlineBold(text: string): this
inlineItalic(text: string): this
inlineColor(r: number, g: number, b: number, text: string): this
// Link annotations
linkUrl(url: string): this
linkPage(pageIndex: number): this
linkNamed(destination: string): this
linkJavascript(script: string): this
// Document/field JavaScript actions
onOpen(script: string): this
onClose(script: string): this
fieldKeystroke(script: string): this
fieldFormat(script: string): this
fieldValidate(script: string): this
fieldCalculate(script: string): this
// Markup annotations
highlight(r: number, g: number, b: number): this
underline(r: number, g: number, b: number): this
strikeout(r: number, g: number, b: number): this
squiggly(r: number, g: number, b: number): this
stickyNote(text: string): this
stickyNoteAt(x: number, y: number, text: string): this
freeText(x: number, y: number, w: number, h: number, text: string): this
stamp(typeName: string): this
watermark(text: string): this
watermarkConfidential(): this
watermarkDraft(): this
// AcroForm widgets
textField(name: string, x: number, y: number, w: number, h: number, defaultValue?: string): this
checkbox(name: string, x: number, y: number, w: number, h: number, checked?: boolean): this
comboBox(name: string, x: number, y: number, w: number, h: number, options: string[], selected?: string): this
radioGroup(name: string, buttons: { value: string; x: number; y: number; w: number; h: number }[], selected?: string): this
pushButton(name: string, x: number, y: number, w: number, h: number, caption: string): this
signatureField(name: string, x: number, y: number, w: number, h: number): this
// Barcodes & images
barcode1d(barcodeType: number, data: string, x: number, y: number, w: number, h: number): this
barcodeQr(data: string, x: number, y: number, size: number): this
image(bytes: Buffer | Uint8Array, x: number, y: number, w: number, h: number): this
imageWithAlt(bytes: Buffer | Uint8Array, x: number, y: number, w: number, h: number, altText: string): this
imageArtifact(bytes: Buffer | Uint8Array, x: number, y: number, w: number, h: number): this
// Graphics primitives
rect(x: number, y: number, w: number, h: number): this
filledRect(x: number, y: number, w: number, h: number, r: number, g: number, b: number): this
strokeRect(x: number, y: number, w: number, h: number, lineWidth: number, r: number, g: number, b: number): this
line(x1: number, y1: number, x2: number, y2: number): this
// Tables
table(spec: TableSpec): this
done(): DocumentBuilder
PdfBuilder
High-level, metadata-first document builder that produces a Pdf from a source format.
PdfBuilder.create(): PdfBuilder
title(title: string): this
author(author: string): this
subject(subject: string): this
keywords(keywords: string[]): this
addKeyword(keyword: string): this
pageSize(pageSize: string): this
margins(top: number, right: number, bottom: number, left: number): this
fromMarkdown(markdown: string): Pdf
fromHtml(html: string): Pdf
fromText(text: string): Pdf
fromHtmlCss(html: string, css: string, fontBytes: Buffer | Uint8Array): Pdf
fromMarkdownAsync(markdown: string): Promise<Pdf>
fromHtmlAsync(html: string): Promise<Pdf>
fromTextAsync(text: string): Promise<Pdf>
DocumentEditor
In-place mutation: pages, metadata, forms, annotations, redaction, and encrypted save.
Constructors
DocumentEditor.open(path: string): DocumentEditor
DocumentEditor.openFromBytes(data: Buffer | Uint8Array): DocumentEditor
Info & metadata
pageCount(): number
isModified(): boolean
setTitle(title: string): void
setAuthor(author: string): void
setSubject(subject: string): void
getKeywords(): string | null
setKeywords(keywords: string): void
getProducer(): string
setProducer(producer: string): void
getCreationDate(): string
setCreationDate(date: string): void
Page operations
deletePage(pageIndex: number): void
movePage(fromIndex: number, toIndex: number): void
setPageRotation(pageIndex: number, degrees: 0 | 90 | 180 | 270): void
rotateAllPages(degrees: number): void
rotatePageBy(pageIndex: number, degrees: number): void
getPageMediaBox(pageIndex: number): [number, number, number, number]
setPageMediaBox(pageIndex: number, x: number, y: number, width: number, height: number): void
getPageCropBox(pageIndex: number): [number, number, number, number]
setPageCropBox(pageIndex: number, x: number, y: number, width: number, height: number): void
eraseRegions(pageIndex: number, rects: [number, number, number, number][]): void
clearEraseRegions(pageIndex: number): void
Forms & annotations
flattenForms(): void
flattenFormsOnPage(pageIndex: number): void
flattenAnnotations(pageIndex?: number): void
flattenWarnings(): string[]
setFormFieldValue(fieldName: string, value: string): void
importFdfBytes(fdf: Buffer | Uint8Array): void
importXfdfBytes(xfdf: Buffer | Uint8Array): void
isPageMarkedForFlatten(pageIndex: number): boolean
unmarkPageForFlatten(pageIndex: number): void
Redaction & merge
applyPageRedactions(pageIndex: number): void
applyAllRedactions(): void
isPageMarkedForRedaction(pageIndex: number): boolean
unmarkPageForRedaction(pageIndex: number): void
mergeFrom(sourcePath: string): void
mergeFromBytes(data: Buffer | Uint8Array): number
embedFile(name: string, data: Buffer | Uint8Array): void
Save
save(path: string): void
saveEncrypted(path: string, userPassword: string, ownerPassword: string): void
saveToBytes(): Buffer
saveToBytesWithOptions(compress: boolean, garbageCollect: boolean, linearize: boolean): Buffer
extractPagesToBytes(pageIndices: number[]): Buffer
close(): void
Managers
The manager classes wrap a PdfDocument (new XManager(doc)) and group related operations. Most accessor methods are async. Many managers also expose clearCache() / getCacheStats() and destroy().
ExtractionManager
new ExtractionManager(doc: PdfDocument)
extractText(pageIndex: number, options?: object): string
extractAllText(options?: object): string
extractTextBatch(pageIndices: number[], options?: object): string
extractMarkdown(pageIndex: number, options?: object): string
extractAllMarkdown(options?: object): string
getPageWordCount(pageIndex: number): number
getTotalWordCount(): number
getPageCharacterCount(pageIndex: number): number
getTotalCharacterCount(): number
getPageLineCount(pageIndex: number): number
getContentStatistics(): ContentStatistics
searchContent(searchText: string, contextLength?: number): SearchMatch[]
SearchManager
new SearchManager(doc: PdfDocument)
search(searchText: string, pageIndex: number, options?: object): SearchResult[]
searchAll(searchText: string, options?: object): SearchResult[]
countOccurrences(searchText: string, pageIndex: number, options?: object): number
countAllOccurrences(searchText: string, options?: object): number
contains(searchText: string, pageIndex: number, options?: object): boolean
containsAnywhere(searchText: string, options?: object): boolean
getPagesContaining(searchText: string, options?: object): number[]
getSearchStatistics(searchText: string, options?: object): SearchStatistics
findFirst(searchText: string, options?: object): SearchResult | null
findLast(searchText: string, options?: object): SearchResult | null
highlightMatches(searchText: string, options?: object): SearchResult[]
isSearchable(): boolean
getCapabilities(): SearchCapabilities
MetadataManager
new MetadataManager(doc: PdfDocument)
getTitle(): string | null
getAuthor(): string | null
getSubject(): string | null
getKeywords(): string[]
getCreator(): string | null
getProducer(): string | null
getCreationDate(): Date | null
getModificationDate(): Date | null
getAllMetadata(): Record<string, any>
hasMetadata(): boolean
getMetadataSummary(): string
hasKeyword(keyword: string): boolean
getKeywordCount(): number
compareWith(otherDocument: PdfDocument): MetadataComparison
validate(): ValidationResult
OutlineManager
new OutlineManager(doc: PdfDocument)
hasOutlines(): boolean
getOutlineCount(): number
getOutlines(): OutlineItem[]
findByTitle(titleFragment: string): OutlineItem | null
findAllByTitle(titleFragment: string): OutlineItem[]
getOutlinesForPage(pageIndex: number): OutlineItem[]
pageHasOutlines(pageIndex: number): boolean
getOutlineAt(index: number): OutlineItem | null
containsPageNumber(pageNumber: number): boolean
AnnotationManager
new AnnotationManager(doc: PdfDocument)
getAnnotations(): Annotation[]
getAnnotationsByType(type: string): Annotation[]
getAnnotationCount(): number
getAnnotationsByAuthor(author: string): Annotation[]
getAnnotationAuthors(): string[]
getAnnotationsAfter(date: Date): Annotation[]
getAnnotationsBefore(date: Date): Annotation[]
getAnnotationsWithContent(contentFragment: string): Annotation[]
getHighlights(): Annotation[]
getComments(): Annotation[]
getUnderlines(): Annotation[]
getStrikeouts(): Annotation[]
getSquigglies(): Annotation[]
getAnnotationStatistics(): AnnotationStatistics
getRecentAnnotations(days: number): Annotation[]
generateAnnotationSummary(): string
validateAnnotation(annotation: any): AnnotationValidation
EditingManager
new EditingManager(doc: PdfDocument)
addRedaction(page: number, rect: RedactionRect, color?: RgbColor): void
applyRedactions(options?: ApplyRedactionsOptions): number
getRedactionCount(page?: number): number
scrubMetadata(options?: ScrubMetadataOptions): void
flattenForms(): void
flattenFormsPage(page: number): void
flattenAnnotations(): void
flattenAnnotationsPage(page: number): void
importFormDataFromFile(filePath: string): number
importFdfBytes(data: Buffer): number
importXfdfBytes(data: Buffer): number
exportFormDataToBytes(format?: 0 | 1): Buffer
FormFieldManager
new FormFieldManager(doc: PdfDocument)
getAllFields(): Promise<FormField[]>
getField(fieldName: string): Promise<FormField | undefined>
getFieldsOfType(fieldType: FormFieldType): Promise<FormField[]>
getFieldValue(fieldName: string): Promise<string | undefined>
setFieldValue(fieldName: string, value: string): Promise<void>
getFieldCount(): Promise<number>
hasForm(): Promise<boolean>
createField(config: FormFieldConfig): Promise<void>
removeField(fieldName: string): Promise<void>
flattenForm(): Promise<void>
resetForm(): Promise<void>
getFormAcroform(): Promise<any>
exportFormData(filename: string, format?: number): Promise<number>
exportFormDataBytes(format?: number): Promise<Uint8Array>
importFormData(filename: string): Promise<number>
resetAllFields(): Promise<number>
getFieldDefaultValue(fieldName: string): Promise<string>
setFieldDefaultValue(fieldName: string, value: string): Promise<void>
getFieldFlags(fieldName: string): Promise<number>
setFieldFlags(fieldName: string, flags: number): Promise<void>
getFieldTooltip(fieldName: string): Promise<string>
setFieldTooltip(fieldName: string, tooltip: string): Promise<void>
getFieldAlternateName(fieldName: string): Promise<string>
setFieldAlternateName(fieldName: string, alternateName: string): Promise<void>
isFieldReadonly(fieldName: string): Promise<boolean>
setFieldReadonly(fieldName: string, readonly: boolean): Promise<void>
isFieldRequired(fieldName: string): Promise<boolean>
setFieldRequired(fieldName: string, required: boolean): Promise<void>
getFieldBackgroundColor(fieldName: string): Promise<[number, number, number] | null>
getFieldTextColor(fieldName: string): Promise<[number, number, number] | null>
validateField(fieldName: string): Promise<boolean>
getFormStatistics(): Promise<Record<string, number>>
batchSetValues(values: Record<string, string>): Promise<number>
getBatchValues(fieldNames: string[]): Promise<Record<string, string>>
XfaManager
new XfaManager(doc: PdfDocument)
hasXfa(): boolean
parseXfaForm(): any
extractFieldData(): Record<string, string | undefined>
getDatasetXml(): string
convertToAcroForm(): boolean
getFieldCount(): Promise<number>
getFieldByIndex(index: number): Promise<XFAFormField | null>
getFieldValue(fieldName: string): Promise<string | null>
setFieldValue(fieldName: string, value: string): Promise<boolean>
getFieldType(fieldName: string): Promise<string | null>
isFieldReadOnly(fieldName: string): Promise<boolean>
getFieldBounds(fieldName: string): Promise<[number, number, number, number] | null>
getFormState(): Promise<Record<string, any> | null>
exportData(filePath: string): Promise<boolean>
importData(filePath: string): Promise<boolean>
flattenForm(): Promise<boolean>
createXfaForm(config: XfaTemplateConfig): Promise<XfaCreationResult>
createFromXdpTemplate(xdpContent: string): Promise<XfaCreationResult>
createFromXmlTemplate(xmlTemplate: string): Promise<XfaCreationResult>
addSubform(parentPath: string, config: XfaSubformConfig): Promise<boolean>
removeXfaForm(): Promise<boolean>
addTextField(pageIndex: number, config: XfaFieldConfig): Promise<XfaFieldHandle | null>
updateField(fieldId: string, updates: Partial<XfaFieldConfig>): Promise<boolean>
removeField(fieldId: string): Promise<boolean>
importXfaData(data: string, options: XfaDataOptions): Promise<boolean>
exportXfaData(options: XfaDataOptions): Promise<string | null>
exportAsXdp(): Promise<string | null>
addFieldScript(fieldName: string, script: XfaScriptConfig): Promise<boolean>
addFormScript(script: XfaScriptConfig): Promise<boolean>
RenderingManager & RenderOptions
new RenderOptions(config?: { dpi?: number; format?: "png" | "jpeg"; quality?: number; maxWidth?: number; maxHeight?: number })
RenderOptions.merge(options: RenderOptions | object | null): RenderOptions
RenderOptions.fromQuality(quality: "draft" | "normal" | "high"): RenderOptions
toJSON(): Record<string, any>
new RenderingManager(doc: PdfDocument)
getMaxResolution(): number
getSupportedColorSpaces(): string[]
getPageDimensions(pageIndex: number): PageDimensions
getDisplaySize(pageIndex: number, zoomLevel: number): PageDimensions
getPageRotation(pageIndex: number): number
getPageCropBox(pageIndex: number): PageBox
getPageMediaBox(pageIndex: number): PageBox
getPageBleedBox(pageIndex: number): PageBox
getPageTrimBox(pageIndex: number): PageBox
getPageArtBox(pageIndex: number): PageBox
calculateZoomForWidth(pageIndex: number, viewportWidth: number): number
calculateZoomForHeight(pageIndex: number, viewportHeight: number): number
calculateZoomToFit(pageIndex: number, viewportWidth: number, viewportHeight: number): number
getEmbeddedFonts(pageIndex: number): any[]
getEmbeddedImages(pageIndex: number): any[]
getPageResources(pageIndex: number): PageResources
getRecommendedResolution(quality: "draft" | "normal" | "high"): number
getRenderingStatistics(): RenderingStatistics
canRenderPage(pageIndex: number): boolean
validateRenderingState(): object
ThumbnailManager
new ThumbnailManager(doc: PdfDocument)
generateThumbnail(pageIndex: number, config?: ThumbnailConfig): Promise<Buffer>
generateAllThumbnails(config?: ThumbnailConfig): Promise<Map<number, Buffer>>
getThumbnailInfo(pageIndex: number): Promise<ThumbnailInfo>
preloadThumbnails(config?: ThumbnailConfig): Promise<void>
getStatistics(): ThumbnailStatistics
SecurityManager
new SecurityManager(doc: PdfDocument)
isEncrypted(): boolean
requiresPassword(): boolean
getEncryptionAlgorithm(): string | null
canPrint(): boolean
canCopy(): boolean
canModify(): boolean
canAnnotate(): boolean
canFillForms(): boolean
isViewOnly(): boolean
getPermissionsSummary(): PermissionsSummary
getSecurityLevel(): SecurityLevel
validateAccessibility(): AccessibilityValidation
generateSecurityReport(): string
SecurityManager.setCryptoPolicy(spec: string): void // static
SecurityManager.getCryptoPolicy(): string // static
SecurityManager.cryptoInventory(): string[] // static
SecurityManager.cryptoCbom(): string // static
ComplianceManager
new ComplianceManager(doc: PdfDocument)
getAllIssues(): Promise<ComplianceIssue[]>
getIssuesOfType(type: ComplianceIssueType): Promise<ComplianceIssue[]>
getIssueCount(): Promise<number>
getErrorCount(): Promise<number>
getWarningCount(): Promise<number>
convertToPdfA(level?: string): Promise<boolean>
convertToPdfUA(): Promise<boolean>
getComplianceReport(complianceType?: string): Promise<string>
checkFontEmbedding(): Promise<boolean>
hasFontsEmbedded(): Promise<boolean>
checkColorSpace(): Promise<boolean>
hasValidColorSpace(): Promise<boolean>
checkTaggedContent(): Promise<boolean>
addMissingTags(): Promise<boolean>
fixFontIssues(): Promise<number>
fixColorIssues(): Promise<number>
removeUnsupportedFeatures(): Promise<number>
getComplianceIssues(): Promise<string[]>
getIssueSeverity(issue: string): string
createComplianceReportFile(filePath: string): Promise<boolean>
getComplianceSummary(): Promise<object>
AccessibilityManager
new AccessibilityManager(doc: PdfDocument)
isTagged(): Promise<boolean>
getStructureTree(): Promise<StructureTree>
autoTag(language?: string): Promise<AutoTagResult>
setAltText(page: number, mcid: number, text: string): Promise<void>
setLanguage(lang: string): Promise<void>
setTitle(title: string): Promise<void>
OptimizationManager
new OptimizationManager(doc: PdfDocument)
subsetFonts(): Promise<OptimizationResult>
downsampleImages(dpi?: number, quality?: number): Promise<OptimizationResult>
deduplicate(): Promise<OptimizationResult>
optimizeFull(dpi?: number, quality?: number): Promise<OptimizationResult>
LayerManager
new LayerManager(doc: PdfDocument)
hasLayers(): boolean
getLayerCount(): number
getLayers(): Layer[]
getLayerByName(name: string): Layer | null
getLayerById(id: string): Layer | null
getRootLayers(): Layer[]
getLayerHierarchy(): LayerHierarchy
getChildLayers(parentId: string): Layer[]
getParentLayer(layerId: string): Layer | null
isLayerVisible(layerId: string): boolean
getVisibilityChain(layerId: string): Layer[]
getLayerUsages(): Record<string, number>
getLayerStatistics(): LayerStatistics
findLayersByPattern(pattern: RegExp | string): Layer[]
validateLayerState(): LayerValidation
BarcodeManager
new BarcodeManager(doc: PdfDocument)
detectBarcodes(pageIndex: number): Promise<DetectedBarcode[]>
detectAllBarcodes(): Promise<Map<number, DetectedBarcode[]>>
getBarcodesOfFormat(format: BarcodeFormat, pageIndex?: number): Promise<DetectedBarcode[]>
getBarcodeCount(): Promise<number>
getCountByFormat(format: BarcodeFormat): Promise<number>
hasBarcode(pageIndex: number): Promise<boolean>
generateBarcode(data: string, config?: BarcodeGenerationConfig): Promise<Buffer>
generateSvg(data: string, config?: BarcodeGenerationConfig): Promise<string>
barcodeToPng(barcodeData: Buffer, sizePx?: number): Promise<Buffer>
barcodeToSvg(barcodeData: Buffer, sizePx?: number): Promise<string>
detectBarcodeFormat(barcodeData: Buffer): BarcodeFormat
decodeBarcodeData(barcodeData: Buffer): string
getDetectionConfidence(barcodeData: Buffer): number
BatchManager
new BatchManager(documents: BatchDocument[])
extractTextBatch(options?: BatchOptions): Promise<BatchResult>
extractMarkdownBatch(options?: BatchOptions): Promise<BatchResult>
extractHtmlBatch(options?: BatchOptions): Promise<BatchResult>
searchBatch(searchText: string, options?: BatchOptions): Promise<BatchResult>
getStatistics(): BatchStatistics
CacheManager
new CacheManager()
set<T>(key: string, value: T, scope?: CacheScope, ttl?: number): void
get<T>(key: string): T | undefined
has(key: string): boolean
delete(key: string): boolean
clear(): void
clearScope(scope: CacheScope): number
getStatistics(): CacheStatistics
setTtl(key: string, ttl: number): boolean
getKeys(scope?: CacheScope): string[]
prune(): number
destroy(): void
EnterpriseManager
new EnterpriseManager(doc: PdfDocument)
applyBates(...): Promise<boolean> // Bates numbering
applyBatesAdvanced(...): Promise<boolean>
comparePages(...): Promise<PageComparisonResult>
compareDocuments(docA: any, docB: any): Promise<DocumentComparisonResult>
stampHeader(...): Promise<boolean>
stampFooter(...): Promise<boolean>
stampHeaderFooter(...): Promise<boolean>
HybridMLManager
new HybridMLManager(doc: PdfDocument)
analyzePage(pageIndex: number): Promise<PageAnalysisResult>
analyzeDocument(): Promise<PageAnalysisResult[]>
getExtractionStrategy(pageIndex: number): Promise<ExtractionStrategy>
detectTables(pageIndex: number): Promise<TableRegion[]>
detectColumns(pageIndex: number): Promise<ColumnRegion[]>
getAverageComplexity(): Promise<number>
getMostCommonContentType(): Promise<ContentType>
estimateProcessingTime(): Promise<number>
ResultAccessorsManager
Lazy property accessors over native search/font/image/annotation result handles.
new ResultAccessorsManager(doc: PdfDocument)
// Search results
getSearchResultLineNumber(results, index): Promise<number>
getSearchResultParagraphNumber(results, index): Promise<number>
getSearchResultConfidence(results, index): Promise<number>
isSearchResultHighlighted(results, index): Promise<boolean>
getSearchResultFontInfo(results, index): Promise<string>
getSearchResultColor(results, index): Promise<[number, number, number]>
getSearchResultRotation(results, index): Promise<number>
getSearchResultObjectId(results, index): Promise<number>
getSearchResultStreamIndex(results, index): Promise<number>
getSearchResultAllProperties(results, index): Promise<SearchResultProperties>
// Fonts
getFontBaseFontName(fonts, index): Promise<string>
getFontDescriptor(fonts, index): Promise<string>
getFontDescendantFont(fonts, index): Promise<string>
getFontToUnicodeCmap(fonts, index): Promise<string>
isFontVertical(fonts, index): Promise<boolean>
getFontWidths(fonts, index): Promise<Float32Array>
getFontAscender(fonts, index): Promise<number>
getFontDescender(fonts, index): Promise<number>
getFontAllProperties(fonts, index): Promise<FontProperties>
// Images
hasImageAlphaChannel(images, index): Promise<boolean>
getImageIccProfile(images, index): Promise<Uint8Array>
getImageFilterChain(images, index): Promise<string>
getImageDecodedData(images, index): Promise<Uint8Array>
getImageWidth(images, index): Promise<number>
getImageHeight(images, index): Promise<number>
getImageColorSpace(images, index): Promise<string>
getImageAllProperties(images, index): Promise<ImageProperties>
// Annotations
getAnnotationModifiedDate(annotations, index): Promise<number>
getAnnotationSubject(annotations, index): Promise<string>
getAnnotationReplyToIndex(annotations, index): Promise<number>
getAnnotationPageNumber(annotations, index): Promise<number>
getAnnotationIconName(annotations, index): Promise<string>
getAnnotationAuthor(annotations, index): Promise<string>
getAnnotationAllProperties(annotations, index): Promise<AnnotationProperties>
OcrManager (feature ocr)
new OcrManager(doc: PdfDocument, options?: ManagerOptions)
destroyOcrEngine(): Promise<void>
pageNeedsOcr(pageIndex: number): Promise<boolean>
recognizePage(pageIndex: number): Promise<string>
extractText(pageIndex: number, config?: OcrConfig): Promise<string>
extractSpans(pageIndex: number, config?: OcrConfig): Promise<OcrSpan[]>
getOcrConfidence(pageIndex: number): Promise<number>
detectTextRegions(pageIndex: number): Promise<TextRegion[]>
setOcrLanguage(language: OcrLanguage | string): Promise<boolean>
setLanguage(language: OcrLanguage): void
getLanguage(): OcrLanguage
getAvailableLanguages(): Promise<OcrLanguage[]>
preprocessPage(pageIndex: number, preprocessingType?: string): Promise<boolean>
getOcrStatistics(pageIndex: number): Promise<OcrResult>
batchRecognizePages(startPage: number, endPage: number): Promise<Map<number, string>>
analyzePage(pageIndex: number, config?: OcrConfig): Promise<OcrPageAnalysis>
analyzeDocument(config?: OcrConfig): Promise<OcrPageAnalysis[]>
getEngineStatus(): Promise<string>
getConfiguration(): object
isAvailable(): Promise<boolean>
getVersion(): Promise<string>
destroy(): Promise<void>
Build with --features ocr (see OCR guide).
Signatures
SignatureManager
new SignatureManager(doc: PdfDocument)
// Inspect
getSignatures(): Promise<DigitalSignature[]>
getSignatureFields(): Promise<SignatureField[]>
getSignatureCount(): Promise<number>
isSigned(): Promise<boolean>
isCertified(): Promise<boolean>
verifySignatures(): Promise<SignatureValidationResult>
verifySignature(signatureName: string): Promise<SignatureValidationResult>
getSignerName(index: number): Promise<string>
getSigningTime(index: number): Promise<number>
getSigningReason(index: number): Promise<string | null>
getSigningLocation(index: number): Promise<string | null>
getCertificateSubject(index: number): Promise<string>
getCertificateIssuer(index: number): Promise<string>
getCertificateSerial(index: number): Promise<string>
getCertificateValidity(index: number): Promise<[number, number]>
getSignatureDetails(index: number): Promise<Signature | null>
isCertificateValidByIndex(index: number): Promise<boolean>
getCertificateInfo(certificateId: string): Promise<CertificateInfo | null>
getCertificateChain(certificateId: string): Promise<CertificateChain | null>
// Certificates / credentials
loadCertificateFromFile(filePath: string, password?: string, format?: CertificateFormat): Promise<LoadedCertificate | null>
loadCertificateFromBytes(certData: Buffer, password?: string, format?: CertificateFormat): Promise<LoadedCertificate | null>
loadCertificateFromPem(certificatePem: string, ...): Promise<LoadedCertificate | null>
loadCertificateFromDerBytes(certData: Buffer): Promise<any>
loadCredentialsPkcs12(filePath: string, password: string): Promise<SigningCredentials>
loadCredentialsFromDer(certData: Buffer, keyData?: Buffer): Promise<SigningCredentials>
addChainCert(credentials: SigningCredentials, certData: Buffer): Promise<void>
getCertificate(credentials: SigningCredentials): Promise<any>
getCertificateCn(certHandle: any): Promise<string>
getCertificateIssuerFromHandle(certHandle: any): Promise<string>
getCertificateSize(certHandle: any): Promise<number>
getLoadedCertificates(): readonly LoadedCertificate[]
unloadCertificate(certificateId: string): boolean
freeCredentials(credentials: SigningCredentials): void
freeCertificate(certHandle: any): void
// Sign
signDocument(fieldName: string, certificate: LoadedCertificate | string, options?: SigningOptions): Promise<SigningResult>
certifyDocument(fieldName: string, certificate: LoadedCertificate | string, permission: CertificationPermission, options?: SigningOptions): Promise<SigningResult>
signInvisibly(certificate: LoadedCertificate | string, options?: SigningOptions): Promise<SigningResult>
signMultipleFields(signings: { fieldName: string; certificate: LoadedCertificate | string; options?: SigningOptions }[]): Promise<SigningResult[]>
saveSigned(pdfData: Buffer, outputPath: string): Promise<void>
// Signature fields
addSignatureField(config: SignatureFieldConfig): Promise<boolean>
removeSignatureField(fieldName: string): Promise<boolean>
getSignatureFieldNames(): Promise<string[]>
hasSignatureField(fieldName: string): Promise<boolean>
// Timestamps / LTV
addTimestamp(pdfData: Buffer, signatureIndex: number, tsaUrl: string): Promise<Buffer>
addDocumentTimestamp(config: TimestampConfig): Promise<TimestampResult>
embedTimestamp(fieldName: string, config: TimestampConfig): Promise<TimestampResult>
getTimestampInfo(fieldName: string): Promise<object>
hasLtvEnabled(fieldName: string): Promise<boolean>
embedLtv(pdfData: Buffer, ocspData?: Buffer, crlData?: Buffer): Promise<Buffer>
Signature objects (doc.signatures() parity)
for (const sig of doc.signatures()) {
sig.signerName; sig.reason; sig.location; sig.signingTime;
sig.verify(); // "Valid" | "Invalid" | "Unknown"
sig.verifyDetached(pdfBytes); // boolean
const cert = sig.getCertificate();
cert.subject; cert.issuer; cert.serial;
cert.notBefore; cert.notAfter; cert.isValid;
}
Timestamp (RFC 3161)
Timestamp.parse(data: Buffer | Uint8Array): Timestamp
get time(): number
get serial(): string
get policyOid(): string
get tsaName(): string
get hashAlgorithm(): TimestampHashAlgorithm
get messageImprint(): Uint8Array
get token(): Uint8Array
verify(): boolean
close(): void
TsaClient
new TsaClient(options: { url: string; timeoutSeconds?: number; hashAlgorithm?: number; useNonce?: boolean; certReq?: boolean; username?: string; password?: string })
requestTimestamp(data: Buffer | Uint8Array): Timestamp
requestTimestampHash(digest: Buffer | Uint8Array, algorithm?: number): Timestamp
close(): void
Builders (options & annotations)
AnnotationBuilder
AnnotationBuilder.create(): AnnotationBuilder
asText(): this; asHighlight(): this; asUnderline(): this; asStrikeout(): this; asSquiggly(): this
type(type: string): this
content(content: string): this
author(author: string): this
subject(subject: string): this
color(rgb: number[]): this
colorName(colorName: string): this
opacity(opacity: number): this
bounds(bounds: AnnotationBounds): this
creationDate(date: Date): this
modificationDate(date: Date): this
printable(): this; notPrintable(): this
locked(locked: boolean): this
reply(replyContent: string): this
build(): Annotation
MetadataBuilder
MetadataBuilder.create(): MetadataBuilder
title(title: string): this
author(author: string): this
subject(subject: string): this
keywords(keywords: string[]): this
addKeyword(keyword: string): this
creator(creator: string): this
producer(producer: string): this
creationDate(date: Date): this
modificationDate(date: Date): this
withCurrentDate(): this
customProperty(key: string, value: string): this
customProperties(properties: Record<string, string>): this
build(): Metadata
SearchOptionsBuilder
SearchOptionsBuilder.create(): SearchOptionsBuilder
SearchOptionsBuilder.default(): SearchOptions
SearchOptionsBuilder.strict(): SearchOptions
SearchOptionsBuilder.regex(): SearchOptions
caseSensitive(sensitive: boolean): this
wholeWords(wholeOnly: boolean): this
useRegex(regex: boolean): this
ignoreAccents(ignore: boolean): this
maxResults(max: number): this
searchAnnotations(search: boolean): this
build(): SearchOptions
ConversionOptionsBuilder
ConversionOptionsBuilder.create(): ConversionOptionsBuilder
ConversionOptionsBuilder.default(): ConversionOptions
ConversionOptionsBuilder.textOnly(): ConversionOptions
ConversionOptionsBuilder.highQuality(): ConversionOptions
ConversionOptionsBuilder.fast(): ConversionOptions
preserveFormatting(preserve: boolean): this
detectHeadings(detect: boolean): this
detectTables(detect: boolean): this
detectLists(detect: boolean): this
includeImages(include: boolean): this
imageFormat(format: string): this
imageQuality(quality: number): this
maxImageDimension(maxDimension: number): this
outputEncoding(encoding: string): this
normalizeWhitespace(normalize: boolean): this
extractAnnotations(extract: boolean): this
useStructureTree(use: boolean): this
pageRange(start: number, end: number): this
build(): ConversionOptions
Streams
All stream classes are standard Node.js Readable streams in object mode.
new SearchStream(manager: SearchManager, query: string, options?: object)
new ExtractionStream(manager: ExtractionManager, startPage: number, endPage: number, type?: "text" | "markdown" | "html", options?: object)
new MetadataStream(manager: RenderingManager, startPage: number, endPage: number)
// Factories
createSearchStream(manager, term, options?): SearchStream
createExtractionStream(manager, startPage, endPage, type?, options?): ExtractionStream
createMetadataStream(manager, startPage, endPage): MetadataStream
StreamingTable
Incrementally build large tables into a PageBuilder.
new StreamingTable(config: StreamingTableConfig)
pushRow(cells: (string | null | undefined)[]): this
pushRowSpan(cells: (SpanCell | string | null | undefined)[]): this
flush(): this
finish(): Promise<PageBuilder>
WorkerPool
new WorkerPool(poolSize?: number) // default 4
workerPool // shared default pool instance
See the Node.js streams guide and the concurrency guide.
Value types & enums
new Rect(x: number, y: number, width: number, height: number)
rect.getRight(): number
rect.getBottom(): number
rect.contains(x: number, y: number): boolean
rect.intersects(other: Rect): boolean
new Point(x: number, y: number)
point.distanceTo(other: Point): number
new Color(red: number, green: number, blue: number)
Color.fromHex(hex: string): Color
color.toHex(): string
enum PageSize { Letter, Legal, A0, A1, A2, A3, A4, A5, A6, B4, B5, B6, Tabloid, Ledger, Custom }
Other exported enums: Align, BarcodeFormat, BarcodeErrorCorrection, ContentType, DigestAlgorithm, FieldVisibility, FormFieldType, ImageFormat, IssueSeverity, ComplianceIssueType, OCRDetectionMode, OCRLanguage, PageComplexity, PdfALevel, PdfUALevel, PdfXLevel, SignatureAlgorithm, ThumbnailSize, XfaFieldType, XfaFormType, ErrorCategory, ErrorSeverity.
Data types
interface Word {
text: string;
x: number; y: number;
width: number; height: number;
}
interface TextLine {
text: string;
y: number;
spans: Span[];
}
interface Span {
text: string;
fontName: string;
fontSize: number;
bbox: [number, number, number, number];
}
interface ImageInfo {
width: number;
height: number;
format: "png" | "jpeg" | "tiff";
colorspace: "rgb" | "gray" | "cmyk" | "indexed";
bitsPerComponent: number;
data: Buffer;
}
interface FontInfo {
name: string;
type: string;
encoding: string;
isEmbedded: boolean;
isSubset: boolean;
size: number;
}
interface AnnotationInfo {
type: string;
subtype: string;
content: string;
x: number; y: number;
width: number; height: number;
author: string;
linkUri?: string;
}
interface FormField {
name: string;
fieldType: string;
value: string;
pageIndex: number;
}
interface SearchResult {
pageIndex: number;
text: string;
position: number;
bounds?: Rect;
}
interface ConversionOptions {
preserveFormatting?: boolean;
includeTables?: boolean;
includeImages?: boolean;
extractHeadings?: boolean;
extractLists?: boolean;
}
interface RgbaPixmap {
width: number;
height: number;
data: Uint8Array; // RGBA, 4 bytes/pixel
}
Error handling
Failures throw typed errors that all extend PdfError. Inspect err.message or branch on the subclass:
import { PdfError, PdfIoError, PdfParseError, PdfEncryptionError } from "pdf-oxide";
try {
const doc = PdfDocument.open("file.pdf");
const text = doc.extractText(0);
} catch (err) {
if (err instanceof PdfEncryptionError) console.error("wrong password");
else if (err instanceof PdfParseError) console.error("malformed PDF");
else console.error(`Extraction failed: ${err.message}`);
}
Exported error classes: PdfError / PdfException, PdfIoError, PdfParseError, PdfEncryptionError, PdfUnsupportedError, PdfInvalidStateError, PdfDecodeError, PdfEncodeError, PdfFontError, PdfImageError, PdfCircularReferenceError, PdfRecursionLimitError, PdfOcrError, PdfMlError, PdfBarcodeError, plus the manager-scoped exceptions (AccessibilityException, ComplianceException, EncryptionException, OptimizationException, RedactionException, RenderingException, SearchException, SignatureException, ValidationException, IoException, ParseException, InvalidStateException, UnsupportedFeatureException, CertificateLoadFailed, SigningFailed, UnknownError).
Async method suffix
Many methods have an *Async variant returning a Promise (e.g. extractText → extractTextAsync, toMarkdown → toMarkdownAsync, renderPageWithOptions → renderPageWithOptionsAsync). Async variants dispatch to the libuv thread pool and do not block the event loop. Most manager accessor methods are already async. See the async guide.
Thread safety
PdfDocument is Send + Sync on the Rust side — safe to share across Node.js Worker threads. Use the WorkerPool for CPU-bound batch work. See the concurrency guide.
Generated types
TypeScript definitions ship with the package at node_modules/pdf-oxide/lib/index.d.ts — the canonical source of truth for types, including any fields added after this page was last updated.
HTML + CSS pipeline
const pdf = Pdf.fromHtmlCss(html, css, fontBytes);
const pdf = Pdf.fromHtmlCssWithFonts(html, css, [
["DejaVu Sans", font1],
["Noto Sans CJK", font2],
]);
Multi-target WASM packaging
If you use the WASM build (pdf-oxide-wasm) inside a Node.js app, import from pdf-oxide-wasm/nodejs. See JavaScript (WASM) API Reference → Multi-target packaging.
Other Language Bindings
PDF Oxide ships native bindings for every major ecosystem: Rust, Python, WASM, C#, Golang, Java, PHP, Ruby, C++, Swift, Kotlin, Dart, R, Julia, Zig, Scala, Clojure, Objective-C, and Elixir.
Next Steps
- Types & Enums — all shared types and enums
- Page API Reference — consistent per-page iteration across bindings
- Getting Started with Node.js — tutorial