- Strona główna
- Przewodnik
- JSONL w JavaScript: odczyt, zapis i parsowanie
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.
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.
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ść.
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.
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.
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.
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.
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)
WbudowanyWbudowane 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
Popularnyndjson 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
Prostajsonl-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.
Wypróbuj nasze bezpłatne narzędzia do JSONL
Nie chcesz pisać kodu? Skorzystaj z naszych bezpłatnych narzędzi online, aby przeglądać, konwertować i formatować pliki JSONL bezpośrednio w przeglądarce. Dane są przetwarzane lokalnie, więc zachowujesz ich prywatność.
Dowiedz się, jak strumieniować dane JSONL w Node.js i Pythonie. Obejmuje SSE, WebSockets i przetwarzanie logów w czasie rzeczywistym.
Sposoby przetwarzania gigabajtów danych JSONL: odczyt strumieniowy, zarządzanie pamięcią, dzielenie plików, kompresja i narzędzia online.
Waliduj pliki JSONL linia po linii. Od razu wykrywaj błędy składni, problemy z kodowaniem i niezgodności z formatem.
Poznaj dobre praktyki pracy z JSONL: formatowanie, spójność schematu, obsługę błędów, optymalizację wydajności i organizację plików. Praktyczne przykłady pomogą Ci uniknąć typowych pułapek.
Pełny przewodnik po pracy z plikami JSONL w Pythonie. Naucz się odczytywać, zapisywać i parsować JSONL przy użyciu json, pandas i orjson oraz przetwarzać duże pliki strumieniowo.