TOML in NDJSON umwandeln

Ein TOML-Dokument ist immer eine Tabelle, es gibt in der Spezifikation keine TOML-Datei, die auf oberster Ebene eine Liste ist. Genau die Grenze, an der NDJSON eine neue Zeile beginnt, taucht in einer einzelnen TOML-Datei also nie auf — das ganze Dokument wird zu einer Zeile.

Bei den meisten Quellformaten wäre das eine Einschränkung. Hier ist es die Form der Aufgabe: Niemand will eine pyproject.toml in Fragmente zerlegt sehen, und wer eine TOML-Datei nach NDJSON umwandelt, baut fast immer eine Sammlung, in der jede Datei ein Datensatz ist.

Bei einem gewachsenen Microservice-Zuschnitt hat jeder Dienst seine eigene Cargo.toml oder pyproject.toml, mit eigenen Abhängigkeitsversionen, eigenem Edition- oder Python-Ziel, eigenen Lizenzangaben. Zusammen ergeben sie eine Frage, die keine einzelne Datei beantworten kann: Welcher Dienst hängt noch an einer alten Major-Version, welcher deklariert überhaupt keine Lizenz.

Der Weg dahin ist mechanisch: jede Datei einzeln umwandeln, jede Zeile an eine wachsende Ausgabedatei anhängen. Weil jede Zeile ein vollständiger, eigenständiger JSON-Wert ist und nichts sie umschließt, ist Aneinanderhängen die gesamte Zusammenführung — zwei Zeilen aus zwei Umwandlungen sind bereits ein gültiges NDJSON mit zwei Datensätzen.

Ein Datensatz ohne Herkunftsangabe ist in einem Inventar fast wertlos. Die Umwandlung liest den Inhalt einer Datei, nicht ihren Pfad, ihr Repository oder ihren Commit — die erzeugte Zeile weiß also nicht, aus welchem Dienst sie stammt.

Das Feld muss an einer von zwei Stellen ergänzt werden. Ein jq-Durchlauf beim Zusammenführen kann pro Zeile einen Pfad-Schlüssel einfügen, ohne die TOML-Dateien selbst anzufassen — der richtige Weg für einen Bestand, den man nicht selbst pflegt. Alternativ trägt jede TOML-Datei ihren eigenen Namen ein, was jede künftige Umwandlung übersteht, aber Dateien betrifft, die vielleicht einem anderen Team gehören.

Kompaktes JSON: keine Einrückung, keine Leerzeichen nach Doppelpunkten, Schlüssel in der Reihenfolge, in der die TOML sie deklariert hat, abgeschlossen mit einem Zeilenumbruch. Tabellen werden zu verschachtelten Objekten, Arrays von Tabellen zu Arrays von Objekten — eine Autorenliste oder eine Menge von Build-Zielen kommt so in der Form an, die eine Abfrage-Engine erwartet.

Die Zeile ist so lang wie die Konfig groß ist. Eine pyproject.toml sind ein paar Kilobyte, eine generierte Lock-nahe Konfig kann deutlich mehr sein, und ein Leser, der zeilenweise arbeitet, hält die ganze Zeile im Speicher. Bei Konfiggrößen ist das selten ein Problem — nur eben nicht mehr, sobald jemand diese Seite auf eine Datei ansetzt, die keine Konfig mehr ist.

TOML kennt echte Zeit- und Datumstypen, JSON nicht, also wird jedes Datum und jeder Zeitstempel zur Zeichenkette. Der Offset bleibt erhalten statt auf UTC normalisiert zu werden, ein lokales Datum kommt genau so an, wie es geschrieben wurde, und eine lokale Uhrzeit gewinnt einen Millisekundenanteil, den sie in der Quelle nicht hatte. Die meisten Lader lesen das als Text, wenn das Zielschema nichts anderes vorgibt.

Zwei Fließkommawerte gehen dabei leise verloren, ohne dass irgendetwas darauf hinweist: inf und nan sind gültiges TOML und werden in JSON zu null, sodass ein konfiguriertes unbegrenztes Limit und ein nicht konfiguriertes im Datensatz nicht mehr zu unterscheiden sind. Auch der Unterschied zwischen Ganzzahl und Fließkommazahl geht verloren, denn 1.0 wird als 1 geschrieben — wichtig, wenn eine Abfrage eine Version von einer Anzahl unterscheiden soll.

