Autor: Jerry Fan

JSONL w JavaScript: odczyt, zapis i parsowanie

Kompletny przewodnik po pracy z plikami JSONL (JSON Lines) w JavaScript. Dowiedz się, jak odczytywać, zapisywać, parsować i strumieniowo przetwarzać dane JSONL w Node.js i w przeglądarce, korzystając z wbudowanych API oraz popularnych bibliotek.

Dlaczego warto przetwarzać JSONL w JavaScript?

JavaScript naturalnie nadaje się do pracy z plikami JSONL. Sam format JSON wywodzi się z JavaScript, a wbudowane metody JSON.parse() i JSON.stringify() zapewniają natywną obsługę parsowania i serializacji. Niezależnie od tego, czy budujesz potok przetwarzania danych w Node.js, przetwarzasz logi na serwerze, czy pozwalasz użytkownikom wczytywać pliki JSONL w przeglądarce, JavaScript daje Ci narzędzia potrzebne na każdym etapie.

W formacie JSONL (JSON Lines) każdy obiekt JSON zajmuje osobną linię. Dzięki temu format świetnie sprawdza się przy przetwarzaniu strumieniowym, zapisywaniu logów wyłącznie przez dopisywanie nowych wpisów oraz przetwarzaniu dużych zbiorów danych linia po linii. Strumienie w Node.js doskonale pasują do tego formatu: pozwalają odczytywać i przekształcać miliony rekordów bez wyczerpywania dostępnej pamięci. W przeglądarce API FileReader i Streams umożliwiają przetwarzanie JSONL w całości na urządzeniu użytkownika. Z tego przewodnika dowiesz się, jak odczytywać JSONL w Node.js i w przeglądarce, zapisywać pliki JSONL, tworzyć potoki strumieniowego przetwarzania danych oraz dobrać bibliotekę npm do swojego projektu.

Odczyt JSONL w Node.js

Node.js udostępnia moduł readline, który pozwala wydajnie odczytywać pliki linia po linii. W połączeniu z fs.createReadStream to zalecany sposób przetwarzania plików JSONL na serwerze: dane są odczytywane strumieniowo, bez wczytywania całego pliku do pamięci.

Przekaż strumień z fs.createReadStream do readline.createInterface, aby odczytywać plik JSONL linia po linii. Takie rozwiązanie zużywa niewiele pamięci niezależnie od rozmiaru pliku.

Odczyt strumieniowy z 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]);

Jeśli niewielki plik JSONL bez problemu mieści się w pamięci, możesz odczytać go w całości i podzielić tekst według znaków nowej linii. To prostsze rozwiązanie, choć nie daje korzyści wydajnościowych przetwarzania strumieniowego.

Krótki zapis w jednej linii (małe pliki)
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`);

Odczyt JSONL w przeglądarce

W przeglądarce użytkownik może wczytać plik JSONL przez pole input typu file. Do odczytu możesz użyć API FileReader lub nowoczesnego API Streams. Wszystko odbywa się bez wysyłania danych na serwer.

Odczytaj plik wybrany przez użytkownika za pomocą FileReader, a następnie podziel tekst na linie i sparsuj każdą z nich. Wszystkie dane pozostają po stronie klienta, co pozwala zachować ich prywatność.

API FileReader w przeglądarce
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`);
});

Do przetwarzania dużych plików w przeglądarce użyj API Streams z TextDecoderStream. Pozwala to przetwarzać plik fragmentami, bez wczytywania go w całości do pamięci.

API Streams w przeglądarce (duże pliki)
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);
}

Zapis JSONL w Node.js

Zapis plików JSONL w Node.js jest prosty: wystarczy zserializować każdy obiekt JavaScript do tekstu w formacie JSON i dodać znak nowej linii. Przy dużych zbiorach danych najlepszą wydajność uzyskasz, korzystając ze strumienia zapisu zamiast tworzyć cały wynikowy tekst w pamięci.

Użyj fs.writeFileSync lub fs.createWriteStream, aby zapisać rekordy w pliku JSONL. Każdy rekord zajmuje jedną linię zawierającą poprawny JSON i zakończoną znakiem nowej linii.

Prosty zapis za pomocą 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`);

Przy zapisie milionów rekordów użyj strumienia zapisu, aby nie tworzyć całego wynikowego tekstu w pamięci. Strumień automatycznie obsługuje backpressure i wstrzymuje zapis, gdy bufor systemu operacyjnego jest pełny.

Zapis strumieniowy dużych zbiorów danych
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);

Strumienie Transform w potokach przetwarzania JSONL

Strumienie Transform w Node.js pozwalają budować potoki z połączonych etapów, które odczytują JSONL, przetwarzają poszczególne rekordy i zapisują wyniki. Ten wzorzec świetnie sprawdza się w zadaniach ETL, przetwarzaniu logów i migracji danych.

Strumienie Transform w potokach przetwarzania 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');

Ten potok odczytuje plik JSONL linia po linii, przekształca każdy rekord (dodając pola processed i processedAt) i zapisuje wyniki w nowym pliku. Strumień Transform automatycznie obsługuje backpressure, dzięki czemu zużycie pamięci pozostaje stałe nawet przy bardzo dużych plikach. Możesz łączyć kolejne transformacje, aby realizować złożone procesy ETL.

Biblioteki do obsługi JSONL w JavaScript

Wbudowana metoda JSON.parse dobrze sprawdza się w większości zastosowań. Dostępne są też pakiety npm, które ułatwiają typowe zadania związane z JSONL, takie jak przetwarzanie strumieniowe, walidacja i przetwarzanie wsadowe.

JSON.parse (wbudowany)

Wbudowany

Wbudowane metody JSON.parse() i JSON.stringify() są mocno zoptymalizowane w V8 i wystarczają do większości zadań związanych z JSONL. Połącz je z readline, aby przetwarzać dane strumieniowo. Nie potrzebujesz żadnych zależności, a wydajność jest bardzo dobra przy plikach o rozmiarze do kilkuset MB.

ndjson

Popularny

ndjson to popularny pakiet npm ze strumieniowymi parserami i serializerami JSONL (Newline Delimited JSON), zgodnymi ze strumieniami Node.js. Sprawnie obsługuje błędy parsowania i dobrze współpracuje z istniejącymi potokami przetwarzania strumieniowego. Świetnie nadaje się do szybkiego prototypowania.

jsonl-parse-stringify

Prosta

jsonl-parse-stringify to lekka biblioteka bez zależności, która udostępnia proste metody parse() i stringify() do obsługi danych JSONL. Radzi sobie z przypadkami brzegowymi, takimi jak znaki nowej linii na końcu pliku i puste linie. To dobry wybór, jeśli potrzebujesz prostego, synchronicznego API bez konfigurowania strumieni.

Pracuj z plikami JSONL online

Przeglądaj, waliduj i konwertuj pliki JSONL o rozmiarze do 1GB bezpośrednio w przeglądarce. Bez wysyłania plików na serwer, ze 100% prywatności.

Najczęściej zadawane pytania

Źródła