Convertire TOML in NDJSON

Un documento TOML è una tabella. Non esiste un file TOML che sia una lista al livello superiore — la specifica non lo permette — quindi il confine di record di cui NDJSON ha bisogno non appare mai dentro un singolo file. L'intero documento diventa una riga.

Per la maggior parte delle sorgenti sarebbe un limite. Qui è la forma del problema: nessuno vuole un pyproject.toml diviso in frammenti, e chiunque ne converta uno in NDJSON sta costruendo una collezione dove ogni file è un record. L'unità del formato e l'unità della domanda capitano di coincidere, cosa non vera per ogni coppia su questo sito.

Il flusso di lavoro è: convertire ogni file, aggiungere la riga a un output crescente. Poiché ogni riga è un valore JSON completo e autonomo e nulla avvolge il file — nessun array che racchiude, nessuna virgola tra i record — la concatenazione è l'intero passo di unione. Due righe da due conversioni sono un file NDJSON valido a due record.

Ciò che si ottiene è un dataset a cui si possono porre domande. Quali crate fissano una versione specifica di dipendenza, quali pacchetti non dichiarano alcuna licenza, quali repository puntano ancora a una vecchia edizione — sono tutte un'unica query sulla collezione invece di uno script che percorre directory e analizza file. Costruire quell'inventario è molto più utile che leggere una singola config, ed è il motivo per cui questa coppia esiste.

Un record senza sorgente è quasi inutile in un inventario. Il convertitore legge il contenuto di un file e nient'altro — non conosce il percorso, il repository o il commit — quindi la riga che produce non ha alcun campo che dica da dove viene.

Lo si aggiunge da sé, in uno di due momenti. Un passaggio jq durante la concatenazione può iniettare una chiave percorso per riga, mantenendo intoccati i file TOML, l'approccio giusto per una flotta che non si possiede. In alternativa, una chiave dentro ogni file TOML lo nomina, sopravvivendo a ogni conversione futura ma significando modificare file che appartengono ad altri. Il primo scala; il secondo è più onesto quando il file dovrebbe davvero identificarsi da sé.

JSON compatto: nessuna indentazione, nessuno spazio dopo i due punti, chiavi nell'ordine dichiarato dal TOML, terminante con un a capo. Le tabelle diventano oggetti nidificati e gli array di tabelle diventano array di oggetti, quindi un elenco autori o un insieme di target di build arriva nella forma che un motore di query si aspetta.

La riga è lunga quanto la config. Un pyproject.toml sono pochi kilobyte e una config generata adiacente a un lock può essere molto più grande, e un lettore che elabora una riga alla volta deve tenere l'intera riga in memoria. Raramente è un problema alle dimensioni tipiche di una config, e vale la pena saperlo prima che qualcuno punti questo a un file che non è davvero una config.

TOML ha veri tipi temporali e JSON no, quindi ogni data e datetime diventa una stringa. Gli offset sopravvivono invece di essere normalizzati a UTC, una data locale arriva esattamente come scritta, e un'ora locale guadagna una componente millisecondi che non aveva nella sorgente. La maggior parte dei caricatori li leggerà come testo a meno che lo schema di destinazione non dica diversamente.

Due letterali float sono lossy in un modo che nulla segnala: inf e nan sono TOML validi e diventano null in JSON, quindi un limite infinito configurato e uno non configurato diventano indistinguibili nel dataset. Anche la distinzione intero-float sparisce, dato che 1.0 si serializza come 1 — importante se una query deve distinguere una versione da un conteggio.

TOML 1.0 richiede interi con segno a 64 bit e i numeri JSON sono double IEEE, quindi un valore sopra circa nove quadrilioni non può essere rappresentato esattamente. Il parser si ferma con un errore che nomina la riga invece di scrivere un numero arrotondato nel dataset.

È il comportamento corretto per un inventario in particolare, dove un numero sbagliato sarebbe indistinguibile da uno giusto su diecimila record. Quando succede, si mette tra virgolette il valore come stringa nel file sorgente — era un identificatore piuttosto che una quantità in ogni caso reale in cui questo capita.

Le config di progetti diversi non avranno le stesse sezioni. Una dichiara una tabella tool con tre linter dentro, la successiva non ne dichiara nessuna, una terza usa una chiave che nessun altro usa. Ogni riga porta solo le chiavi che il suo file aveva, un vero vantaggio rispetto ad appiattire la stessa collezione in una tabella dove le colonne dovrebbero essere l'unione di tutto.

La destinazione decide quanto costa. Un archivio schema-on-read gestisce nativamente i record irregolari e lascia che una query chieda una chiave che solo alcuni record portano. Un caricatore con uno schema fisso rifiuterà gli outlier o scarterà i campi. Si campionano i file più larghi e più stretti della collezione prima di definire la destinazione, invece che dopo aver caricato ottomila record.

I commenti TOML sono il ragionamento dentro una config: perché una dipendenza è fissata, a quale ticket appartiene un workaround, cosa significa un numero magico. NDJSON è JSON per riga e JSON non ha sintassi commenti, quindi tutto ciò sparisce dal dataset.

È accettabile per un inventario e non accettabile come migrazione. Nessuno che interroghi quali pacchetti fissano una versione ha bisogno della prosa circostante; chiunque sostituisca i file TOML con qualcosa generato da questi dati la starebbe buttando via. Si usa lo stream per rispondere a domande sulle config, e si lasciano le config dove sono.

Se si ha solo una config da leggere, la si converte in JSON invece. Il JSON indentato è leggibile, jq lo gestisce identicamente, e un file a una riga è peggiore per ogni scopo eccetto l'aggiunta. NDJSON si guadagna il suo posto nel punto in cui ci sono molti file e vanno in qualcosa.

L'altro confine è la ricorrenza. Se l'inventario deve essere ricostruito su un programma, il lavoro appartiene a uno script che percorre l'albero, analizza ogni file con una vera libreria TOML ed emette le righe con il percorso già allegato. Questo convertitore serve per costruire il dataset la prima volta, decidere se le domande a cui risponde valgono la pena di essere automatizzate, e farlo senza che nessuno dei file lasci la propria macchina.