Referencia de API JavaScript

PDF Oxide proporciona bindings WebAssembly para JavaScript y TypeScript. El paquete npm pdf-oxide-wasm funciona en Node.js, navegadores, bundlers, Deno y Cloudflare Workers.

npm install pdf-oxide-wasm

Empaquetado multiobjetivo (v0.3.38)

pdf-oxide-wasm ahora entrega tres builds en paralelo con exports condicionales en package.json. Elige el subpath que encaje con tu runtime — el import de nivel superior también se resuelve correctamente vía el campo exports en la mayoría de los entornos.

Subpath	Destino
pdf-oxide-wasm/nodejs	Node.js (CommonJS + ESM)
pdf-oxide-wasm/bundler	Vite, webpack, Rollup, esbuild, Bun
pdf-oxide-wasm/web	Navegadores, Deno, Cloudflare Workers

// Node.js
import { WasmPdfDocument } from "pdf-oxide-wasm/nodejs";

// Vite / webpack / Rollup
import init, { WasmPdfDocument } from "pdf-oxide-wasm/bundler";
await init();

// Navegadores / Deno / Workers
import init, { WasmPdfDocument } from "pdf-oxide-wasm/web";
await init();

Esto resuelve el ReferenceError: Can't find variable: __dirname que lanzaban los bundlers de navegador antes de la v0.3.38.

Para la API de Rust, consulta la Rust API Reference. Para la API de Python, consulta la Referencia de API Python. Para detalles de tipos, consulta Types & Enums.

---

WasmPdfDocument

La clase principal para abrir, extraer, editar y guardar PDFs.

import { WasmPdfDocument } from "pdf-oxide-wasm";

Constructor

new WasmPdfDocument(data)

Cargue un documento PDF desde bytes sin procesar.

Parámetro	Tipo	Descripción
data	Uint8Array	El contenido del archivo PDF

Lanza: Error si el PDF es inválido o no puede ser analizado.

const bytes = new Uint8Array(readFileSync("document.pdf"));
const doc = new WasmPdfDocument(bytes);

---

Núcleo de solo lectura

pageCount() -> number

Obtener el número de páginas del documento.

version() -> Uint8Array

Obtener la versión PDF como [major, minor].

const [major, minor] = doc.version();
console.log(`PDF ${major}.${minor}`);

authenticate(password) -> boolean

Desencriptar un PDF encriptado. Retorna true si la autenticación fue exitosa.

Parámetro	Tipo	Descripción
password	string	La cadena de contraseña

hasStructureTree() -> boolean

Verificar si el documento es un PDF etiquetado con un árbol de estructura.

---

Extracción de texto

extractText(pageIndex) -> string

Extraer texto plano de una sola página.

Parámetro	Tipo	Descripción
pageIndex	number	Número de página basado en cero

const text = doc.extractText(0);

extractAllText() -> string

Extraer texto plano de todas las páginas, separado por caracteres de avance de página.

extractChars(pageIndex) -> Array

Extraer caracteres individuales con posicionamiento preciso y metadatos de fuente.

Parámetro	Tipo	Descripción
pageIndex	number	Número de página basado en cero

Retorna: Array de objetos con campos:

Campo	Tipo	Descripción
char	string	El carácter
bbox	{x, y, width, height}	Cuadro delimitador
font_name	string	Nombre de fuente
font_size	number	Tamaño de fuente en puntos
font_weight	string	Peso (Normal, Bold, etc.)
is_italic	boolean	Indicador de cursiva
color	{r, g, b}	Color RGB (0.0–1.0)

const chars = doc.extractChars(0);
for (const c of chars) {
  console.log(`'${c.char}' at (${c.bbox.x}, ${c.bbox.y})`);
}

extractSpans(pageIndex) -> Array

Extraer spans de texto con estilo y metadatos de fuente.

Parámetro	Tipo	Descripción
pageIndex	number	Número de página basado en cero

Retorna: Array de objetos con campos:

Campo	Tipo	Descripción
text	string	El contenido de texto
bbox	{x, y, width, height}	Cuadro delimitador
font_name	string	Font name
font_size	number	Tamaño de fuente en puntos
font_weight	string	Peso (Normal, Bold, etc.)
is_italic	boolean	Indicador de cursiva
color	{r, g, b}	Color RGB (0.0–1.0)

