From b070d026db6ef43485576b06b5e128aa21183cdc Mon Sep 17 00:00:00 2001 From: Julian Soreavis Date: Thu, 16 Jul 2026 15:47:11 +0200 Subject: [PATCH] doc: clarify how fs.Dirent file types are determined The file type of a directory entry returned by fs.readdir() or fs.opendir() is the type reported by the operating system's directory listing. Node.js falls back to lstat() only when the reported type is unknown, and some file systems may report a type that differs from what lstat() would return. Document this in the fs.Dirent class introduction, with fs.lstat() as the accurate alternative. Fixes: https://github.com/nodejs/node/issues/30646 Signed-off-by: Julian Soreavis --- doc/api/fs.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/doc/api/fs.md b/doc/api/fs.md index 9cb84007b3b815..3c065e5c0fddce 100644 --- a/doc/api/fs.md +++ b/doc/api/fs.md @@ -7336,6 +7336,13 @@ Additionally, when [`fs.readdir()`][] or [`fs.readdirSync()`][] is called with the `withFileTypes` option set to `true`, the resulting array is filled with {fs.Dirent} objects, rather than strings or {Buffer}s. +When a directory is read, such as with [`fs.readdir()`][] or +[`fs.opendir()`][], the file type of each entry is the type reported by the +operating system and may depend on the file system; for example, some file +systems may report a type that differs from what [`fs.lstat()`][] returns. +Node.js calls [`fs.lstat()`][] on such an entry only when the reported type +is unknown. Use [`fs.lstat()`][] when an accurate file type is required. + #### `dirent.isBlockDevice()`