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.
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.
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.
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.
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.
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.
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.
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)
NativoI 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
Diffusondjson è 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
Semplicejsonl-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.
Prova i nostri strumenti gratuiti per JSONL
Non vuoi scrivere codice? Usa i nostri strumenti online gratuiti per visualizzare, convertire e formattare i file JSONL direttamente nel browser. Tutta l'elaborazione avviene in locale, quindi i tuoi dati rimangono privati.
Impara a elaborare dati JSONL in streaming in tempo reale con Node.js, Python, Server-Sent Events e WebSocket. Crea pipeline di streaming per log, metriche e flussi di dati in tempo reale.
Strategie per elaborare gigabyte di dati JSONL: lettura in streaming, gestione della memoria, suddivisione dei file, compressione e strumenti online.
Valida i file JSONL riga per riga. Individua subito errori di sintassi e problemi di codifica o di formato.
Impara le best practice per la formattazione dei file JSONL, la coerenza dello schema, la gestione degli errori, l’ottimizzazione delle prestazioni e l’organizzazione dei file. Evita gli errori più comuni con esempi pratici.
Una guida completa per lavorare con i file JSONL in Python. Impara a leggere, scrivere ed effettuare il parsing dei dati JSONL con json, pandas e orjson, e a usare lo streaming per i file di grandi dimensioni.