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

fstatSyncメソッドは、Node.jsのファイルシステム操作において、特定のファイル記述子に紐づけられたファイルやディレクトリのステータス情報を同期的に取得するメソッドです。

ファイル記述子とは、Node.jsでファイルシステム上のファイルを開いた際に、OSによってそのファイルを識別するために割り当てられる一意の数値のことです。このfstatSyncメソッドは、引数として受け取ったファイル記述子に対応する対象の、種類（ファイルかディレクトリか）、サイズ、作成日時、最終更新日時、最終アクセス日時、所有者ID、グループID、パーミッションなどの詳細な属性情報を取得します。

メソッド名の「Sync」が示す通り、この操作は同期的に実行されます。これは、ファイル情報の取得処理が完了するまでプログラムの実行がブロックされ、後続のJavaScriptコードの実行が一時停止することを意味します。そのため、特に大規模なファイルや多数のファイルに対して使用する際には、アプリケーション全体のパフォーマンスに影響を与える可能性があるため、利用する場面を考慮する必要があります。

fstatSyncメソッドが正常に実行されると、fs.Statsオブジェクトを返します。このfs.Statsオブジェクトには、取得されたファイル属性がプロパティとして格納されており、プログラマはこれらの情報を用いてファイルの特性を判断したり、それに応じた処理を実装したりすることができます。例えば、対象がディレクトリであるか、ファイルのサイズがどれくらいかといった情報を確認する際に活用されます。このメソッドは、主に低レベルなファイル操作や、特定のファイル記述子に直接アクセスして情報を得る必要がある場合に用いられます。

Copy
1const fs = require('node:fs');
2
3try {
4  const filePath = 'fstat_example.txt';
5  fs.writeFileSync(filePath, 'Node.js fstatSync example content.');
6
7  const fd = fs.openSync(filePath, 'r');
8  const stats = fs.fstatSync(fd);
9
10  console.log(stats.size);
11  console.log(stats.isFile());
12  console.log(stats.isDirectory());
13
14  fs.closeSync(fd);
15  fs.unlinkSync(filePath);
16} catch (error) {
17  console.error(error.message);
18}

fd, options = { bigint: false }

• fd: number: ファイルディスクリプタ（ファイルへの参照を表す数値）
• options: object = { bigint: false }: オプションを指定するオブジェクト。bigint を true に設定すると、ファイルサイズなどを BigInt 型で取得できます。

fs.Stats

fstatSyncメソッドは、指定されたファイルディスクリプターに関連するファイルの状態情報を含むfs.Statsオブジェクトを同期的に返します。このオブジェクトには、ファイルのサイズ、最終更新日時などの情報が含まれています。