doc: clarify how fs.Dirent file types are determined by soreavis · Pull Request #64532 · nodejs/node

soreavis · 2026-07-16T13:47:36Z

The fs.Dirent docs don't say where entry file types come from — the confusion in #30646, where the type reported on a remotely mounted file system didn't match lstat() and @addaleax suggested documenting that "the type of the entry may be dependent on the file system and operating system". This adds one paragraph to the fs.Dirent class intro: the type of an entry from a directory read is the type reported by the operating system, it may depend on the file system, lstat() is only used as a fallback when the reported type is unknown, and fs.lstat() is the accurate alternative.

Verified against lib/internal/fs/utils.js (getDirent/getDirents fall back to lstat only on UV_DIRENT_UNKNOWN) and src/node_file.cc (the type comes from uv_fs_scandir_next, no stat call). The wording is scoped to directory reads (fs.readdir(), fs.opendir()) because fs.glob() with withFileTypes builds its dirents from lstat() directly.

I used an AI assistant while researching and drafting this change; I've verified the behavior and the wording against the source myself and take full responsibility for it.

Fixes: #30646

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: nodejs#30646 Signed-off-by: Julian Soreavis <julian.soreavis@gmail.com>

lpinca

RSLGTM

trivikr · 2026-08-18T07:00:52Z

cc @nodejs/fs

nodejs-github-bot · 2026-08-18T15:15:51Z

Landed in 29a083c

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: #30646 Signed-off-by: Julian Soreavis <julian.soreavis@gmail.com> PR-URL: #64532 Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Jason Zhang <xzha4350@gmail.com>

soreavis · 2026-07-16T13:47:36Z

The fs.Dirent docs don't say where entry file types come from — the confusion in #30646, where the type reported on a remotely mounted file system didn't match lstat() and @addaleax suggested documenting that "the type of the entry may be dependent on the file system and operating system". This adds one paragraph to the fs.Dirent class intro: the type of an entry from a directory read is the type reported by the operating system, it may depend on the file system, lstat() is only used as a fallback when the reported type is unknown, and fs.lstat() is the accurate alternative.

Verified against lib/internal/fs/utils.js (getDirent/getDirents fall back to lstat only on UV_DIRENT_UNKNOWN) and src/node_file.cc (the type comes from uv_fs_scandir_next, no stat call). The wording is scoped to directory reads (fs.readdir(), fs.opendir()) because fs.glob() with withFileTypes builds its dirents from lstat() directly.

I used an AI assistant while researching and drafting this change; I've verified the behavior and the wording against the source myself and take full responsibility for it.

Fixes: #30646

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: nodejs#30646 Signed-off-by: Julian Soreavis <julian.soreavis@gmail.com>

lpinca

RSLGTM

trivikr · 2026-08-18T07:00:52Z

cc @nodejs/fs

nodejs-github-bot · 2026-08-18T15:15:51Z

Landed in 29a083c

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: #30646 Signed-off-by: Julian Soreavis <julian.soreavis@gmail.com> PR-URL: #64532 Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Jason Zhang <xzha4350@gmail.com>

soreavis · 2026-07-16T13:47:36Z

The fs.Dirent docs don't say where entry file types come from — the confusion in #30646, where the type reported on a remotely mounted file system didn't match lstat() and @addaleax suggested documenting that "the type of the entry may be dependent on the file system and operating system". This adds one paragraph to the fs.Dirent class intro: the type of an entry from a directory read is the type reported by the operating system, it may depend on the file system, lstat() is only used as a fallback when the reported type is unknown, and fs.lstat() is the accurate alternative.

Verified against lib/internal/fs/utils.js (getDirent/getDirents fall back to lstat only on UV_DIRENT_UNKNOWN) and src/node_file.cc (the type comes from uv_fs_scandir_next, no stat call). The wording is scoped to directory reads (fs.readdir(), fs.opendir()) because fs.glob() with withFileTypes builds its dirents from lstat() directly.

I used an AI assistant while researching and drafting this change; I've verified the behavior and the wording against the source myself and take full responsibility for it.

Fixes: #30646

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: nodejs#30646 Signed-off-by: Julian Soreavis <julian.soreavis@gmail.com>

lpinca

RSLGTM

trivikr · 2026-08-18T07:00:52Z

cc @nodejs/fs

nodejs-github-bot · 2026-08-18T15:15:51Z

