JavaScript で JSONL を扱う:読み込み・書き込み・パース
JavaScript で JSONL(JSON Lines)ファイルを扱うための総合ガイドです。組み込み API と広く使われているライブラリを使って、Node.js とブラウザの両方で JSONL データを読み込み、書き込み、パースし、ストリーミングで処理する方法を解説します。
JSONL の処理に JavaScript が適している理由
JavaScript は JSONL ファイルの処理と相性のよい言語です。JSON 自体が JavaScript から生まれた形式なので、組み込みの JSON.parse() と JSON.stringify() でパースとシリアライズを標準で行えます。Node.js でのデータパイプラインの構築、サーバーでのログファイル処理、ブラウザでユーザーが JSONL をアップロードする機能の実装など、どの場面でも一連の処理に必要なツールがそろっています。
JSONL(JSON Lines)は 1 行に 1 つの JSON オブジェクトを格納する形式で、ストリーミング処理、追記専用のログ、大規模なデータセットの行単位の処理に適しています。Node.js のストリームはこの形式と相性がよく、メモリ不足を起こさずに数百万件のレコードを読み込み、変換できます。クライアント側では、ブラウザの FileReader API と Streams API を使うことで、JSONL の処理をすべてユーザーの端末内で完結できます。このガイドでは、Node.js とブラウザで JSONL を読み込む方法、JSONL ファイルへの書き込み、ストリーミングで変換するパイプラインの構築、プロジェクトに合った npm ライブラリの選び方を解説します。
Node.js で JSONL を読み込む
Node.js の readline モジュールを使うと、ファイルを 行単位で効率よく読み込めます。fs.createReadStream と組み合わせれば、ファイル全体をメモリに読み込まずにストリーミングで処理できるため、サーバーで JSONL ファイルを扱う際におすすめの方法です。
fs.createReadStream を readline.createInterface に渡して、JSONL ファイルを 1 行ずつ読み込みます。ファイルサイズにかかわらず、最小限のメモリで読み込めます。
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]);メモリに十分収まる小さな JSONL ファイルなら、ファイル全体を一度に読み込み、改行で分割する方法も使えます。ストリーミング処理の効率よりも、実装のシンプルさを優先する方法です。
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 を読み込む
ブラウザでは、ファイル入力欄からユーザーが JSONL ファイルをアップロードできます。FileReader API や、より新しい Streams API を使えば、サーバーにデータを送信せずにファイルを読み込めます。
FileReader でユーザーが選択したファイルを読み込み、テキストを行ごとに分割してパースします。データをすべてクライアント側で扱うため、プライバシーを保てます。
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`);
});ブラウザで大容量ファイルを扱う場合は、Streams API と TextDecoderStream を組み合わせて、ファイルをチャンク単位で処理します。ファイル全体を一度にメモリに読み込まずに済みます。
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);
}Node.js で JSONL を書き込む
Node.js での JSONL ファイルへの書き込みは簡単です。各 JavaScript オブジェクトを JSON 文字列にシリアライズし、末尾に改行文字を付けます。大規模なデータセットで性能を引き出すには、文字列全体をメモリ上で組み立てる代わりに、書き込みストリームを使います。
fs.writeFileSync または fs.createWriteStream を使って、レコードを JSONL ファイルに書き込みます。各レコードを 1 行の正しい JSON として出力し、末尾に改行文字を付けます。
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`);数百万件のレコードを書き込む場合は、出力文字列全体をメモリ上で組み立てずに済むよう、書き込みストリームを使います。ストリームがバックプレッシャーを自動的に処理し、OS のバッファがいっぱいになると書き込みを一時停止します。
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 ストリームで JSONL パイプラインを構築する
Node.js の Transform ストリームを使うと、JSONL の読み込み、レコードごとの処理、結果の書き込みを組み合わせてデータパイプラインを構築できます。このパターンは、ETL ジョブやログ処理、データ移行に適しています。
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');このパイプラインでは、JSONL ファイルを 行単位で読み込み、各レコードに変換処理を加えて(processed と processedAt フィールドを追加)、結果を新しいファイルに書き込みます。Transform ストリームがバックプレッシャーを自動的に処理するため、非常に大きなファイルでもメモリ使用量は一定に保たれます。複数の変換処理をつなげれば、複雑な ETL ワークフローにも対応できます。
JSONL を扱う JavaScript ライブラリ
多くの場合は組み込みの JSON.parse で十分ですが、ストリーミングやバリデーション、バッチ処理など、JSONL 特有の処理に便利な機能を備えた npm パッケージもあります。
JSON.parse(組み込み)
組み込み組み込みの JSON.parse() と JSON.stringify() は V8 で高度に最適化されており、JSONL を扱う多くの用途ではこれらで十分です。readline と組み合わせれば、ストリーミング処理にも使えます。外部ライブラリへの依存は不要で、数百 MB までのファイルで優れた性能を発揮します。
ndjson
人気ndjson は、Node.js のストリームに対応した JSONL(改行区切りの JSON)のストリーミングパーサーとシリアライザーを提供する、人気の npm パッケージです。パースエラーを適切に処理でき、既存のストリームパイプラインにも容易に組み込めます。手早くプロトタイプを作りたいときに適しています。
jsonl-parse-stringify
シンプルjsonl-parse-stringify は、JSONL データを扱うシンプルな parse() と stringify() メソッドを備えた、外部依存のない軽量ライブラリです。末尾の改行や空行といったエッジケースにも対応しています。ストリームを設定せずに、使いやすい同期 API で処理したい場合に適しています。
無料の JSONL ツールを試す
コードを書かずに処理したい場合は、無料のオンラインツールをご利用ください。ブラウザ上でそのまま JSONL ファイルを表示・変換・整形できます。処理はすべてローカルで行われるため、データのプライバシーを保てます。
Node.jsとPythonでJSONLデータをストリーミングする方法を学びます。SSE、WebSocket、リアルタイムログ処理をカバー。
ギガバイト規模の JSONL データを処理する方法を紹介します。ストリーミングでの読み込み、メモリ管理、ファイル分割、圧縮、オンラインツールを取り上げます。
JSONL ファイルを 1 行ずつ検証します。構文エラーや文字エンコーディング、形式の問題をすぐに検出できます。
整形、スキーマの一貫性、エラーハンドリング、パフォーマンスの最適化、ファイル整理に関する JSONL のベストプラクティスを解説します。実践的な例を通じて、よくある落とし穴を避ける方法を学べます。
Python で JSONL ファイルを扱うための完全ガイドです。json、pandas、orjson を使った読み書きとパース、大容量ファイルのストリーミング処理を解説します。