Convertire NDJSON in TOML

Si presume spesso che il TOML non possa contenere ciò che contiene il JSON, e per una lista di record è sbagliato. Un array di tabelle si scrive come la stessa intestazione ripetuta fra doppie parentesi quadre — [[items]] tre volte dà tre record — con ogni blocco che porta le proprie chiavi sotto. È il costrutto che Cargo usa per le dipendenze e Hugo per le voci di menu.

Rispetto al JSON da cui proviene è più prolisso e molto più facile da modificare. Aggiungere un record significa copiare quattro righe invece di bilanciare parentesi e ricordarsi una virgola, e un diff di una modifica a un record tocca solo quel blocco.

Un documento TOML deve essere una tabella al livello superiore, e un file delimitato da nuove righe è una lista senza un nome proprio. Quindi alla lista viene dato un nome segnaposto: l’uscita è una sequenza di blocchi [[items]], uno per riga della sorgente.

Quel nome è la prima cosa da cambiare, ed è una ricerca e sostituzione sulle intestazioni dei blocchi — in [[dependencies]], [[authors]], [[products]], qualunque cosa si aspetti lo strumento che legge il file. Niente in un file NDJSON potrebbe dire al convertitore cosa siano i record, quindi il segnaposto è intenzionale.

Questo è il vantaggio silenzioso del TOML rispetto a ogni destinazione tabellare per lo stesso file. Un CSV, un file Parquet o una serie di istruzioni INSERT devono riconciliare i record in un unico insieme di colonne, riempiendo gli spazi vuoti dove un record non aveva nulla. Un array di tabelle no: ogni blocco porta esattamente le chiavi che aveva la sua riga.

Quindi un file dove record successivi hanno acquisito un campo si converte senza null, senza celle vuote e senza allargamento. Il risultato si legge per quello che è — una lista di record perlopiù simili — piuttosto che una griglia sparsa.

Il TOML non ha un letterale null, e chi scrive il file non ne inventa uno. Una chiave il cui valore JSON era null semplicemente non viene scritta nel blocco, né al livello superiore di un record né altrove al suo interno.

Se questo conta è una domanda sullo strumento che legge il file. Molti trattano una chiave mancante e un valore vuoto in modo identico, tornando a un predefinito in entrambi i casi. Dove la distinzione guida il comportamento, la conversione ha cambiato silenziosamente i dati, e la difesa più economica è cercare null nella sorgente prima di convertire.

Un record con un oggetto annidato produce una sotto-tabella sotto il suo blocco: un oggetto autore dentro un record diventa un’intestazione [items.author] con le sue chiavi sotto. La profondità è espressa nell’intestazione piuttosto che nell’indentazione, quindi anche tre livelli restano piatti sulla pagina.

È legale a qualsiasi profondità e sgradevole oltre due o tre. Un’intestazione come [items.metadata.source.system] è valida e nessuno si diverte a leggerla, e un file di fixture che le produce di solito porta più struttura di quanta un file modificato a mano dovrebbe avere.

Un’intestazione di tabella TOML rivendica ogni riga scritta dopo di essa fino alla prossima intestazione, quindi una chiave semplice posta sotto un blocco diventerebbe silenziosamente parte di quel blocco. Chi scrive quindi mette ogni scalare di primo livello sopra la prima intestazione.

Per questa coppia raramente capita, perché l’ingresso è una lista e tutto finisce dentro un blocco. Conta quando modificate il file in seguito: aggiungere una chiave version in fondo al file la mette dentro l’ultimo record invece che al livello superiore, l’errore più comune che le persone commettono col TOML.

Il TOML 1.0 ha quattro tipi di data e ora, incluso un date-time con offset che è un valore vero e non testo. Il JSON non ne ha nessuno — ogni timestamp in ogni file JSON è una stringa o un numero per convenzione — quindi un valore come "2024-01-01T00:00:00Z" viene scritto come stringa TOML tra virgolette.

È corretto e non è ciò che il formato potrebbe esprimere. Se lo strumento che legge il file vuole una data-ora vera, rimuovere le virgolette su quelle righe è tutta la correzione, e niente altro nel file deve cambiare.

Qualche dozzina è comodo. Qualche centinaio è un file che nessuno leggerà ma uno strumento analizzerà ancora rapidamente. Qualche migliaio di blocchi è un file di configurazione solo di nome, e a quel punto ogni proprietà che rendeva il TOML attraente — diff leggibili, modifica a mano, commenti accanto ai valori — ha smesso di applicarsi.

La regola d’arresto vale la pena applicarla onestamente: se nessuno aprirà il file, non convertitelo in un formato di configurazione. Il CSV è più piccolo e ogni strumento lo legge, il JSON è ciò che i dati già erano, e un database è ciò che volete se la lista verrà interrogata.

I commenti, che è l’intera ragione per cui i formati di configurazione hanno questo aspetto. Il JSON non ne ha, e nemmeno un file delimitato da nuove righe fatto di esso, quindi le ragioni dietro i valori in un set di fixture vivono attualmente in un messaggio di commit o nella testa di nessuno.

Una volta che il file è TOML, quelle ragioni possono stare accanto alle voci: perché questo record è escluso da un test, quale identificativo a monte un valore deve corrispondere, cosa si rompe se una voce viene riordinata. I primi minuti dopo la conversione sono il momento più economico per scriverlo.

Entrambe le metà sono JavaScript in questa scheda: il file viene analizzato riga per riga e il TOML viene scritto da una piccola libreria caricata al bisogno. Niente viene caricato, non c’è account, e il livello gratuito accetta fino a 100 MB.

Il punto sulla privacy si applica comunque anche a questa scala. Un set di fixture è spesso dati reali con i nomi lasciati dentro, e un file seme per un database di sviluppo è frequentemente una fetta di produzione. Non inviarlo da nessuna parte è una decisione più piccola qui che su un file di log, ed è comunque quella giusta.