const result = doc.extractPageText(0);
console.log(`Page: ${result.pageWidth}x${result.pageHeight} pt`);
for (const span of result.spans) {
  console.log(`'${span.text}' font=${span.fontName} size=${span.fontSize}`);
}

const spans = doc.extractSpans(0);
for (const span of spans) {
  console.log(`"${span.text}" size=${span.fontSize}`);
}

---

Conversión de formato

toMarkdown(pageIndex, detectHeadings?, includeImages?, includeFormFields?) -> string

Convertir una sola página a Markdown.

Parámetro	Tipo	Predeterminado	Descripción
pageIndex	number	–	Número de página basado en cero
detectHeadings	boolean	true	Detectar encabezados por tamaño de fuente
includeImages	boolean	true	Incluir imágenes
includeFormFields	boolean	true	Incluir valores de campos de formulario

toMarkdownAll(detectHeadings?, includeImages?, includeFormFields?) -> string

Convertir todas las páginas a Markdown.

toHtml(pageIndex, preserveLayout?, detectHeadings?, includeFormFields?) -> string

Convertir una sola página a HTML.

Parámetro	Tipo	Predeterminado	Descripción
pageIndex	number	–	Número de página basado en cero
preserveLayout	boolean	false	Preservar diseño visual
detectHeadings	boolean	true	Detectar encabezados
includeFormFields	boolean	true	Incluir valores de campos de formulario

toHtmlAll(preserveLayout?, detectHeadings?, includeFormFields?) -> string

Convertir todas las páginas a HTML.

toPlainText(pageIndex) -> string

Convertir una sola página a texto plano.

toPlainTextAll() -> string

Convertir todas las páginas a texto plano.

---

Búsqueda

search(pattern, caseInsensitive?, literal?, wholeWord?, maxResults?) -> Array

Buscar texto en todas las páginas.

Parámetro	Tipo	Predeterminado	Descripción
pattern	string	–	Patrón de búsqueda (cadena o regex)
caseInsensitive	boolean	false	Búsqueda insensible a mayúsculas
literal	boolean	false	Tratar patrón como cadena literal
wholeWord	boolean	false	Coincidir solo palabras completas
maxResults	number	–	Máximo de resultados a retornar

Retorna: Array of objects with fields:

Campo	Tipo	Descripción
page	number	Número de página
text	string	Texto coincidente
bbox	object	Cuadro delimitador
start_index	number	Índice de inicio en el texto de la página
end_index	number	Índice final en el texto de la página

searchPage(pageIndex, pattern, caseInsensitive?, literal?, wholeWord?, maxResults?) -> Array

Buscar texto en una sola página.

---

Información de imágenes

extractImages(pageIndex) -> Array

Obtener metadatos de imágenes de una página.

Campo	Tipo	Descripción
width	number	Ancho de imagen en píxeles
height	number	Alto de imagen en píxeles
color_space	string	Espacio de color (e.g. DeviceRGB)
bits_per_component	number	Bits por canal de color
bbox	object	Posición en la página

extractImageBytes(pageIndex) -> Array

Extraer bytes de imagen sin procesar de una página. Retorna un array de objetos:

Campo	Tipo	Descripción
width	number	Ancho de imagen en píxeles
height	number	Alto de imagen en píxeles
data	Uint8Array	Bytes de imagen sin procesar
format	string	Formato de imagen

pageImages(pageIndex) -> Array

Obtener nombres de imágenes y límites para operaciones de posicionamiento.

Campo	Tipo	Descripción
name	string	Nombre XObject
bounds	number[]	[x, y, width, height]
matrix	number[]	Matriz de transformación [a, b, c, d, e, f]

---

Estructura del documento

getOutline() -> Array | null

Obtener marcadores del documento / tabla de contenidos. Retorna null si no existe un esquema.

getAnnotations(pageIndex) -> Array

Obtener metadatos de anotaciones (tipo, rectángulo, contenido, etc.) de una página.

extractPaths(pageIndex) -> Array

Obtener trazados vectoriales (líneas, curvas, formas) de una página.

pageLabels() -> Array

Obtener rangos de etiquetas de página. Retorna un array de objetos:

Campo	Tipo	Descripción
start_page	number	Primera página en este rango
style	string	Estilo de numeración
prefix	string	Prefijo de etiqueta
start_value	number	Número inicial

xmpMetadata() -> object | null

Obtener metadatos XMP. Retorna null si no está presente. Los campos del objeto incluyen:

