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

lstatSyncメソッドは、Node.jsのファイルシステム操作を提供するfsモジュールによって提供される同期的なメソッドです。このメソッドは、指定されたファイルやディレクトリの情報を取得するために使用されます。

特にlstatSyncの重要な特徴は、パスがシンボリックリンク（別のファイルやディレクトリへの参照を示す特殊なファイル）である場合でも、そのリンク自体に関する情報を取得する点です。つまり、リンクが指し示す先のファイルやディレクトリではなく、シンボリックリンクファイル自身のサイズ、作成日時、所有者などの統計情報を返します。これに対し、同じくfsモジュールが提供するfs.statSyncメソッドは、シンボリックリンクの参照先を辿り、最終的なターゲットの情報を取得します。

このメソッドは「Sync」という名前が示す通り、同期処理を行います。同期処理とは、ファイルシステムへの読み書きといったI/O操作が完了し、結果が返されるまで、プログラムの実行を一時停止（ブロック））することを意味します。そのため、大規模なファイル操作や、サーバーのように常に応答性が求められるアプリケーションでは、パフォーマンスに影響を与え、全体の処理が停止してしまう可能性があります。

lstatSyncメソッドは、引数として情報取得の対象となるファイルやディレクトリのパスを受け取ります。成功すると、ファイルの種類、サイズ、最終更新日時、パーミッション（読み書き権限）などの詳細情報を含むfs.Statsオブジェクトという特殊なデータ構造を返します。もしファイルが見つからない、またはアクセス権がないなどのエラーが発生した場合は、通常のJavaScriptのエラー（例外）をスローするため、try...catch構文を用いて適切にエラーを処理する必要があります。

通常、Node.jsアプリケーションでは、ノンブロッキングな非同期処理版のfs.lstatメソッドの使用が推奨されますが、簡単なスクリプトや起動時の初期化処理など、一時的なブロックが許容される場面では、lstatSyncは簡潔に記述できるため便利です。

Copy
1const fs = require('fs');
2
3const stats = fs.lstatSync('path/to/your/file_or_symlink.txt', { throwIfNoEntry: true });

path, options={bigint:false, throwIfNoEntry:true}

• path: string: 統計情報を取得したいファイルまたはディレクトリのパス
• options: object: オプション設定オブジェクト
  • bigint: boolean = false: trueに設定すると、ファイルサイズなどの情報をBigInt型で返します。デフォルトはfalseで、Number型で返します。
  • throwIfNoEntry: boolean = true: falseに設定すると、指定されたパスが存在しない場合にエラーを投げずにundefinedを返します。デフォルトはtrueで、存在しない場合はエラーを投げます。

fs.Stats

指定されたパスにあるファイルやディレクトリのステータス情報を表すfs.Statsオブジェクトを返します。このオブジェクトには、ファイルサイズ、変更日時などの情報が含まれています。