著者: Jerry Fan

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 行ずつ読み込みます。ファイルサイズにかかわらず、最小限のメモリで読み込めます。

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]);

メモリに十分収まる小さな 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 でユーザーが選択したファイルを読み込み、テキストを行ごとに分割してパースします。データをすべてクライアント側で扱うため、プライバシーを保てます。

ブラウザの FileReader API を使う
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 を組み合わせて、ファイルをチャンク単位で処理します。ファイル全体を一度にメモリに読み込まずに済みます。

ブラウザの Streams API を使う(大容量ファイル向け)
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 として出力し、末尾に改行文字を付けます。

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`);

数百万件のレコードを書き込む場合は、出力文字列全体をメモリ上で組み立てずに済むよう、書き込みストリームを使います。ストリームがバックプレッシャーを自動的に処理し、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 ジョブやログ処理、データ移行に適しています。

Transform ストリームで 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');

このパイプラインでは、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 ファイルを表示・変換・整形できます。処理はすべてローカルで行われるため、データのプライバシーを保てます。

JSONL ファイルをオンラインで扱う

最大 1GB の JSONL ファイルを、ブラウザ上でそのまま表示・検証・変換できます。アップロードは不要で、データのプライバシーは 100% 保たれます。

よくある質問

参考資料