Landed in 29a083c

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: #30646 Signed-off-by: Julian Soreavis <julian.soreavis@gmail.com> PR-URL: #64532 Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Jason Zhang <xzha4350@gmail.com>

soreavis · 2026-07-16T13:47:36Z

The fs.Dirent docs don't say where entry file types come from — the confusion in #30646, where the type reported on a remotely mounted file system didn't match lstat() and @addaleax suggested documenting that "the type of the entry may be dependent on the file system and operating system". This adds one paragraph to the fs.Dirent class intro: the type of an entry from a directory read is the type reported by the operating system, it may depend on the file system, lstat() is only used as a fallback when the reported type is unknown, and fs.lstat() is the accurate alternative.

Verified against lib/internal/fs/utils.js (getDirent/getDirents fall back to lstat only on UV_DIRENT_UNKNOWN) and src/node_file.cc (the type comes from uv_fs_scandir_next, no stat call). The wording is scoped to directory reads (fs.readdir(), fs.opendir()) because fs.glob() with withFileTypes builds its dirents from lstat() directly.

I used an AI assistant while researching and drafting this change; I've verified the behavior and the wording against the source myself and take full responsibility for it.

Fixes: #30646

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: nodejs#30646 Signed-off-by: Julian Soreavis <julian.soreavis@gmail.com>

lpinca

RSLGTM

trivikr · 2026-08-18T07:00:52Z

cc @nodejs/fs

nodejs-github-bot · 2026-08-18T15:15:51Z

Landed in 29a083c

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: #30646 Signed-off-by: Julian Soreavis <julian.soreavis@gmail.com> PR-URL: #64532 Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Jason Zhang <xzha4350@gmail.com>

soreavis · 2026-07-16T13:47:36Z

The fs.Dirent docs don't say where entry file types come from — the confusion in #30646, where the type reported on a remotely mounted file system didn't match lstat() and @addaleax suggested documenting that "the type of the entry may be dependent on the file system and operating system". This adds one paragraph to the fs.Dirent class intro: the type of an entry from a directory read is the type reported by the operating system, it may depend on the file system, lstat() is only used as a fallback when the reported type is unknown, and fs.lstat() is the accurate alternative.

Verified against lib/internal/fs/utils.js (getDirent/getDirents fall back to lstat only on UV_DIRENT_UNKNOWN) and src/node_file.cc (the type comes from uv_fs_scandir_next, no stat call). The wording is scoped to directory reads (fs.readdir(), fs.opendir()) because fs.glob() with withFileTypes builds its dirents from lstat() directly.

I used an AI assistant while researching and drafting this change; I've verified the behavior and the wording against the source myself and take full responsibility for it.

Fixes: #30646

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: nodejs#30646 Signed-off-by: Julian Soreavis <julian.soreavis@gmail.com>

lpinca

RSLGTM

trivikr · 2026-08-18T07:00:52Z

cc @nodejs/fs

nodejs-github-bot · 2026-08-18T15:15:51Z

Landed in 29a083c

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: #30646 Signed-off-by: Julian Soreavis <julian.soreavis@gmail.com> PR-URL: #64532 Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Jason Zhang <xzha4350@gmail.com>

soreavis · 2026-07-16T13:47:36Z

The fs.Dirent docs don't say where entry file types come from — the confusion in #30646, where the type reported on a remotely mounted file system didn't match lstat() and @addaleax suggested documenting that "the type of the entry may be dependent on the file system and operating system". This adds one paragraph to the fs.Dirent class intro: the type of an entry from a directory read is the type reported by the operating system, it may depend on the file system, lstat() is only used as a fallback when the reported type is unknown, and fs.lstat() is the accurate alternative.

Verified against lib/internal/fs/utils.js (getDirent/getDirents fall back to lstat only on UV_DIRENT_UNKNOWN) and src/node_file.cc (the type comes from uv_fs_scandir_next, no stat call). The wording is scoped to directory reads (fs.readdir(), fs.opendir()) because fs.glob() with withFileTypes builds its dirents from lstat() directly.

I used an AI assistant while researching and drafting this change; I've verified the behavior and the wording against the source myself and take full responsibility for it.

Fixes: #30646

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: nodejs#30646 Signed-off-by: Julian Soreavis <julian.soreavis@gmail.com>

lpinca

RSLGTM