Campo	Tipo	Descripción
dc_title	string | null	Título del documento
dc_creator	string[] | null	Lista de creadores
dc_description	string | null	Descripción
xmp_creator_tool	string | null	Herramienta creadora
xmp_create_date	string | null	Fecha de creación
xmp_modify_date	string | null	Fecha de modificación
pdf_producer	string | null	Productor PDF

---

Campos de formulario

getFormFields() -> Array

Obtener todos los campos de formulario con nombre, tipo, valor e indicadores.

Campo	Tipo	Descripción
name	string	Nombre de campo
field_type	string	Tipo de campo (text, checkbox, etc.)
value	string	Valor actual
flags	number	Indicadores de campo

const fields = doc.getFormFields();
for (const f of fields) {
  console.log(`${f.name} (${f.field_type}) = ${f.value}`);
}

hasXfa() -> boolean

Verificar si el documento contiene formularios XFA.

getFormFieldValue(name) -> any

Obtener un valor de campo de formulario por nombre. Retorna un string, boolean o null dependiendo del tipo de campo.

Parámetro	Tipo	Descripción
name	string	Nombre de campo

setFormFieldValue(name, value) -> void

Establecer un valor de campo de formulario por nombre.

Parámetro	Tipo	Descripción
name	string	Nombre de campo
value	string | boolean	Nuevo valor del campo

exportFormData(format?) -> Uint8Array

Exportar datos de formulario como FDF (predeterminado) o XFDF.

Parámetro	Tipo	Predeterminado	Descripción
format	string	"fdf"	Formato de exportación: "fdf" or "xfdf"

---

Edición

Metadatos

Method	Parameters	Descripción
setTitle(title)	string	Establecer título del documento
setAuthor(author)	string	Establecer autor del documento
setSubject(subject)	string	Establecer asunto del documento
setKeywords(keywords)	string	Establecer palabras clave del documento

Rotación de páginas

Method	Parameters	Descripción
pageRotation(pageIndex)	number	Obtener rotación actual (0, 90, 180, 270)
setPageRotation(pageIndex, degrees)	number, number	Establecer rotación absoluta
rotatePage(pageIndex, degrees)	number, number	Agregar a la rotación actual
rotateAllPages(degrees)	number	Rotar todas las páginas

Dimensiones de página

Method	Parameters	Descripción
pageMediaBox(pageIndex)	number	Obtener MediaBox [llx, lly, urx, ury]
setPageMediaBox(pageIndex, llx, lly, urx, ury)	number, ...	Establecer MediaBox
pageCropBox(pageIndex)	number	Obtener CropBox (puede ser null)
setPageCropBox(pageIndex, llx, lly, urx, ury)	number, ...	Establecer CropBox
cropMargins(left, right, top, bottom)	number, ...	Recortar todos los márgenes de página

Borrado / Blanqueo

Method	Parameters	Descripción
eraseRegion(pageIndex, llx, lly, urx, ury)	number, ...	Borrar una región
eraseRegions(pageIndex, rects)	number, Float32Array	Borrar múltiples regiones
clearEraseRegions(pageIndex)	number	Limpiar borrados pendientes

Anotaciones & Redaction

Method	Parameters	Descripción
flattenPageAnnotations(pageIndex)	number	Aplanar anotaciones en la página
flattenAllAnnotations()	–	Aplanar todas las anotaciones
applyPageRedactions(pageIndex)	number	Aplicar redacciones en la página
applyAllRedactions()	–	Aplicar todas las redacciones

Aplanamiento de formularios

Method	Parameters	Descripción
flattenForms()	–	Aplanar todos los campos de formulario en el contenido de la página
flattenFormsOnPage(pageIndex)	number	Aplanar formularios en una página específica

Combinar e incrustar

mergeFrom(data) -> number

Combinar páginas de otro PDF. Retorna el número de páginas combinadas.

Parámetro	Tipo	Descripción
data	Uint8Array	Los bytes del archivo PDF fuente

embedFile(name, data) -> void

Adjuntar un archivo al PDF.

Parámetro	Tipo	Descripción
name	string	Nombre de archivo para el adjunto
data	Uint8Array	Contenido del archivo

Manipulación de imágenes

Method	Parameters	Descripción
repositionImage(pageIndex, name, x, y)	number, string, number, number	Mover imagen
resizeImage(pageIndex, name, w, h)	number, string, number, number	Redimensionar imagen
setImageBounds(pageIndex, name, x, y, w, h)	number, string, ...	Establecer límites de imagen

