Referência da API Node.js
O pacote npm pdf-oxide fornece um addon nativo N-API com definições de tipos TypeScript completas. Os binários pré-compilados por plataforma são distribuídos via subpacotes específicos de cada plataforma, e uma fina camada TypeScript adiciona as APIs baseadas em classes, manager, builder e stream documentadas abaixo.
npm install pdf-oxide
Para o build WASM voltado a navegadores / Deno / Bun / edge runtimes, veja a Referência da API WASM. Para outras linguagens, veja Python, Golang, C# ou Rust.
Exports do pacote
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";
Todas as classes apoiadas por código nativo expõem close() (e Symbol.dispose quando apropriado) — use using (Node.js 22+) para limpeza automática.
Funções de nível superior
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
Acesso somente leitura a documentos PDF, além de conversão e renderização.
Construtores
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
Informações do documento
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
Páginas
page(index: number): Page // lightweight lazy page handle (see Page)
Extração de texto
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
Conversão
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
Recursos e estrutura
getFormFields(): FormField[]
getOutline(): OutlineItem[]
getPageAnnotations(pageIndex: number): AnnotationInfo[]
getEmbeddedFonts(pageIndex: number): FontInfo[]
getEmbeddedImages(pageIndex: number): ImageInfo[]
planSplitByBookmarks(options?: SplitByBookmarksOptions): SplitSegment[]
Busca
searchPage(pageIndex: number, query: string, caseSensitive?: boolean): SearchResult[]
searchAll(query: string, caseSensitive?: boolean): SearchResult[]
Renderização
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 (literal de objeto): { dpi?, format?: "png" | "jpeg", jpegQuality?, background?: [r,g,b,a], renderAnnotations?, transparentBackground? }.
Conformidade
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
Um handle de página leve e lazy retornado por doc.page(index). Cada método delega ao documento pai.
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 — criação
Crie PDFs a partir de vários formatos de origem.
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
Autoria de documentos fluente e de baixo nível, com fontes incorporadas, anotações, widgets AcroForm, tabelas e elementos gráficos.
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
Retornado por a4Page() / letterPage() / page(w, h). Retorna ao pai com 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
Builder de documentos de alto nível, orientado a metadados, que produz um Pdf a partir de um formato de origem.
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
Mutação in-place: páginas, metadados, formulários, anotações, redação e salvamento criptografado.
Construtores
DocumentEditor.open(path: string): DocumentEditor
DocumentEditor.openFromBytes(data: Buffer | Uint8Array): DocumentEditor
Informações e metadados
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
Operações de página
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
Formulários e anotações
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
Redação e 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
Salvar
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
As classes manager encapsulam um PdfDocument (new XManager(doc)) e agrupam operações relacionadas. A maioria dos métodos de acesso é async. Muitos managers também expõem clearCache() / getCacheStats() e 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 e 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
Acessores de propriedade lazy sobre handles nativos de resultados de busca/fonte/imagem/anotação.
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>
Compile com --features ocr (veja o guia de OCR).
Assinaturas
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>
Objetos de assinatura (paridade com doc.signatures())
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 (opções e anotações)
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
Todas as classes de stream são streams Readable padrão do Node.js em modo de objeto.
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
Construa incrementalmente tabelas grandes dentro de um 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
Veja o guia de streams do Node.js e o guia de concorrência.
Tipos de valor e 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 }
Outros enums exportados: Align, BarcodeFormat, BarcodeErrorCorrection, ContentType, DigestAlgorithm, FieldVisibility, FormFieldType, ImageFormat, IssueSeverity, ComplianceIssueType, OCRDetectionMode, OCRLanguage, PageComplexity, PdfALevel, PdfUALevel, PdfXLevel, SignatureAlgorithm, ThumbnailSize, XfaFieldType, XfaFormType, ErrorCategory, ErrorSeverity.
Tipos de dados
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
}
Tratamento de erros
As falhas lançam erros tipados que estendem todos de PdfError. Inspecione err.message ou faça branch pela subclasse:
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}`);
}
Classes de erro exportadas: PdfError / PdfException, PdfIoError, PdfParseError, PdfEncryptionError, PdfUnsupportedError, PdfInvalidStateError, PdfDecodeError, PdfEncodeError, PdfFontError, PdfImageError, PdfCircularReferenceError, PdfRecursionLimitError, PdfOcrError, PdfMlError, PdfBarcodeError, além das exceções específicas de manager (AccessibilityException, ComplianceException, EncryptionException, OptimizationException, RedactionException, RenderingException, SearchException, SignatureException, ValidationException, IoException, ParseException, InvalidStateException, UnsupportedFeatureException, CertificateLoadFailed, SigningFailed, UnknownError).
Sufixo de método assíncrono
Muitos métodos têm uma variante *Async que retorna uma Promise (ex.: extractText → extractTextAsync, toMarkdown → toMarkdownAsync, renderPageWithOptions → renderPageWithOptionsAsync). As variantes assíncronas delegam ao thread pool do libuv e não bloqueiam o event loop. A maioria dos métodos de acesso dos managers já é async. Veja o guia de async.
Segurança em threads
PdfDocument é Send + Sync no lado Rust — seguro para compartilhar entre Worker threads do Node.js. Use o WorkerPool para trabalho em lote limitado por CPU. Veja o guia de concorrência.
Tipos gerados
As definições TypeScript são distribuídas junto com o pacote em node_modules/pdf-oxide/lib/index.d.ts — a fonte canônica de verdade para os tipos, incluindo quaisquer campos adicionados após a última atualização desta página.
Pipeline HTML + CSS
const pdf = Pdf.fromHtmlCss(html, css, fontBytes);
const pdf = Pdf.fromHtmlCssWithFonts(html, css, [
["DejaVu Sans", font1],
["Noto Sans CJK", font2],
]);
Empacotamento WASM multi-target
Se você usa o build WASM (pdf-oxide-wasm) dentro de uma aplicação Node.js, importe de pdf-oxide-wasm/nodejs. Veja Referência da API JavaScript (WASM) → Empacotamento multi-target.
Other Language Bindings
O PDF Oxide oferece bindings nativos para todos os principais ecossistemas: Rust, Python, WASM, C#, Golang, Java, PHP, Ruby, C++, Swift, Kotlin, Dart, R, Julia, Zig, Scala, Clojure, Objective-C e Elixir.
Próximos Passos
- Tipos e Enums — todos os tipos e enums compartilhados
- Referência da API Page — iteração consistente por página entre os bindings
- Primeiros Passos com Node.js — tutorial