trivikr · 2026-08-18T07:00:52Z

cc @nodejs/fs

nodejs-github-bot · 2026-08-18T15:15:51Z

Landed in 29a083c

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: #30646 Signed-off-by: Julian Soreavis <julian.soreavis@gmail.com> PR-URL: #64532 Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Jason Zhang <xzha4350@gmail.com>

soreavis · 2026-07-16T13:47:36Z

The fs.Dirent docs don't say where entry file types come from — the confusion in #30646, where the type reported on a remotely mounted file system didn't match lstat() and @addaleax suggested documenting that "the type of the entry may be dependent on the file system and operating system". This adds one paragraph to the fs.Dirent class intro: the type of an entry from a directory read is the type reported by the operating system, it may depend on the file system, lstat() is only used as a fallback when the reported type is unknown, and fs.lstat() is the accurate alternative.

Verified against lib/internal/fs/utils.js (getDirent/getDirents fall back to lstat only on UV_DIRENT_UNKNOWN) and src/node_file.cc (the type comes from uv_fs_scandir_next, no stat call). The wording is scoped to directory reads (fs.readdir(), fs.opendir()) because fs.glob() with withFileTypes builds its dirents from lstat() directly.

I used an AI assistant while researching and drafting this change; I've verified the behavior and the wording against the source myself and take full responsibility for it.

Fixes: #30646

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: nodejs#30646 Signed-off-by: Julian Soreavis <julian.soreavis@gmail.com>

lpinca

RSLGTM

trivikr · 2026-08-18T07:00:52Z

cc @nodejs/fs

nodejs-github-bot · 2026-08-18T15:15:51Z

Landed in 29a083c

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: #30646 Signed-off-by: Julian Soreavis <julian.soreavis@gmail.com> PR-URL: #64532 Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Jason Zhang <xzha4350@gmail.com>

soreavis · 2026-07-16T13:47:36Z

The fs.Dirent docs don't say where entry file types come from — the confusion in #30646, where the type reported on a remotely mounted file system didn't match lstat() and @addaleax suggested documenting that "the type of the entry may be dependent on the file system and operating system". This adds one paragraph to the fs.Dirent class intro: the type of an entry from a directory read is the type reported by the operating system, it may depend on the file system, lstat() is only used as a fallback when the reported type is unknown, and fs.lstat() is the accurate alternative.

Verified against lib/internal/fs/utils.js (getDirent/getDirents fall back to lstat only on UV_DIRENT_UNKNOWN) and src/node_file.cc (the type comes from uv_fs_scandir_next, no stat call). The wording is scoped to directory reads (fs.readdir(), fs.opendir()) because fs.glob() with withFileTypes builds its dirents from lstat() directly.

I used an AI assistant while researching and drafting this change; I've verified the behavior and the wording against the source myself and take full responsibility for it.

Fixes: #30646

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: nodejs#30646 Signed-off-by: Julian Soreavis <julian.soreavis@gmail.com>

lpinca

RSLGTM

trivikr · 2026-08-18T07:00:52Z

cc @nodejs/fs

nodejs-github-bot · 2026-08-18T15:15:51Z

Landed in 29a083c

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: #30646 Signed-off-by: Julian Soreavis <julian.soreavis@gmail.com> PR-URL: #64532 Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Jason Zhang <xzha4350@gmail.com>

nodejs-github-bot added doc Issues and PRs related to Node.js documentation. fs Issues and PRs related to file-system APIs and the fs module. labels Jul 16, 2026

soreavis mentioned this pull request Jul 16, 2026
readdir(p, { withFileTypes: true }) seemingly returns wrong type #30646
Closed

lpinca approved these changes Jul 18, 2026
View reviewed changes

jazelly approved these changes Aug 18, 2026
View reviewed changes

trivikr added the commit-queue PRs queued for automated landing through the Commit Queue. label Aug 18, 2026

nodejs-github-bot merged commit 29a083c into nodejs:mainAug 18, 2026
27 checks passed

nodejs-github-bot removed the commit-queue PRs queued for automated landing through the Commit Queue. label Aug 18, 2026

anonrig mentioned this pull request Aug 18, 2026
tools: keep multi-commit PRs in the commit queue #65386
Closed

github-actionsBot mentioned this pull request Aug 25, 2026
2026-08-26, Version 26.8.0 (Current) #65551
Merged