Por Jerry Fan

JSONL em JavaScript: leitura, escrita e parsing

Um guia completo para trabalhar com arquivos JSONL (JSON Lines) em JavaScript. Aprenda a ler, escrever, fazer o parsing e processar dados JSONL em streaming, tanto no Node.js quanto no navegador, usando APIs nativas e bibliotecas populares.

Por que usar JavaScript para trabalhar com JSONL?

JavaScript é uma escolha natural para trabalhar com arquivos JSONL. O próprio JSON surgiu do JavaScript, e a linguagem oferece suporte nativo por meio dos métodos JSON.parse() e JSON.stringify(). Seja para criar um pipeline de dados em Node.js, processar arquivos de log em um servidor ou permitir que usuários carreguem arquivos JSONL no navegador, JavaScript oferece as ferramentas necessárias para cada etapa.

JSONL (JSON Lines) armazena um objeto JSON por linha, o que o torna ideal para streaming, logs em que os registros são apenas acrescentados e processamento de grandes conjuntos de dados linha por linha. Os streams do Node.js se adaptam perfeitamente a esse formato e permitem ler e transformar milhões de registros sem esgotar a memória. No lado do cliente, as APIs FileReader e Streams do navegador permitem processar JSONL inteiramente no dispositivo do usuário. Neste guia, você vai aprender a ler JSONL no Node.js e no navegador, escrever arquivos JSONL, criar pipelines de transformação com streaming e escolher a biblioteca npm mais adequada para o seu projeto.

Leitura de JSONL no Node.js

O Node.js oferece o módulo readline para ler arquivos linha por linha de forma eficiente. Em conjunto com fs.createReadStream, essa é a abordagem recomendada para processar arquivos JSONL no servidor, pois lê os dados em streaming sem carregar o arquivo inteiro na memória.

Use fs.createReadStream como entrada de readline.createInterface para ler um arquivo JSONL uma linha por vez. Essa abordagem consome pouca memória, independentemente do tamanho do arquivo.

Leitura em streaming com readline
import { createReadStream } from 'node:fs';
import { createInterface } from 'node:readline';


async function readJsonl(filePath) {
  const records = [];
  const rl = createInterface({
    input: createReadStream(filePath, 'utf-8'),
    crlfDelay: Infinity,
  });


  for await (const line of rl) {
    const trimmed = line.trim();
    if (trimmed) {
      records.push(JSON.parse(trimmed));
    }
  }
  return records;
}


// Usage
const data = await readJsonl('data.jsonl');
console.log(`Loaded ${data.length} records`);
console.log(data[0]);

Para arquivos JSONL pequenos que cabem com folga na memória, você pode ler todo o conteúdo de uma vez e separá-lo pelas quebras de linha. Essa abordagem abre mão da eficiência do streaming em favor da simplicidade.

Solução rápida em uma linha para arquivos pequenos
import { readFileSync } from 'node:fs';


const records = readFileSync('data.jsonl', 'utf-8')
  .split('\n')
  .filter(line => line.trim())
  .map(line => JSON.parse(line));


console.log(`Loaded ${records.length} records`);

Leitura de JSONL no navegador

No navegador, os usuários podem carregar arquivos JSONL por meio de um campo de seleção de arquivo. Você pode ler o arquivo com a API FileReader ou com a moderna API Streams, sem enviar dados para um servidor.

Use FileReader para ler um arquivo selecionado pelo usuário. Depois, separe o texto em linhas e faça o parsing de cada uma. Todos os dados ficam no lado do cliente, preservando a privacidade.

API FileReader do navegador
function parseJsonlFile(file) {
  return new Promise((resolve, reject) => {
    const reader = new FileReader();
    reader.onload = () => {
      const text = reader.result;
      const records = text
        .split('\n')
        .filter(line => line.trim())
        .map(line => JSON.parse(line));
      resolve(records);
    };
    reader.onerror = () => reject(reader.error);
    reader.readAsText(file, 'utf-8');
  });
}


// Usage with an <input type="file"> element
const input = document.querySelector('input[type="file"]');
input.addEventListener('change', async (e) => {
  const file = e.target.files[0];
  const records = await parseJsonlFile(file);
  console.log(`Parsed ${records.length} records`);
});

Para arquivos grandes no navegador, use a API Streams com TextDecoderStream para processar o arquivo em blocos. Assim, você evita carregar todo o arquivo na memória de uma só vez.

API Streams do navegador para arquivos grandes
async function* streamJsonl(file) {
  const stream = file.stream()
    .pipeThrough(new TextDecoderStream());
  const reader = stream.getReader();
  let buffer = '';


  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    buffer += value;
    const lines = buffer.split('\n');
    buffer = lines.pop(); // Keep incomplete last line
    for (const line of lines) {
      const trimmed = line.trim();
      if (trimmed) yield JSON.parse(trimmed);
    }
  }
  // Handle remaining buffer
  if (buffer.trim()) {
    yield JSON.parse(buffer.trim());
  }
}


// Usage
for await (const record of streamJsonl(file)) {
  console.log(record);
}

