【Node.js24.x】Object::readSync()メソッドの使い方

readSyncメソッドは、Node.js環境において、Objectクラスに属し、指定されたソースからデータを同期的に読み込む処理を実行するメソッドです。このメソッドの主な役割は、ファイルディスクリプタやストリームといったデータソースから、メモリ上のバッファへ、指定されたオフセットから一定の長さのデータを読み込むことです。

データ読み込みのプロセス中、readSyncメソッドは、その処理が完了するまでプログラムの実行を一時的に停止させます。これは「同期処理」と呼ばれ、読み込みが完了するまで次のコードの実行を待つ特性を持ちます。メソッドが成功裏に完了した場合、実際に読み込まれたバイト数が戻り値として提供されます。もし、データの読み込み中に何らかのエラーが発生した場合は、例外を発生させることで、呼び出し元にその異常を通知します。

この同期的な特性のため、readSyncは主に、アプリケーションの起動時に必要な設定ファイルの読み込みや、小規模なデータの一時的な取得など、比較的処理時間が短く、かつプログラムの実行をブロックしても問題がない場面での利用が適しています。大量のデータ読み込みや、応答性が重視される処理でこのメソッドを使用すると、アプリケーション全体のパフォーマンスやユーザーエクスペリエンスに悪影響を与える可能性があるため、利用には注意が必要です。

Copy
1const fs = require('node:fs');
2
3let fd;
4try {
5  // 'example.txt' というファイルを読み込みモードで同期的に開きます。
6  // 実際のシステムでは、このファイルが存在し、読み取り権限がある必要があります。
7  fd = fs.openSync('example.txt', 'r');
8
9  // データを読み込むためのBufferオブジェクトを準備します。
10  // ここでは10バイト分の領域を確保しています。
11  const buffer = Buffer.alloc(10);
12
13  // fs.readSync メソッドを使用して、ファイルからデータを読み込みます。
14  // 構文: fs.readSync(fd, buffer, offset, length, position)
15  //   fd: ファイルディスクリプタ (fs.openSync() の戻り値)
16  //   buffer: 読み込んだデータを格納するBufferオブジェクト
17  //   offset: buffer内でデータを書き込み始める位置 (バイト)
18  //   length: ファイルから読み込むバイト数
19  //   position: ファイル内で読み込みを開始する位置 (バイト)。null の場合、現在のファイル位置から読み込みます。
20  const bytesRead = fs.readSync(fd, buffer, 0, buffer.length, 0);
21
22  // bytesRead には実際に読み込まれたバイト数が格納されます。
23  // 読み込まれたデータは buffer オブジェクト内にあります。
24
25} finally {
26  // ファイルディスクリプタが開かれている場合は、必ず閉じます。
27  if (fd !== undefined) {
28    fs.closeSync(fd);
29  }
30}

fd, buffer, offset, length, position

• fd: number: ファイルディスクリプタ。読み込み対象のファイルを表す番号。
• buffer: Buffer: 読み込んだデータを格納するバッファオブジェクト。
• offset: number: buffer 内の書き込み開始位置（バイト単位）。
• length: number: 読み込むバイト数。
• position: number | null: ファイル内の読み込み開始位置（バイト単位）。null を指定すると現在のファイルポインタ位置から読み込みます。

number

このメソッドは、同期的にファイルの内容を読み込んだバイト数を返します。