Renderizado

Método	Parámetros	Retorno	Descripción
renderPage(pageIndex, dpi?)	number, number	Uint8Array	Renderizar página como bytes PNG
flattenToImages(dpi?)	number	Uint8Array	Aplanar todas las páginas a PDF basado en imágenes

---

Guardar

saveToBytes() -> Uint8Array

Guardar el PDF editado como bytes.

saveEncryptedToBytes(password, ownerPassword?, allowPrint?, allowCopy?, allowModify?, allowAnnotate?) -> Uint8Array

Guardar con encriptación AES-256.

Parámetro	Tipo	Predeterminado	Descripción
password	string	–	Contraseña de usuario
ownerPassword	string	user password	Contraseña de propietario
allowPrint	boolean	true	Permitir impresión
allowCopy	boolean	true	Permitir copia
allowModify	boolean	false	Permitir modificación
allowAnnotate	boolean	true	Permitir anotaciones

free()

Liberar memoria WASM. Siempre llame a esto cuando termine con el documento.

---

WasmPdf

Clase de fábrica para crear nuevos PDFs.

import { WasmPdf } from "pdf-oxide-wasm";

Métodos estáticos

WasmPdf.fromMarkdown(content, title?, author?) -> WasmPdf

Crear un PDF desde texto Markdown.

Parámetro	Tipo	Predeterminado	Descripción
content	string	–	Contenido Markdown
title	string	–	Título del documento
author	string	–	Autor del documento

WasmPdf.fromHtml(content, title?, author?) -> WasmPdf

Crear un PDF desde HTML.

WasmPdf.fromText(content, title?, author?) -> WasmPdf

Crear un PDF desde texto plano.

WasmPdf.fromImageBytes(data) -> WasmPdf

Crear un PDF de una sola página desde bytes de imagen.

Parámetro	Tipo	Descripción
data	Uint8Array	Bytes de archivo de imagen (JPEG, PNG)

WasmPdf.fromMultipleImageBytes(imagesArray) -> WasmPdf

Crear un PDF de múltiples páginas desde múltiples imágenes, una página por imagen.

Parámetro	Tipo	Descripción
imagesArray	Uint8Array[]	Array de bytes de archivos de imagen

Métodos de instancia

toBytes() -> Uint8Array

Obtener el PDF como bytes.

size -> number

Tamaño del PDF en bytes (propiedad de solo lectura).

const pdf = WasmPdf.fromMarkdown("# Hello World\n\nThis is a PDF.");
console.log(`PDF size: ${pdf.size} bytes`);
writeFileSync("output.pdf", pdf.toBytes());

---

Disponibilidad de funciones

Algunas funciones requieren dependencias nativas y no están disponibles en WebAssembly:

Función	WASM	Notas
Extracción de texto	Sí	Soporte completo
Extracción estructurada	Sí	Caracteres, spans
Creación de PDF	Sí	Markdown, HTML, texto, imágenes
Edición de PDF	Sí	Metadatos, rotación, dimensiones, borrado
Campos de formulario	Sí	Leer, escribir, exportar, aplanar
Búsqueda	Sí	Soporte completo de regex
Encriptación	Sí	Lectura y escritura AES-256
Anotaciones	Sí	Leer, aplanar, redactar
Combinar PDFs	Sí	Combinar páginas de otro PDF
Archivos embebidos	Sí	Adjuntar archivos a PDFs
Etiquetas de página	Sí	Leer rangos de etiquetas de página
Metadatos XMP	Sí	Leer metadatos XMP
OCR	No	Requiere ONNX Runtime nativo
Digital signatures	No	Requiere bibliotecas criptográficas nativas
Page rendering	No	Requiere tiny-skia nativo
Barcodes	No	Requiere renderizado nativo
Office conversion	No	Requiere LibreOffice nativo

---

Manejo de errores

Todos los métodos que pueden fallar lanzan objetos Error de JavaScript:

try {
  const doc = new WasmPdfDocument(new Uint8Array([0, 1, 2]));
} catch (e) {
  console.error(`Failed to open: ${e.message}`);
}

---

TypeScript

Las definiciones completas de tipos están incluidas en el paquete:

import { WasmPdfDocument, WasmPdf } from "pdf-oxide-wasm";

const doc: WasmPdfDocument = new WasmPdfDocument(bytes);
const text: string = doc.extractText(0);
const pdf: WasmPdf = WasmPdf.fromMarkdown("# Hello");