0008. Codec CSV basato su csv-parse / csv-stringify

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

Contesto

Serve un FileCodec per CSV (il formato più comune in ingresso, es. export da gestionali), conforme a RFC 4180: quoting, virgole e a-capo nei campi, BOM, delimitatori custom. Deve lavorare in streaming (byte → record) per file grandi.

Decisione

Adottiamo csv-parse e csv-stringify (famiglia adaltas/node-csv, JS puro, tipi inclusi, streaming nativo).

• decode: Readable.from(bytes).pipe(parse({ columns: header, bom: true, … })) → record come oggetti; i valori restano stringhe (il CSV non ha tipi) e si tipizzano a valle con validate (Zod con coercizione).
• encode: record → csv-stringify (header opzionale, colonne/ordine configurabili) → byte.
• Opzioni minime esposte: delimiter, header, columns (vedi csvCodec).

Alternative considerate

• Parser fatto a mano — l'avevo evitato nell'astrazione (#21) proprio per non gestire a mano quoting/escaping/BOM: error-prone. Scartato.
• papaparse — ottimo lato browser, ma node-csv è più idiomatico per gli stream Node.
• fast-csv — valido; node-csv scelto per maturità, tipi e streaming a basso livello.

Conseguenze

• Positive: parsing CSV robusto e in streaming, due dipendenze piccole e tipizzate, API allineata al FileCodec.
• Costi/limiti: i valori sono stringhe (per scelta) — la conversione di tipo è demandata a validate/transform a valle.