@dragon708/docmind-spreadsheet

Carga y normalización de hojas de cálculo para DocMind: un único flujo asíncrono alineado con @dragon708/docmind-shared (FileLikeInput, errores compartidos), preparado para análisis, conversión a JSON/CSV y futuras rutas (Markdown, salida estructurada).

Objetivo

• Detectar formato (extensión, MIME, magic bytes o forceFormat).
• Abrir el libro con el motor adecuado (ExcelJS para .xlsx, SheetJS para .xls/.ods y fallback, Papa Parse para .csv).
• Exponer metadatos de libro/hoja, matrices de celdas normalizadas y advertencias estructuradas.

Formatos soportados (inicial)

| Formato | Extensión típica | Motor principal | |--------|-------------------|-----------------| | Excel Open XML | .xlsx | ExcelJS (fallback SheetJS) | | Excel binario (legacy) | .xls | SheetJS | | OpenDocument Spreadsheet | .ods | SheetJS | | CSV | .csv | Papa Parse |

Librerías usadas

• exceljs — lectura .xlsx.
• xlsx (SheetJS) — .xls, .ods, y respaldo de .xlsx.
• papaparse — CSV (parseo al cargar; unparse en export CSV).
• @dragon708/docmind-shared — bytes, nombres MIME, tipos de entrada y errores.

Instalación

npm install @dragon708/docmind-spreadsheet

Requiere Node.js ≥ 20 (alineado con el resto de paquetes DocMind en este monorepo).

API inicial (entrypoint único)

Todo se exporta desde el paquete raíz:

import {
  readWorkbook,
  getSheetNames,
  analyzeSpreadsheet,
  extractSheetData,
  convertSheetToJson,
  convertSheetToCsv,
  SpreadsheetWorkbook,
} from "@dragon708/docmind-spreadsheet";

Funciones principales

| Función | Rol | |--------|-----| | readWorkbook(input, options?) | Devuelve un SpreadsheetWorkbook (handle con el motor cargado). | | getSheetNames(input \| workbook) | Lista de nombres de hojas. | | analyzeSpreadsheet(input, options?) | Resumen serializable: formato, estrategia, hojas, warnings, workbook anidado. | | extractSheetData(source, options?) | Matriz de una hoja: rows, headers?, mergedCells, context, warnings. | | convertSheetToJson(source, options?) | JSON como objetos (con cabeceras) o arrays de filas. | | convertSheetToCsv(source, options?) | Cadena CSV (Papa unparse, delimitador/comillas configurables). |

Helpers útiles: normalizeCellValue, normalizeSheetRows, inferHeaders, getSheetDimensions, resolveSpreadsheetBytes.

Ejemplos básicos

Analizar un archivo

import { analyzeSpreadsheet } from "@dragon708/docmind-spreadsheet";

const result = await analyzeSpreadsheet({ name: "data.xlsx", data: bytes });
// result.format, result.strategyUsed, result.sheetNames, result.warnings, result.workbook

Leer y extraer una hoja

import { readWorkbook, extractSheetData } from "@dragon708/docmind-spreadsheet";

const wb = await readWorkbook({ name: "report.xlsx", data: bytes });
const grid = await extractSheetData(wb, {
  sheetName: "Summary",
  inferHeaders: true,
});
// grid.rows, grid.headers, grid.context, grid.warnings

CSV → JSON

import { convertSheetToJson } from "@dragon708/docmind-spreadsheet";

const { data, representation, warnings, context } = await convertSheetToJson(
  { name: "export.csv", data: csvBytes },
  { useFirstRowAsHeader: true },
);

Limitaciones actuales

• Una tabla rectangular por extracción: no hay detección automática de múltiples tablas dentro de la misma hoja (previsto como API futura).
• Markdown / structured output completo no están en este paquete todavía; el modelo de tipos (SpreadsheetTableData, SpreadsheetOperationContext, etc.) está pensado para enganchar esas capas después.
• Estilos, gráficos y macros no se modelan; el foco es valor de celda normalizado (texto, número, booleano, fecha, fórmula con valor evaluado cuando el motor lo expone).
• Celdas combinadas: en rutas no ExcelJS el valor suele reflejarse solo en la celda maestra; se emiten mergedCells y avisos cuando aplica.
• CSV: un único “libro” lógico; opciones de Papa (delimiter, skipEmptyLines, …) pasan por ReadWorkbookOptions.csv.

Publicación

El paquete define publishConfig.access: "public" y entra en el orden de publicación del monorepo (después de @dragon708/docmind-shared). Para alinear versiones entre paquetes @dragon708/docmind-*, usar en la raíz del repo:

node scripts/set-docmind-version.mjs <semver>
npm install

Licencia

MIT (alineada con los paquetes DocMind publicados como @dragon708/docmind-*).