Package Exports

@dragon708/docmind-docx

Readme

`@dragon708/docmind-docx`

Extracción de texto plano, HTML y imágenes incrustadas desde .docx. El texto/HTML usa Mammoth; las imágenes se leen del ZIP interno (word/media/) con JSZip.

Contenido de esta guía

Instalación
Uso rápido
Tipos exportados
Métodos y funciones (extractImagesFromDocx, extractTextFromDocx, convertDocxToHtml, analyzeDocx, …)
Opciones DocxToHtmlOptions (Mammoth)
Seguridad
Licencia

Instalación

npm install @dragon708/docmind-docx

Dependencias runtime: mammoth, jszip.

Uso rápido

import { readFile } from "node:fs/promises";
import { analyzeDocx, extractTextFromDocx, convertDocxToHtml } from "@dragon708/docmind-docx";

const buffer = await readFile("documento.docx");

const full = await analyzeDocx(buffer);
// full.text, full.html, full.warnings, full.kind === "docx"

const soloTexto = await extractTextFromDocx(buffer);
const soloHtml = await convertDocxToHtml(buffer);

Tipos exportados

Tipo	Descripción
`DocxBinaryInput`	Entrada binaria: `Buffer` \| `Uint8Array` \| `ArrayBuffer`.
`DocxToHtmlOptions`	Opciones opcionales de Mammoth para la conversión a HTML (ver tabla más abajo).
`ExtractTextResult`	`{ text: string; warnings: string[]; pages?: string[] }` (ver `splitByRenderedPages`).
`ExtractTextOptions`	`{ splitByRenderedPages?: boolean }` para texto paginado.
`ConvertHtmlResult`	`{ html: string; warnings: string[] }`
`DocxAnalysisResult`	`{ kind: "docx"; text: string; html: string; warnings: string[] }`
`DocxEmbeddedImage`	Una imagen extraída: `filename`, `zipPath`, `mediaType`, `data`, `base64`.
`ExtractImagesFromDocxResult`	`{ images: DocxEmbeddedImage[]; warnings: string[] }`

Métodos y funciones

`extractImagesFromDocx(input)`

Parámetros: input: DocxBinaryInput
Retorno: Promise<ExtractImagesFromDocxResult>
Qué hace: Lista los ficheros bajo word/media/ del DOCX (ZIP) y devuelve cada uno con bytes, Base64 (sin prefijo data:) y mediaType inferido por extensión. Si no hay imágenes, images es []. Si el archivo no es un ZIP válido, images es [] y warnings lo indica (no lanza).

Helper docxImageToDataUri(image) devuelve data:<mime>;base64,<payload> para usar en navegador como href de descarga o <img src>.

Ejemplo (Node: guardar en disco):

import { writeFile } from "node:fs/promises";
import { extractImagesFromDocx } from "@dragon708/docmind-docx";

const { images, warnings } = await extractImagesFromDocx(buffer);
for (const img of images) {
  await writeFile(img.filename, Buffer.from(img.data));
}

Ejemplo (navegador: enlace de descarga):

import { docxImageToDataUri, extractImagesFromDocx } from "@dragon708/docmind-docx";

const { images } = await extractImagesFromDocx(arrayBuffer);
const img = images[0];
if (img) {
  const a = document.createElement("a");
  a.href = docxImageToDataUri(img);
  a.download = img.filename;
  a.click();
}

Nota: incluye todos los ficheros directamente bajo word/media/ (no subcarpetas). El MIME se infiere por extensión; si no coincide con tipos habituales, se usa application/octet-stream. No comprueba si el XML del documento referencia cada fichero.

`extractTextFromDocx(input, options?)`

Parámetros: input: DocxBinaryInput, options?: ExtractTextOptions
Retorno: Promise<ExtractTextResult>
Qué hace: Obtiene texto sin marcas HTML. La estructura es aproximada (no conserva maquetación fina).
splitByRenderedPages: true (por defecto es false): antes de Mammoth se inyectan marcas en word/document.xml donde Word suele guardar saltos de página (lastRenderedPageBreak, saltos explícitos, pageBreakBefore). El resultado en text queda como:
```
Page 1 --------
…contenido página 1…

Page 2 --------
…contenido página 2…
```
Además se rellena pages con un array (solo cuerpos, sin la línea Page N). Si no se encuentra ninguna pista de salto, se devuelve una sola página y un warning descriptivo.
Helpers exportados (avanzado): injectDocxPageBreakMarkers, DOCX_RAW_PAGE_BREAK_MARKER, formatDocxRawTextByPages.

Si el buffer no es un DOCX válido, Mammoth suele lanzar error (no devuelve objeto vacío).

`convertDocxToHtml(input, htmlOptions?)`

Parámetros: input: DocxBinaryInput, htmlOptions?: DocxToHtmlOptions
Retorno: Promise<ConvertHtmlResult>
Qué hace: Genera un fragmento HTML (no documento completo con <html>). Imágenes incrustadas: por defecto DocMind usa data-URI en src salvo que definas otro convertImage.

`analyzeDocx(input, htmlOptions?)`

Parámetros: input: DocxBinaryInput, htmlOptions?: DocxToHtmlOptions
Retorno: Promise<DocxAnalysisResult>
Qué hace: Ejecuta en paralelo extracción de texto y conversión a HTML; une los warnings de ambas pasadas. Si algo falla de forma excepcional, no lanza: devuelve text y html vacíos y un warnings con mensaje error: Failed to read DOCX: ….

`docxImagesAsDataUri()`

Parámetros: ninguno
Retorno: Valor apto para la opción Mammoth convertImage.
Qué hace: Construye <img src="data:…;base64,…"> para imágenes inline. Es el predeterminado de este paquete cuando no pasas convertImage en htmlOptions. Puedes usarla explícitamente o sustituirla por mammoth.images.dataUri u otra estrategia (p. ej. escribir archivos en disco).

Ejemplo explícito:

import mammoth from "mammoth";
import { convertDocxToHtml, docxImagesAsDataUri } from "@dragon708/docmind-docx";

await convertDocxToHtml(buffer, {
  convertImage: docxImagesAsDataUri(),
});

// O la helper de Mammoth (muy similar):
await convertDocxToHtml(buffer, {
  convertImage: mammoth.images.dataUri,
});

Opciones `DocxToHtmlOptions` (Mammoth)

Se reenvían a mammoth.convertToHtml. Campos habituales:

Opción	Descripción breve
`styleMap`	Reglas personalizadas de mapeo de estilos (string multilínea o array de líneas).
`includeEmbeddedStyleMap`	Usar el mapa incrustado en el `.docx`.
`includeDefaultStyleMap`	Usar el mapa por defecto de Mammoth.
`convertImage`	Cómo convertir cada imagen (por defecto en DocMind: data-URI vía `docxImagesAsDataUri`).
`ignoreEmptyParagraphs`	Omitir párrafos vacíos en el HTML.
`idPrefix`	Prefijo para ids generados (notas, etc.).
`externalFileAccess`	Permitir lectura de recursos externos referenciados (riesgo con documentos no confiables).
`transformDocument`	Transformación del árbol del documento antes del HTML (avanzado).

Detalle y sintaxis de styleMap: documentación de Mammoth.

Seguridad

Mammoth no sanea el contenido del documento. No uses conversión a HTML con entrada no confiable sin un paso posterior de sanitización (p. ej. para XSS) si vas a insertar el HTML en una página.

Licencia

MIT (alineada con el monorepo DocMind).