Par Jerry Fan

JSONL en JavaScript : lecture, écriture et parsing

Un guide complet pour manipuler des fichiers JSONL (JSON Lines) en JavaScript. Découvrez comment lire, écrire, parser et traiter des données JSONL en streaming, dans Node.js comme dans le navigateur, avec les API natives et les bibliothèques courantes.

Pourquoi utiliser JavaScript pour le JSONL ?

JavaScript se prête naturellement à la manipulation de fichiers JSONL. JSON étant lui-même issu de JavaScript, le langage prend directement en charge le parsing et la sérialisation grâce aux méthodes natives JSON.parse() et JSON.stringify(). Que vous développiez un pipeline de données avec Node.js, traitiez des fichiers de logs sur un serveur ou proposiez aux utilisateurs de charger du JSONL dans leur navigateur, JavaScript fournit les outils nécessaires à chaque étape.

Le format JSONL (JSON Lines) stocke un objet JSON par ligne. Il est donc idéal pour le streaming, les logs alimentés uniquement par ajout et le traitement de grands jeux de données ligne par ligne. Les streams de Node.js conviennent parfaitement à ce format : ils permettent de lire et de transformer des millions d'enregistrements sans épuiser la mémoire. Côté client, les API FileReader et Streams du navigateur permettent de traiter le JSONL entièrement sur l'appareil de l'utilisateur. Ce guide explique comment lire du JSONL dans Node.js et dans le navigateur, écrire des fichiers JSONL, créer des pipelines de transformation en streaming et choisir la bibliothèque npm adaptée à votre projet.

Lire du JSONL dans Node.js

Node.js fournit le module readline pour lire efficacement les fichiers ligne par ligne. Associé à fs.createReadStream, il constitue la méthode recommandée pour traiter des fichiers JSONL côté serveur : les données sont lues en streaming, sans charger tout le fichier en mémoire.

Passez le flux créé par fs.createReadStream à readline.createInterface pour lire un fichier JSONL ligne par ligne. Cette approche consomme très peu de mémoire, quelle que soit la taille du fichier.

Lecture en streaming avec 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]);

Pour les petits fichiers JSONL qui tiennent sans difficulté en mémoire, vous pouvez lire tout le fichier en une fois, puis découper son contenu aux retours à la ligne. Vous gagnez en simplicité au prix de l'efficacité du streaming.

Une expression pour les petits fichiers
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`);

Lire du JSONL dans le navigateur

Dans le navigateur, les utilisateurs peuvent charger des fichiers JSONL à l'aide d'un champ de sélection de fichier. Vous pouvez ensuite les lire avec l'API FileReader ou l'API Streams, plus récente, sans envoyer de données à un serveur.

Utilisez FileReader pour lire un fichier sélectionné par l'utilisateur, puis découpez le texte en lignes et parsez chacune d'elles. Toutes les données restent côté client, ce qui préserve leur confidentialité.

API FileReader du navigateur
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`);
});

Pour traiter des fichiers volumineux dans le navigateur, utilisez l'API Streams avec TextDecoderStream afin de lire le fichier par blocs. Vous évitez ainsi de le charger entièrement en mémoire.

API Streams du navigateur pour les fichiers volumineux
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);
}

Écrire du JSONL dans Node.js

Écrire des fichiers JSONL dans Node.js est simple : sérialisez chaque objet JavaScript en une chaîne JSON, puis ajoutez un caractère de retour à la ligne. Pour obtenir les meilleures performances avec de grands jeux de données, utilisez un flux d'écriture plutôt que de constituer toute la chaîne en mémoire.

Utilisez fs.writeFileSync ou fs.createWriteStream pour écrire des enregistrements dans un fichier JSONL. Chaque enregistrement occupe une ligne de JSON valide, suivie d'un retour à la ligne.

Écriture simple avec 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`);

Pour écrire des millions d'enregistrements, utilisez un flux d'écriture afin d'éviter de constituer toute la chaîne de sortie en mémoire. Le flux gère automatiquement la backpressure et suspend les écritures lorsque le tampon du système d'exploitation est plein.

Écriture en streaming pour les gros volumes de données
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);

Des streams Transform pour les pipelines JSONL

Les streams Transform de Node.js permettent de composer des pipelines de données qui lisent du JSONL, traitent chaque enregistrement et écrivent les résultats. Cette approche est idéale pour les traitements ETL, le traitement des logs et la migration de données.

Des streams Transform pour les 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');

Ce pipeline lit un fichier JSONL ligne par ligne, transforme chaque enregistrement en ajoutant les champs processed et processedAt, puis écrit les résultats dans un nouveau fichier. Le stream Transform gère automatiquement la backpressure : la consommation mémoire reste donc constante, même avec des fichiers très volumineux. Vous pouvez enchaîner plusieurs transformations pour réaliser des traitements ETL complexes.

Bibliothèques JavaScript pour le JSONL

La méthode native JSON.parse suffit dans la plupart des cas. Plusieurs packages npm proposent toutefois des utilitaires pratiques pour les traitements propres au JSONL, comme le streaming, la validation et le traitement par lots.

JSON.parse (natif)

Natif

Les méthodes natives JSON.parse() et JSON.stringify() sont très optimisées dans V8 et suffisent pour la plupart des usages du JSONL. Associez-les à readline pour le streaming. Aucune dépendance n'est nécessaire, et les performances sont excellentes pour des fichiers allant jusqu'à plusieurs centaines de Mo.

ndjson

Populaire

ndjson est un package npm populaire qui propose des parseurs et des sérialiseurs JSONL (Newline Delimited JSON) en streaming, compatibles avec les streams de Node.js. Il gère les erreurs de parsing de manière souple et s'intègre facilement aux pipelines de streams existants. Un bon choix pour prototyper rapidement.

jsonl-parse-stringify

Simple

jsonl-parse-stringify est une bibliothèque légère, sans dépendances, qui propose deux méthodes simples, parse() et stringify(), pour manipuler des données JSONL. Elle gère les cas particuliers, comme les retours à la ligne en fin de fichier et les lignes vides. Elle convient parfaitement si vous cherchez une API synchrone simple, sans avoir à configurer de streams.

Manipulez vos fichiers JSONL en ligne

Visualisez, validez et convertissez des fichiers JSONL jusqu'à 1 Go directement dans votre navigateur. Aucun envoi de fichier nécessaire, vos données restent 100% privées.

Questions fréquentes

Références