Door Jerry Fan

JSONL in JavaScript: lezen, schrijven en parseren

Een complete gids voor het werken met JSONL-bestanden (JSON Lines) in JavaScript. Leer hoe je JSONL-data leest, schrijft, parseert en streamt in Node.js en in de browser, met ingebouwde API's en populaire libraries.

Waarom JavaScript voor JSONL?

JavaScript leent zich uitstekend voor het werken met JSONL-bestanden. JSON is ontstaan uit JavaScript, dus met de ingebouwde methoden JSON.parse() en JSON.stringify() heeft de taal alles in huis om JSON te parseren en te serialiseren. Of je nu een datapipeline in Node.js bouwt, logbestanden op een server verwerkt of gebruikers JSONL laat uploaden in de browser: JavaScript biedt de tools voor elke stap.

JSONL (JSON Lines) slaat per regel één JSON-object op. Dat maakt het formaat ideaal voor streaming, append-only logging en het regel voor regel verwerken van grote datasets. Streams in Node.js sluiten hier perfect op aan: je kunt miljoenen records lezen en transformeren zonder dat het geheugen volloopt. In de browser kun je met de FileReader API en de Streams API JSONL volledig op het apparaat van de gebruiker verwerken. In deze gids leer je JSONL lezen in Node.js en in de browser, JSONL-bestanden schrijven, streaming pipelines voor datatransformatie bouwen en de juiste npm-library voor je project kiezen.

JSONL lezen in Node.js

Met de readline-module van Node.js lees je bestanden efficiënt regel voor regel. In combinatie met fs.createReadStream is dit de aanbevolen manier om JSONL-bestanden op de server te verwerken: je streamt de data in plaats van het hele bestand in het geheugen te laden.

Geef een stream van fs.createReadStream als invoer door aan readline.createInterface om een JSONL-bestand regel voor regel te lezen. Deze aanpak gebruikt weinig geheugen, ongeacht de bestandsgrootte.

Streamend lezen met 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]);

Kleine JSONL-bestanden die ruim in het geheugen passen, kun je in één keer inlezen en op regeleinden splitsen. Dat is eenvoudiger, maar je mist de efficiëntie van streaming.

Een snelle one-liner voor kleine bestanden
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`);

JSONL lezen in de browser

In de browser kunnen gebruikers JSONL-bestanden uploaden via een veld voor bestandsselectie. Met de FileReader API of de moderne Streams API lees je het bestand zonder data naar een server te sturen.

Lees met FileReader een bestand dat de gebruiker heeft geselecteerd, splits de tekst in regels en parseer elke regel. Alle data blijft in de browser, zodat de privacy gewaarborgd blijft.

FileReader API in de 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`);
});

Gebruik voor grote bestanden in de browser de Streams API met TextDecoderStream om het bestand in chunks te verwerken. Zo hoef je het niet in één keer volledig in het geheugen te laden.

Streams API in de browser voor grote bestanden
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);
}

JSONL schrijven in Node.js

Een JSONL-bestand schrijven in Node.js is eenvoudig: serialiseer elk JavaScript-object naar een JSON-string en voeg een regeleindeteken toe. Gebruik voor de beste prestaties bij grote datasets een write stream, zodat je niet de hele string in het geheugen hoeft op te bouwen.

Gebruik fs.writeFileSync of fs.createWriteStream om records naar een JSONL-bestand te schrijven. Elk record bestaat uit één regel geldige JSON, gevolgd door een regeleindeteken.

Eenvoudig schrijven met 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`);

Gebruik bij het schrijven van miljoenen records een writable stream, zodat je niet de volledige uitvoerstring in het geheugen hoeft op te bouwen. De stream handelt backpressure automatisch af en pauzeert het schrijven wanneer de buffer van het besturingssysteem vol is.

Grote hoeveelheden data schrijven met een stream
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);

Transform-streams voor JSONL-pipelines

Met Transform-streams in Node.js bouw je datapipelines uit losse onderdelen die je aan elkaar kunt koppelen. Zo lees je JSONL, verwerk je elk record en schrijf je de resultaten weg. Dit patroon is ideaal voor ETL-taken, het verwerken van logs en datamigraties.

Transform-streams voor JSONL-pipelines
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');

Deze pipeline leest een JSONL-bestand regel voor regel, transformeert elk record door de velden processed en processedAt toe te voegen en schrijft de resultaten naar een nieuw bestand. De Transform-stream handelt backpressure automatisch af, zodat het geheugengebruik ook bij zeer grote bestanden constant blijft. Voor complexe ETL-workflows kun je meerdere transforms aan elkaar koppelen.

JavaScript-libraries voor JSONL

De ingebouwde JSON.parse volstaat in de meeste gevallen. Daarnaast bieden verschillende npm-packages handige functies voor specifieke JSONL-workflows, zoals streaming, validatie en batchverwerking.

JSON.parse (ingebouwd)

Ingebouwd

De ingebouwde methoden JSON.parse() en JSON.stringify() zijn sterk geoptimaliseerd in V8 en volstaan voor de meeste JSONL-toepassingen. Combineer ze met readline voor streaming. Je hebt geen dependencies nodig en de prestaties zijn uitstekend voor bestanden tot enkele honderden MB.

ndjson

Populair

ndjson is een populair npm-package met streaming parsers en serializers voor JSONL (Newline Delimited JSON) die werken met streams in Node.js. Het vangt parseerfouten netjes op en sluit goed aan op bestaande pipelines met streams. Handig om snel prototypes te bouwen.

jsonl-parse-stringify

Eenvoudig

jsonl-parse-stringify is een lichte library zonder dependencies met eenvoudige methoden parse() en stringify() voor JSONL-data. De library houdt rekening met randgevallen, zoals regeleinden aan het einde van het bestand en lege regels. Ideaal als je een eenvoudige synchrone API wilt zonder streams te hoeven opzetten.

Online werken met JSONL-bestanden

Bekijk, valideer en converteer JSONL-bestanden tot 1GB direct in je browser. Uploaden is niet nodig: alles blijft 100% privé.

Veelgestelde vragen

Bronnen