Convertir NDJSON en TOML

On suppose que TOML ne peut pas contenir ce que JSON contient, et pour une liste d’enregistrements c’est faux. Un tableau de tables s’écrit comme le même en-tête répété entre doubles crochets — [[items]] trois fois donne trois enregistrements — avec chaque bloc portant ses propres clés en dessous. C’est le construct que Cargo utilise pour les dépendances et que Hugo utilise pour les entrées de menu.

Comparé au JSON dont il vient, il est plus verbeux et considérablement plus facile à éditer. Ajouter un enregistrement signifie copier quatre lignes plutôt que d’équilibrer des crochets et de se souvenir d’une virgule, et un diff d’une modification à un seul enregistrement ne touche que ce bloc. Pour un fichier qu’une personne maintient, c’est tout l’argument.

Un document TOML doit être une table au niveau supérieur, et un fichier délimité par des sauts de ligne est une liste sans nom propre. La liste reçoit donc un nom de placeholder : la sortie est une suite de blocs [[items]], un par ligne de la source.

Ce nom est la première chose à changer, et c’est une recherche-remplacement sur les en-têtes de bloc — en [[dependencies]], [[authors]], [[products]], peu importe ce que l’outil qui lit le fichier attend. Il n’y a rien dans un fichier NDJSON qui puisse dire au convertisseur ce que sont les enregistrements, donc le placeholder est délibéré et volontairement évident plutôt qu’une supposition qui pourrait sembler plausible et être fausse.

C’est l’avantage discret de TOML sur toutes les destinations tabulaires pour le même fichier. Un CSV, un fichier Parquet ou une suite d’instructions INSERT doit rapprocher les enregistrements en un seul ensemble de colonnes, en remplissant les vides là où un enregistrement n’avait rien. Un tableau de tables ne le fait pas : chaque bloc porte exactement les clés que sa ligne avait.

Donc un fichier où des enregistrements tardifs ont gagné un champ se convertit sans nulls, sans cellules vides et sans élargissement. Le résultat se lit comme ce qu’il est — une liste d’enregistrements qui se ressemblent pour l’essentiel — plutôt que comme une grille clairsemée. Pour un jeu de fixtures assemblé au fil du temps, c’est en général la représentation la plus honnête.

TOML n’a pas de littéral null, et l’écrivain n’en invente pas. Une clé dont la valeur JSON était null n’est tout simplement pas écrite dans le bloc, au niveau supérieur d’un enregistrement ou n’importe où à l’intérieur.

Savoir si cela compte est une question sur l’outil qui lit le fichier. Beaucoup traitent une clé manquante et une valeur vide de la même manière, en retombant sur un défaut dans les deux cas, et pour ceux-là rien n’a été perdu. Là où la distinction pilote le comportement, la conversion a silencieusement changé les données, et la défense la moins coûteuse est de chercher `null` dans la source avant de convertir plutôt que de comparer les deux fichiers après — une ligne absente est bien plus difficile à repérer qu’une ligne modifiée.

Un enregistrement avec un objet imbriqué produit une sous-table sous son bloc : un objet `author` à l’intérieur d’un enregistrement devient un en-tête `[items.author]` avec ses clés en dessous. La profondeur s’exprime dans l’en-tête plutôt que dans l’indentation, donc même trois niveaux restent à plat sur la page.

C’est légal à n’importe quelle profondeur et désagréable au-delà de deux ou trois. Un en-tête comme `[items.metadata.source.system]` est valide et personne n’apprécie le lire, et un fichier de fixtures qui produit ceux-là porte généralement plus de structure qu’un fichier édité à la main ne devrait. C’est un signal sur les données plutôt que sur la conversion.

Un en-tête de table TOML s’approprie chaque ligne écrite après lui jusqu’à l’en-tête suivant, donc une clé nue placée sous un bloc deviendrait silencieusement membre de ce bloc. L’écrivain place donc tout scalaire de niveau supérieur au-dessus du premier en-tête.

Pour cette paire cela survient rarement, parce que l’entrée est une liste et que tout finit à l’intérieur d’un bloc. Cela compte quand vous éditez le fichier ensuite : ajouter une clé `version` au bas du fichier la met dans le dernier enregistrement plutôt qu’au niveau supérieur, ce qui est l’erreur la plus courante que les gens font avec TOML. Ajoutez ces clés en haut, au-dessus du premier en-tête à double crochet.

TOML 1.0 a quatre types de date et heure, dont une date-heure avec décalage qui est une vraie valeur plutôt que du texte. JSON n’en a aucun — chaque horodatage dans chaque fichier JSON est une chaîne ou un nombre par convention — donc une valeur comme « 2024-01-01T00:00:00Z » est écrite en chaîne TOML entre guillemets.

C’est correct et ce n’est pas ce que le format pourrait exprimer. Si l’outil qui lit le fichier veut une vraie date-heure, retirer les guillemets sur ces lignes est toute la correction, et rien d’autre dans le fichier n’a à changer. C’est une chose raisonnable à faire pendant que vous êtes en train de renommer les en-têtes de bloc.

Quelques dizaines est confortable. Quelques centaines est un fichier que personne ne lira mais qu’un outil continuera d’analyser rapidement. Quelques milliers de blocs est un fichier de configuration de nom seulement, et à ce moment toute propriété qui rendait TOML attractif — diffs lisibles, édition à la main, commentaires à côté des valeurs — a cessé de s’appliquer.

La règle d’arrêt mérite d’être appliquée honnêtement : si personne n’ouvrira le fichier, ne le convertissez pas vers un format de configuration. CSV est plus petit et tout outil le lit, JSON est ce que les données étaient déjà, et une base de données est ce que vous voulez si la liste va être interrogée. TOML ne gagne sa place que lorsqu’une personne maintiendra le résultat.

Des commentaires, ce qui est toute la raison pour laquelle les formats de configuration ressemblent à cela. JSON n’en a pas, et un fichier délimité par des sauts de ligne fait de même, donc les raisons derrière les valeurs dans un jeu de fixtures vivent actuellement dans un message de commit ou dans la tête de personne.

Une fois le fichier en TOML, ces raisons peuvent s’asseoir à côté des entrées : pourquoi cet enregistrement est exclu d’un test, à quel identifiant amont une valeur doit correspondre, ce qui casse si une entrée est réordonnée. C’est l’information qu’un fichier généré n’a jamais pu porter, et les premières minutes après la conversion sont le moment le moins coûteux pour l’écrire.

Les deux moitiés sont du JavaScript dans cet onglet : le fichier est analysé ligne par ligne et le TOML est écrit par une petite bibliothèque chargée à la demande. Rien n’est téléversé, il n’y a ni compte, et le niveau gratuit accepte jusqu’à 100 Mo — ce qui, pour un fichier pour lequel cette conversion est appropriée, n’est une limite que personne n’atteint.

L’argument de confidentialité s’applique toujours même à cette échelle. Un jeu de fixtures est souvent de vraies données dont les noms sont restés, et un fichier de seed pour une base de développement est fréquemment une tranche de production. Ne pas l’envoyer ailleurs est ici une décision plus petite que sur un fichier de journal, et c’est toujours le bon défaut.