Di Jerry Fan

JSONL in JavaScript: lettura, scrittura e parsing

Una guida completa per lavorare con i file JSONL (JSON Lines) in JavaScript. Impara a leggere, scrivere, fare il parsing ed elaborare in streaming i dati JSONL, sia in Node.js sia nel browser, con le API native e le librerie più diffuse.

Perché usare JavaScript per JSONL?

JavaScript si presta bene a lavorare con i file JSONL. Il formato JSON nasce proprio da JavaScript, che offre quindi un supporto nativo al parsing attraverso i metodi JSON.parse() e JSON.stringify(). Che tu stia realizzando una pipeline di dati in Node.js, elaborando file di log su un server o consentendo agli utenti di caricare file JSONL nel browser, JavaScript ti mette a disposizione gli strumenti per gestire ogni passaggio.

JSONL (JSON Lines) memorizza un oggetto JSON per riga: è quindi ideale per lo streaming, per i log append-only e per elaborare grandi dataset una riga alla volta. Gli stream di Node.js si adattano perfettamente a questo formato e ti permettono di leggere e trasformare milioni di record senza esaurire la memoria. Lato client, le API FileReader e Streams del browser consentono di elaborare i dati JSONL interamente sul dispositivo dell'utente. In questa guida imparerai a leggere i dati JSONL sia in Node.js sia nel browser, a scrivere file JSONL, a creare pipeline di trasformazione in streaming e a scegliere la libreria npm più adatta al tuo progetto.

Leggere file JSONL in Node.js

Node.js mette a disposizione il modulo readline per leggere i file in modo efficiente, una riga alla volta. Usarlo insieme a fs.createReadStream è il metodo consigliato per elaborare i file JSONL sul server, perché consente di leggere i dati in streaming senza caricare l'intero file in memoria.

Passa lo stream creato con fs.createReadStream a readline.createInterface per leggere un file JSONL una riga alla volta. Questo approccio richiede pochissima memoria, indipendentemente dalle dimensioni del file.

Lettura in streaming con 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]);

Per i file JSONL piccoli, che puoi caricare in memoria senza problemi, puoi leggere tutto il file in una volta e suddividerlo in corrispondenza dei caratteri di fine riga. È una soluzione più semplice, che rinuncia all'efficienza dello streaming.

Una soluzione rapida in una riga (file piccoli)
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`);

Leggere file JSONL nel browser

Nel browser, gli utenti possono caricare file JSONL tramite un campo di selezione file. Puoi leggerli con l'API FileReader o con la più recente API Streams, senza inviare dati a un server.

Usa FileReader per leggere un file selezionato dall'utente, poi suddividi il testo in righe ed esegui il parsing di ciascuna. Tutti i dati rimangono lato client, a tutela della privacy.

API FileReader del browser
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`);
});

Per gestire file di grandi dimensioni nel browser, usa l'API Streams con TextDecoderStream ed elabora il file un blocco alla volta. In questo modo eviti di caricarlo interamente in memoria.

API Streams del browser (file grandi)
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);
}

Scrivere file JSONL in Node.js

Scrivere file JSONL in Node.js è semplice: serializza ogni oggetto JavaScript in una stringa JSON e aggiungi un carattere di fine riga. Per ottenere le migliori prestazioni con grandi dataset, usa uno stream di scrittura invece di costruire l'intera stringa in memoria.

Usa fs.writeFileSync o fs.createWriteStream per scrivere i record in un file JSONL. Ogni record occupa una sola riga di JSON valido, seguita da un carattere di fine riga.

Scrittura di base con 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`);

Quando scrivi milioni di record, usa uno stream di scrittura per evitare di costruire l'intera stringa di output in memoria. Lo stream gestisce automaticamente la backpressure, sospendendo le scritture quando il buffer del sistema operativo è pieno.

Scrittura in streaming per grandi volumi di dati
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);

Stream Transform per le pipeline JSONL

Gli stream Transform di Node.js ti permettono di creare pipeline di dati componibili che leggono i dati JSONL, elaborano ogni record e scrivono i risultati. Questo pattern è ideale per i job ETL, l'elaborazione dei log e la migrazione dei dati.

Stream Transform per le pipeline 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');

Questa pipeline legge un file JSONL una riga alla volta, applica una trasformazione a ogni record (aggiungendo i campi processed e processedAt) e scrive i risultati in un nuovo file. Lo stream Transform gestisce automaticamente la backpressure, mantenendo costante l'uso della memoria anche con file molto grandi. Puoi concatenare più trasformazioni per creare flussi di lavoro ETL complessi.

Librerie JavaScript per JSONL

Il metodo nativo JSON.parse gestisce bene la maggior parte dei casi, ma diversi pacchetti npm offrono funzioni utili per le operazioni specifiche di JSONL, come lo streaming, la validazione e l’elaborazione in batch.

JSON.parse (nativo)

Nativo

I metodi nativi JSON.parse() e JSON.stringify() sono molto ottimizzati in V8 e bastano per la maggior parte degli utilizzi di JSONL. Usali insieme a readline per lo streaming. Non servono dipendenze e le prestazioni sono ottime per file fino a diverse centinaia di MB.

ndjson

Diffuso

ndjson è un pacchetto npm molto diffuso che offre parser e serializzatori JSONL (Newline Delimited JSON) in streaming, compatibili con gli stream di Node.js. Gestisce gli errori di parsing in modo controllato e si integra bene con le pipeline di stream esistenti. È ottimo per creare rapidamente prototipi.

jsonl-parse-stringify

Semplice

jsonl-parse-stringify è una libreria leggera, senza dipendenze, che offre i semplici metodi parse() e stringify() per i dati JSONL. Gestisce i casi limite, come i caratteri di fine riga finali e le righe vuote. È ideale se cerchi un'API sincrona essenziale, senza dover configurare gli stream.

Lavora con i file JSONL online

Visualizza, valida e converti file JSONL fino a 1GB direttamente nel browser. Senza caricarli su un server, con il 100% di privacy.

Domande frequenti

Riferimenti