0010. Codec Excel/XLSX basato su exceljs

• Stato: Accettata
• Data: 2026-06-05
• Decisori: Team BI/ETL

Contesto

Serve un FileCodec per Excel (.xlsx), il secondo formato più comune in ingresso dopo il CSV. A differenza del CSV, XLSX ha tipi (numeri, date, booleani), più fogli, formule, hyperlink e rich text. Il formato è uno zip (richiede il contenuto intero per essere letto).

Decisione

Adottiamo exceljs (libreria Excel più diffusa per Node, tipi inclusi).

• decode: workbook.xlsx.load(buffer) + lettura del foglio scelto (per nome o indice) via getSheetValues(). Preserva i tipi (numeri, date) e normalizza le celle ricche (formula → result, hyperlink/rich text → testo).
• encode: costruisce il foglio (addRow), imposta un formato data sulle celle Date (altrimenti rileggono come numeri), e produce il file con writeBuffer().
• Opzioni: sheet/sheetIndex, header, columns.

Nota: si è scelto il caricamento bufferizzato per-file invece dello stream.xlsx.WorkbookReader di exceljs: lo zip XLSX richiede comunque il file intero e il reader streaming si è rivelato fragile (errori su multi-foglio, date lette come numeri). Adatto a export Excel di dimensioni tipiche, non a file enormi.

Alternative considerate

• stream.xlsx di exceljs — streaming reale ma instabile nel nostro uso (vedi nota). Scartato.
• xlsx/SheetJS — molto diffuso ma con licenza/tipi meno comodi e API datata. exceljs preferito.
• node-xlsx — wrapper minimale su SheetJS, meno controllo su tipi/fogli.

Conseguenze

• Positive: lettura/scrittura XLSX robusta con preservazione dei tipi, selezione foglio, gestione celle ricche.
• Costi/limiti: exceljs è una dipendenza non piccola; il decode bufferizza il file (no streaming per file enormi).