TOML 1.0 verlangt 64-Bit-Ganzzahlen, JSON-Zahlen sind IEEE-Doubles, also lässt sich ein Wert oberhalb von etwa neun Billiarden nicht mehr exakt darstellen. Der Parser bricht mit einer Fehlermeldung ab, die die Zeile nennt, statt eine gerundete Zahl in den Datensatz zu schreiben.

Für ein Inventar mit zehntausend Zeilen ist genau das die richtige Reaktion, denn eine falsche Zahl wäre neben den echten nicht mehr zu erkennen. Tritt der Fall auf, den Wert in der Quelle als Zeichenkette in Anführungszeichen setzen — es handelte sich in jedem realen Fall, in dem das vorkommt, ohnehin um eine Kennung und keine Menge.

Konfigs aus unterschiedlichen Diensten sehen sich selten ähnlich. Der eine deklariert eine tool-Tabelle mit drei Linters, der nächste keine, ein dritter verwendet einen Schlüssel, den sonst niemand nutzt. Jede Zeile trägt nur die Schlüssel, die ihre Datei tatsächlich hatte — ein echter Vorteil gegenüber einer Tabelle, deren Spalten die Vereinigung aller Dateien wären.

Was das kostet, entscheidet das Zielsystem. Ein Schema-on-Read-Speicher verkraftet unregelmäßige Datensätze von Haus aus und lässt eine Abfrage nach einem Schlüssel fragen, den nur einige Zeilen tragen. Ein Lader mit festem Schema weist die Ausreißer zurück oder verwirft die Felder. Die breiteste und die schmalste Datei im Bestand vorab zu prüfen, ist billiger als es nach achttausend geladenen Zeilen zu merken.

TOML-Kommentare sind die Begründung in einer Konfig: warum eine Abhängigkeit fixiert ist, zu welchem Ticket ein Workaround gehört, was eine krumme Zahl bedeutet. NDJSON ist JSON pro Zeile, und JSON kennt keine Kommentarsyntax — also fehlt im Datensatz jede einzelne dieser Zeilen.

Für ein Inventar ist das hinnehmbar, für eine Migration nicht. Wer nur fragt, welche Pakete eine Version fixieren, braucht die umgebende Prosa nicht; wer die TOML-Dateien durch etwas aus diesen Daten Generiertes ersetzen will, würde sie wegwerfen. Der Stream beantwortet Fragen über die Konfigs — die Konfigs selbst bleiben dort, wo sie bearbeitet werden.

Liegt nur eine Konfig vor, ist JSON statt NDJSON die richtige Wahl. Eingerücktes JSON ist lesbar, jq behandelt es identisch, und eine Datei mit nur einer Zeile ist für jeden Zweck außer dem Anhängen die schlechtere Wahl. NDJSON verdient seinen Platz erst dort, wo viele Dateien vorliegen und irgendwo hineingehen.

Die andere Grenze ist Wiederholung: Muss das Inventar regelmäßig neu gebaut werden, gehört die Arbeit in ein Skript, das den Verzeichnisbaum durchläuft, jede Datei mit einer echten TOML-Bibliothek liest und die Zeile mit dem Pfad versehen ausgibt. Diese Seite ist dafür da, den Datensatz ein erstes Mal zu bauen und zu prüfen, ob sich die Automatisierung überhaupt lohnt.

Lesen und Schreiben laufen beide als JavaScript auf dieser Seite, im eigenen Browser. Eine Cargo.toml mit einem internen Registry-Token oder eine pyproject.toml mit einer internen Paketquelle verlässt das Gerät nicht — das lässt sich im Netzwerk-Tab während der Umwandlung nachprüfen.

Es gibt keine Warteschlange, kein Konto und keine Obergrenze, die diese Seite setzt, weil dabei keine Serverkapazität verbraucht wird. Bei Konfigdateien liegt die praktische Grenze ohnehin selten am Limit von 100 MB, sondern am Arbeitsspeicher, den ein Tab mit vielen offenen Zeilen braucht.