Escrita de JSONL no Node.js

Escrever arquivos JSONL no Node.js é simples: serialize cada objeto JavaScript em uma string JSON e acrescente um caractere de quebra de linha. Para obter melhor desempenho com grandes conjuntos de dados, use um stream de escrita em vez de montar a string inteira na memória.

Use fs.writeFileSync ou fs.createWriteStream para escrever registros em um arquivo JSONL. Cada registro ocupa uma única linha de JSON válido, seguida de uma quebra de linha.

Escrita básica com fs
import { writeFileSync } from 'node:fs';


const records = [
  { id: 1, name: 'Alice', role: 'engineer' },
  { id: 2, name: 'Bob', role: 'designer' },
  { id: 3, name: 'Charlie', role: 'manager' },
];


const jsonl = records
  .map(record => JSON.stringify(record))
  .join('\n') + '\n';


writeFileSync('output.jsonl', jsonl, 'utf-8');
console.log(`Wrote ${records.length} records`);

Ao escrever milhões de registros, use um stream de escrita para evitar montar toda a string de saída na memória. O stream gerencia o backpressure automaticamente, pausando as escritas quando o buffer do sistema operacional está cheio.

Escrita em streaming para grandes volumes de dados
import { createWriteStream } from 'node:fs';


async function writeJsonl(filePath, records) {
  const stream = createWriteStream(filePath, 'utf-8');


  for (const record of records) {
    const line = JSON.stringify(record) + '\n';
    // Respect backpressure
    if (!stream.write(line)) {
      await new Promise(resolve => stream.once('drain', resolve));
    }
  }


  stream.end();
  await new Promise(resolve => stream.on('finish', resolve));
  console.log('Write complete');
}


// Usage
const data = Array.from({ length: 100000 }, (_, i) => ({
  id: i + 1,
  value: Math.random(),
  timestamp: new Date().toISOString(),
}));


await writeJsonl('large_output.jsonl', data);

Streams Transform para pipelines JSONL

Os streams Transform do Node.js permitem criar pipelines de dados com etapas que podem ser combinadas para ler JSONL, processar cada registro e escrever os resultados. Esse padrão é ideal para tarefas de ETL, processamento de logs e migração de dados.

Streams Transform para pipelines JSONL
import { createReadStream, createWriteStream } from 'node:fs';
import { createInterface } from 'node:readline';
import { Transform } from 'node:stream';
import { pipeline } from 'node:stream/promises';


// Transform: parse JSONL line into object, process, stringify back
const transformJsonl = new Transform({
  objectMode: true,
  transform(chunk, encoding, callback) {
    const line = chunk.toString().trim();
    if (!line) return callback();
    try {
      const record = JSON.parse(line);
      // Add your transformation here
      record.processed = true;
      record.processedAt = new Date().toISOString();
      callback(null, JSON.stringify(record) + '\n');
    } catch (err) {
      callback(err);
    }
  },
});


// Build the pipeline
const rl = createInterface({
  input: createReadStream('input.jsonl', 'utf-8'),
  crlfDelay: Infinity,
});


const output = createWriteStream('output.jsonl', 'utf-8');


for await (const line of rl) {
  transformJsonl.write(line);
}
transformJsonl.end();
await pipeline(transformJsonl, output);
console.log('Pipeline complete');

Este pipeline lê um arquivo JSONL linha por linha, aplica uma transformação a cada registro (adicionando os campos processed e processedAt) e escreve os resultados em um novo arquivo. O stream Transform gerencia o backpressure automaticamente, mantendo o uso de memória constante mesmo com arquivos muito grandes. Você pode encadear várias transformações para criar fluxos de ETL complexos.

Bibliotecas JavaScript para JSONL

Embora o método nativo JSON.parse atenda bem à maioria dos casos, vários pacotes npm oferecem utilitários que facilitam tarefas específicas com JSONL, como streaming, validação e processamento em lote.

JSON.parse (nativo)

Nativo

Os métodos nativos JSON.parse() e JSON.stringify() são altamente otimizados no V8 e suficientes para a maioria dos casos de uso de JSONL. Combine-os com readline para processar dados em streaming. Não é preciso instalar dependências, e o desempenho é excelente para arquivos de até várias centenas de MB.

ndjson

Popular

ndjson é um pacote npm popular que oferece parsers e serializadores de JSONL (Newline Delimited JSON) para streaming, compatíveis com os streams do Node.js. Ele trata erros de parsing de forma controlada e se integra bem a pipelines de streams existentes. É uma ótima opção para criar protótipos rapidamente.

jsonl-parse-stringify

Simples

jsonl-parse-stringify é uma biblioteca leve e sem dependências que oferece os métodos simples parse() e stringify() para dados JSONL. Ela trata casos especiais, como quebras de linha no final do conteúdo e linhas vazias. É ideal quando você quer uma API síncrona simples, sem precisar configurar streams.

Trabalhe com arquivos JSONL online

Visualize, valide e converta arquivos JSONL de até 1GB diretamente no navegador. Sem necessidade de upload, com 100% de privacidade.

Perguntas frequentes

Referências