Converter NDJSON para TOML

Muita gente presume que o TOML não consegue guardar o que o JSON guarda, e para uma lista de registros isso está errado. Um array de tabelas é escrito como o mesmo cabeçalho repetido entre colchetes duplos — três vezes dá três registros — com cada bloco carregando suas próprias chaves embaixo. É a construção que ferramentas de configuração de dependência usam, e que geradores de site estático usam para entradas de menu.

Comparado ao JSON de onde veio, fica mais verboso e consideravelmente mais fácil de editar. Adicionar um registro significa copiar quatro linhas em vez de equilibrar colchetes e lembrar de uma vírgula, e uma alteração num registro só toca aquele bloco no controle de versão. Para um arquivo que uma pessoa mantém à mão, esse é o argumento inteiro.

Um documento TOML precisa ser uma tabela no nível mais alto, e um arquivo delimitado por quebra de linha é uma lista sem nome próprio. Então a lista recebe um nome provisório: o resultado é uma sequência de blocos items, um por linha da origem.

Esse nome é a primeira coisa a mudar, e é uma busca e substituição sobre os cabeçalhos de bloco — para dependencies, authors, produtos, o que a ferramenta que vai ler o arquivo esperar. Não há nada num arquivo NDJSON que pudesse dizer ao conversor o que os registros são, então o nome provisório é proposital e deliberadamente óbvio, em vez de um chute que pareceria plausível e estaria errado.

Essa é a vantagem discreta do TOML sobre qualquer destino tabular para o mesmo arquivo. Um CSV, um Parquet ou uma sequência de comandos de inserção precisa reconciliar os registros num conjunto único de colunas, preenchendo lacunas onde um registro não tinha nada. Um array de tabelas não precisa: cada bloco carrega exatamente as chaves que sua linha tinha.

Então um arquivo em que registros mais recentes ganharam um campo novo converte sem valor vazio, sem célula em branco, sem alargar nada. O resultado lê como o que é — uma lista de registros parecidos entre si, não idênticos — em vez de uma grade esparsa.

O TOML não tem um literal de nulo, e o gravador não inventa um. Uma chave cujo valor no JSON era nulo simplesmente não é escrita no bloco, no nível superior de um registro ou em qualquer lugar dentro dele.

Se isso importa é uma pergunta sobre a ferramenta que vai ler o arquivo. Muitas tratam uma chave ausente e um valor vazio da mesma forma, caindo num padrão de qualquer jeito, e para essas nada se perdeu. Onde a distinção muda o comportamento, a conversão alterou o dado em silêncio, e a defesa mais barata é procurar por nulo na origem antes de converter, não comparar os dois arquivos depois — uma linha ausente é bem mais difícil de notar que uma linha alterada.

Um registro com um objeto aninhado produz uma subtabela sob seu bloco: um objeto de autor dentro de um registro vira um cabeçalho items.autor com as chaves dele embaixo. A profundidade é expressa no cabeçalho, não em indentação, então mesmo três níveis ficam planos na página.

É válido em qualquer profundidade e desagradável depois de dois ou três níveis. Um cabeçalho como items.metadado.origem.sistema é válido e ninguém gosta de ler isso, e um arquivo de teste que produz esses cabeçalhos costuma carregar mais estrutura do que um arquivo mantido à mão deveria ter. Isso é um sinal sobre o dado, não sobre a conversão.

Um cabeçalho de tabela TOML reivindica toda linha escrita depois dele até o próximo cabeçalho, então uma chave solta colocada abaixo de um bloco silenciosamente se tornaria parte daquele bloco. O gravador, por isso, coloca qualquer valor de nível superior acima do primeiro cabeçalho.

Para este par isso raramente aparece, porque a entrada é uma lista e tudo acaba dentro de um bloco. Importa quando você edita o arquivo depois: adicionar uma chave de versão no fim do arquivo a coloca dentro do último registro em vez do nível superior, o erro mais comum que as pessoas cometem com TOML. Adicione chaves assim no topo, acima do primeiro cabeçalho de colchete duplo.

O TOML tem tipos próprios de data e hora, incluindo um valor de data-hora com fuso que é um tipo real, não texto. O JSON não tem nenhum — toda marcação de tempo em qualquer arquivo JSON é uma string ou um número por convenção — então um valor de data escrito como texto no JSON é escrito como uma string entre aspas no TOML.

Isso é correto e não é o que o formato poderia expressar. Se a ferramenta que vai ler o arquivo quer uma data-hora de verdade, remover as aspas nessas linhas é o ajuste inteiro, e nada mais no arquivo precisa mudar. É uma coisa razoável de fazer enquanto você já está renomeando os cabeçalhos de bloco.

Algumas dezenas é confortável. Algumas centenas é um arquivo que ninguém vai ler, mas uma ferramenta ainda interpreta rápido. Alguns milhares de blocos é um arquivo de configuração só no nome, e nesse ponto toda propriedade que tornava o TOML atraente — diferença legível, edição manual, comentário ao lado do valor — já deixou de valer.

A regra de parada vale aplicar com honestidade: se ninguém vai abrir o arquivo, não converta para um formato de configuração. CSV é menor e qualquer ferramenta lê, JSON é o que o dado já era, e um banco de dados é o que você quer se a lista vai ser consultada. O TOML só ganha o lugar dele quando uma pessoa vai manter o resultado.

Comentário, que é o motivo inteiro de formatos de configuração terem essa cara. O JSON não tem nenhum, e nem o arquivo delimitado por linha feito a partir dele, então os motivos por trás dos valores de um arquivo de teste hoje vivem numa mensagem de commit ou na cabeça de alguém só.

Uma vez que o arquivo é TOML, esses motivos podem ficar ao lado das entradas: por que este registro é excluído de um teste, com qual identificador externo um valor precisa bater, o que quebra se uma entrada for reordenada. Essa é a informação que um arquivo gerado nunca poderia carregar, e os primeiros minutos depois da conversão são o momento mais barato de escrever isso.

As duas metades são JavaScript rodando nesta aba: o arquivo é interpretado linha por linha, e o TOML é escrito por uma biblioteca pequena carregada sob demanda. Nada é enviado, não há conta, e o plano gratuito aceita até 100 MB — um limite que ninguém chega perto para um arquivo do tamanho que esta conversão é apropriada.

O ponto de privacidade continua valendo mesmo nessa escala pequena. Um conjunto de dados de teste costuma ser dado real com o nome deixado dentro, e um arquivo semente para um banco de dados de desenvolvimento costuma ser uma fatia de produção. Não enviar isso a lugar nenhum é uma decisão menor aqui do que num arquivo de log, mas continua sendo a atitude certa por padrão.