Referencia de la API de Node.js
El paquete npm pdf-oxide proporciona un addon N-API nativo con definiciones de tipos TypeScript completas. Los binarios precompilados por plataforma se distribuyen mediante subpaquetes específicos de cada plataforma, y una capa fina de TypeScript añade las APIs basadas en clases, manager, builder y stream que se documentan a continuación.
npm install pdf-oxide
Para el build WASM dirigido a navegadores / Deno / Bun / edge runtimes, consulta la Referencia de la API WASM. Para otros lenguajes, consulta Python, Golang, C# o Rust.
Exports del paquete
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 las clases respaldadas por código nativo exponen close() (y Symbol.dispose cuando corresponde) — usa using (Node.js 22+) para la limpieza automática.
Funciones de nivel 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
Acceso de solo lectura a documentos PDF, además de conversión y renderizado.
Constructores
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
Información del 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)
Extracción 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
Conversión
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 y estructura
getFormFields(): FormField[]
getOutline(): OutlineItem[]
getPageAnnotations(pageIndex: number): AnnotationInfo[]
getEmbeddedFonts(pageIndex: number): FontInfo[]
getEmbeddedImages(pageIndex: number): ImageInfo[]
planSplitByBookmarks(options?: SplitByBookmarksOptions): SplitSegment[]
Búsqueda
searchPage(pageIndex: number, query: string, caseSensitive?: boolean): SearchResult[]
searchAll(query: string, caseSensitive?: boolean): SearchResult[]
Renderizado
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 (objeto literal): { dpi?, format?: "png" | "jpeg", jpegQuality?, background?: [r,g,b,a], renderAnnotations?, transparentBackground? }.
Cumplimiento
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
Un handle de página ligero y perezoso devuelto por doc.page(index). Cada método delega en el documento padre.
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 — creación
Crea PDFs a partir de varios formatos de origen.
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
Creación de documentos de bajo nivel y fluida, con fuentes embebidas, anotaciones, widgets de AcroForm, tablas y 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
Devuelto por a4Page() / letterPage() / page(w, h). Vuelve al padre con 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 nivel y orientado a metadatos que produce un Pdf a partir de un formato de origen.
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
Mutación in situ: páginas, metadatos, formularios, anotaciones, redacción y guardado cifrado.
Constructores
DocumentEditor.open(path: string): DocumentEditor
DocumentEditor.openFromBytes(data: Buffer | Uint8Array): DocumentEditor
Información y metadatos
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
Operaciones 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
Formularios y anotaciones
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
Redacción y combinación
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
Guardar
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
Las clases manager envuelven un PdfDocument (new XManager(doc)) y agrupan operaciones relacionadas. La mayoría de los métodos accesores son async. Muchos managers también exponen clearCache() / getCacheStats() y 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 y 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
Accesores de propiedades perezosos sobre handles nativos de resultados de búsqueda/fuente/imagen/anotación.
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>
Compila con --features ocr (consulta la guía de OCR).
Firmas
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 firma (paridad con 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 (opciones y anotaciones)
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 las clases stream son streams Readable estándar de Node.js en modo 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
Construye tablas grandes de forma incremental dentro de un 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
Consulta la guía de Node.js streams y la guía de concurrencia.
Value types y 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 }
Otros 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 datos
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
}
Manejo de errores
Los fallos lanzan errores tipados que extienden todos de PdfError. Inspecciona err.message o ramifica según la subclase:
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}`);
}
Clases de error exportadas: PdfError / PdfException, PdfIoError, PdfParseError, PdfEncryptionError, PdfUnsupportedError, PdfInvalidStateError, PdfDecodeError, PdfEncodeError, PdfFontError, PdfImageError, PdfCircularReferenceError, PdfRecursionLimitError, PdfOcrError, PdfMlError, PdfBarcodeError, además de las excepciones específicas de cada manager (AccessibilityException, ComplianceException, EncryptionException, OptimizationException, RedactionException, RenderingException, SearchException, SignatureException, ValidationException, IoException, ParseException, InvalidStateException, UnsupportedFeatureException, CertificateLoadFailed, SigningFailed, UnknownError).
Sufijo de métodos async
Muchos métodos tienen una variante *Async que devuelve una Promise (p. ej. extractText → extractTextAsync, toMarkdown → toMarkdownAsync, renderPageWithOptions → renderPageWithOptionsAsync). Las variantes async delegan en el pool de hilos de libuv y no bloquean el event loop. La mayoría de los métodos accesores de los managers ya son async. Consulta la guía async.
Seguridad entre hilos
PdfDocument es Send + Sync en el lado de Rust — es seguro compartirlo entre Worker threads de Node.js. Usa el WorkerPool para trabajo por lotes con carga de CPU. Consulta la guía de concurrencia.
Tipos generados
Las definiciones de TypeScript se distribuyen con el paquete en node_modules/pdf-oxide/lib/index.d.ts — la fuente de verdad canónica para los tipos, incluidos los campos añadidos después de la última actualización de esta 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],
]);
Empaquetado WASM multi-target
Si usas el build WASM (pdf-oxide-wasm) dentro de una app Node.js, importa desde pdf-oxide-wasm/nodejs. Consulta Referencia de la API JavaScript (WASM) → Empaquetado multi-target.
Other Language Bindings
PDF Oxide ofrece bindings nativos para todos los ecosistemas principales: Rust, Python, WASM, C#, Golang, Java, PHP, Ruby, C++, Swift, Kotlin, Dart, R, Julia, Zig, Scala, Clojure, Objective-C y Elixir.
Próximos pasos
- Tipos y enums — todos los tipos y enums compartidos
- Referencia de la API Page — iteración de página consistente entre bindings
- Primeros pasos con Node.js — tutorial