fs: watch directories, not files, in recursive fs.watch fallback by codebytere · Pull Request #65486 · nodejs/node

codebytere · 2026-08-22T15:03:48Z

Makes the JavaScript recursive watcher (used where fs.watch() has no native recursive mode) arm one watcher per directory instead of one per file on Linux, and answer each event with one stat() instead of re-reading the directory.

Linux, this repository's test/ tree (13 500 entries, 896 directories):

	before	after
`fs.watch(test, { recursive: true })` setup	~150 ms, 13 501 handles, +52 MB RSS	~45 ms, 896 handles, +20 MB RSS
`benchmark/fs/bench-watch-recursive.js` (new), `test/fixtures`, 30 runs		+287 % ±4 %
CPU for 300 appends to one file in `test/parallel`	2 860 ms	11 ms
CPU for 100 create+unlink in `test/parallel`	2 890 ms	110 ms

The fallback armed an fs.watch() handle and ran a statSync() for every file in the tree, and handled every event by stat()ing and re-reading the whole directory it happened in. A file replaced by rename() (the usual editor save) also stopped being reported, because its watch stayed on the old inode, and watcher.ref()/unref() were no-ops on this path.

inotify reports changes to a watched directory's entries with the entry name, so on Linux the watcher now keeps one handle per directory (symbolic links keep their own, as before) plus the set of known paths, and resolves an event with a single stat() of the named entry: new names are reported as 'rename' and descended into if they are directories, vanished ones are dropped with their subtree and reported as 'rename', changes to known files are 'change'. kqueue and event ports only report that the directory itself changed, so on the other platforms this fallback serves (illumos, the BSDs, AIX) files keep a watcher each and a directory event rescans that directory, as today. Two event differences remain, both matching the native watchers: creating a file with content yields 'rename' then 'change', and a file keeps being reported after it is replaced by rename(). ref()/unref() now reach the handles.

Tests: all test-fs-watch-recursive-*, test-fs-watch-ignore-*, test-fs-promises-watch* and watch-mode tests pass in both modes (the per-file mode exercised on Linux by flipping the platform check; recursive ones 3/3 repeated runs); a new Linux-only test covers the per-directory handle count, rename-over reporting, events behind a symbolic link, removal of a watched root directory and root file, and ref()/unref().

Disclosure: the code, test, benchmark, measurements and this description were written by Claude Code, directed and reviewed by @codebytere.

nodejs-github-bot · 2026-08-22T15:03:54Z

Review requested:

@nodejs/performance

codecov · 2026-08-22T16:54:15Z

Codecov Report

❌ Patch coverage is 84.76821% with 23 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.14%. Comparing base (21f0f27) to head (7774d81).
⚠️ Report is 188 commits behind head on main.

Files with missing lines	Patch %	Lines
lib/internal/fs/recursive_watch.js	84.76%	22 Missing and 1 partial ⚠️

Additional details and impacted files

@@ Coverage Diff @@## main #65486 +/- ##
==========================================
+ Coverage 90.12% 90.14% +0.02% 
==========================================
Files 752 751 -1 Lines 252315 253482 +1167 Branches 47444 47747 +303 ==========================================
+ Hits 227395 228501 +1106 - Misses 16217 16252 +35 - Partials 8703 8729 +26

Files with missing lines	Coverage Δ
lib/internal/fs/recursive_watch.js	`86.47% <84.76%> (-0.74%)`	⬇️

... and 86 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

nodejs-github-bot · 2026-08-23T08:43:55Z

CI: https://ci.nodejs.org/job/node-test-pull-request/76280/

The JavaScript recursive watcher used on platforms without a native one (notably Linux) armed an fs.watch() handle and a stat() for every file in the tree, and answered every event by stat()ing and re-reading the whole directory it happened in. A 13k-entry tree cost 13.5k inotify watches, ~150 ms and ~50 MB to set up, and appending to one file in a 3900-entry directory cost ~9 ms of CPU per event. A file replaced by rename() (the usual editor save) also stopped being reported, since its watch stayed on the old inode. inotify reports changes to the entries of a watched directory, with their names, so on Linux watch each directory once (symbolic links keep their own watcher, as before), keep the set of known paths, and resolve an event with a single stat() of the named entry: unknown names are added and reported as 'rename', vanished ones are dropped and reported as 'rename', file changes are reported as 'change'. kqueue and event ports only report that a directory changed, so on the other platforms served by this fallback every file keeps its own watcher and a directory event rescans that directory, as before. unref() and ref() now reach the underlying handles. Signed-off-by: Shelley Vohr <shelley.vohr@gmail.com>

codebytere · 2026-08-23T20:44:56Z

@MoLow mind taking another look? the non-Linux path changed since your review

nodejs-github-bot · 2026-08-30T15:51:22Z

CI: https://ci.nodejs.org/job/node-test-pull-request/76735/

nodejs-github-bot · 2026-08-31T13:07:42Z

Landed in 2ec0f9a

aduh95 · 2026-08-31T15:04:09Z

CI on main is failing since this change:

=== release test-fs-watch-enoent === Path: parallel/test-fs-watch-enoent
node:internal/assert/utils:146
throw error;
^
AssertionError [ERR_ASSERTION]: Missing expected exception.
at Object.<anonymous> (/Users/duhamean/Documents/nodejs/node/test/parallel/test-fs-watch-enoent.js:112:12)
at Module._compile (node:internal/modules/cjs/loader:1937:14)
at Object..js (node:internal/modules/cjs/loader:2077:10)
at Module.load (node:internal/modules/cjs/loader:1659:32)
at Module._load (node:internal/modules/cjs/loader:1451:12)
at wrapModuleLoad (node:internal/modules/cjs/loader:261:19)
at Module.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:154:5)
at node:internal/main/run_main_module:33:47 {
generatedMessage: false,
code: 'ERR_ASSERTION',
actual: undefined,
expected: [Function (anonymous)],
operator: 'throws',
diff: 'simple'
}
Node.js v27.0.0-pre

panva · 2026-08-31T15:15:13Z

#65683

The JavaScript recursive watcher used on platforms without a native one (notably Linux) armed an fs.watch() handle and a stat() for every file in the tree, and answered every event by stat()ing and re-reading the whole directory it happened in. A 13k-entry tree cost 13.5k inotify watches, ~150 ms and ~50 MB to set up, and appending to one file in a 3900-entry directory cost ~9 ms of CPU per event. A file replaced by rename() (the usual editor save) also stopped being reported, since its watch stayed on the old inode. inotify reports changes to the entries of a watched directory, with their names, so on Linux watch each directory once (symbolic links keep their own watcher, as before), keep the set of known paths, and resolve an event with a single stat() of the named entry: unknown names are added and reported as 'rename', vanished ones are dropped and reported as 'rename', file changes are reported as 'change'. kqueue and event ports only report that a directory changed, so on the other platforms served by this fallback every file keeps its own watcher and a directory event rescans that directory, as before. unref() and ref() now reach the underlying handles. Signed-off-by: Shelley Vohr <shelley.vohr@gmail.com> PR-URL: #65486 Reviewed-By: Moshe Atlow <moshe@atlow.co.il>

codebytere · 2026-08-22T15:03:48Z

Makes the JavaScript recursive watcher (used where fs.watch() has no native recursive mode) arm one watcher per directory instead of one per file on Linux, and answer each event with one stat() instead of re-reading the directory.

Linux, this repository's test/ tree (13 500 entries, 896 directories):

	before	after
`fs.watch(test, { recursive: true })` setup	~150 ms, 13 501 handles, +52 MB RSS	~45 ms, 896 handles, +20 MB RSS
`benchmark/fs/bench-watch-recursive.js` (new), `test/fixtures`, 30 runs		+287 % ±4 %
CPU for 300 appends to one file in `test/parallel`	2 860 ms	11 ms
CPU for 100 create+unlink in `test/parallel`	2 890 ms	110 ms

The fallback armed an fs.watch() handle and ran a statSync() for every file in the tree, and handled every event by stat()ing and re-reading the whole directory it happened in. A file replaced by rename() (the usual editor save) also stopped being reported, because its watch stayed on the old inode, and watcher.ref()/unref() were no-ops on this path.

inotify reports changes to a watched directory's entries with the entry name, so on Linux the watcher now keeps one handle per directory (symbolic links keep their own, as before) plus the set of known paths, and resolves an event with a single stat() of the named entry: new names are reported as 'rename' and descended into if they are directories, vanished ones are dropped with their subtree and reported as 'rename', changes to known files are 'change'. kqueue and event ports only report that the directory itself changed, so on the other platforms this fallback serves (illumos, the BSDs, AIX) files keep a watcher each and a directory event rescans that directory, as today. Two event differences remain, both matching the native watchers: creating a file with content yields 'rename' then 'change', and a file keeps being reported after it is replaced by rename(). ref()/unref() now reach the handles.

Tests: all test-fs-watch-recursive-*, test-fs-watch-ignore-*, test-fs-promises-watch* and watch-mode tests pass in both modes (the per-file mode exercised on Linux by flipping the platform check; recursive ones 3/3 repeated runs); a new Linux-only test covers the per-directory handle count, rename-over reporting, events behind a symbolic link, removal of a watched root directory and root file, and ref()/unref().

Disclosure: the code, test, benchmark, measurements and this description were written by Claude Code, directed and reviewed by @codebytere.

nodejs-github-bot · 2026-08-22T15:03:54Z

Review requested:

@nodejs/performance

codecov · 2026-08-22T16:54:15Z

Codecov Report

❌ Patch coverage is 84.76821% with 23 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.14%. Comparing base (21f0f27) to head (7774d81).
⚠️ Report is 188 commits behind head on main.

Files with missing lines	Patch %	Lines
lib/internal/fs/recursive_watch.js	84.76%	22 Missing and 1 partial ⚠️

Additional details and impacted files

@@ Coverage Diff @@## main #65486 +/- ##
==========================================
+ Coverage 90.12% 90.14% +0.02% 
==========================================
Files 752 751 -1 Lines 252315 253482 +1167 Branches 47444 47747 +303 ==========================================
+ Hits 227395 228501 +1106 - Misses 16217 16252 +35 - Partials 8703 8729 +26

Files with missing lines	Coverage Δ
lib/internal/fs/recursive_watch.js	`86.47% <84.76%> (-0.74%)`	⬇️

... and 86 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

nodejs-github-bot · 2026-08-23T08:43:55Z

CI: https://ci.nodejs.org/job/node-test-pull-request/76280/

The JavaScript recursive watcher used on platforms without a native one (notably Linux) armed an fs.watch() handle and a stat() for every file in the tree, and answered every event by stat()ing and re-reading the whole directory it happened in. A 13k-entry tree cost 13.5k inotify watches, ~150 ms and ~50 MB to set up, and appending to one file in a 3900-entry directory cost ~9 ms of CPU per event. A file replaced by rename() (the usual editor save) also stopped being reported, since its watch stayed on the old inode. inotify reports changes to the entries of a watched directory, with their names, so on Linux watch each directory once (symbolic links keep their own watcher, as before), keep the set of known paths, and resolve an event with a single stat() of the named entry: unknown names are added and reported as 'rename', vanished ones are dropped and reported as 'rename', file changes are reported as 'change'. kqueue and event ports only report that a directory changed, so on the other platforms served by this fallback every file keeps its own watcher and a directory event rescans that directory, as before. unref() and ref() now reach the underlying handles. Signed-off-by: Shelley Vohr <shelley.vohr@gmail.com>

codebytere · 2026-08-23T20:44:56Z

@MoLow mind taking another look? the non-Linux path changed since your review

nodejs-github-bot · 2026-08-30T15:51:22Z

CI: https://ci.nodejs.org/job/node-test-pull-request/76735/

nodejs-github-bot · 2026-08-31T13:07:42Z

Landed in 2ec0f9a

aduh95 · 2026-08-31T15:04:09Z

CI on main is failing since this change:

=== release test-fs-watch-enoent === Path: parallel/test-fs-watch-enoent
node:internal/assert/utils:146
throw error;
^
AssertionError [ERR_ASSERTION]: Missing expected exception.
at Object.<anonymous> (/Users/duhamean/Documents/nodejs/node/test/parallel/test-fs-watch-enoent.js:112:12)
at Module._compile (node:internal/modules/cjs/loader:1937:14)
at Object..js (node:internal/modules/cjs/loader:2077:10)
at Module.load (node:internal/modules/cjs/loader:1659:32)
at Module._load (node:internal/modules/cjs/loader:1451:12)
at wrapModuleLoad (node:internal/modules/cjs/loader:261:19)
at Module.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:154:5)
at node:internal/main/run_main_module:33:47 {
generatedMessage: false,
code: 'ERR_ASSERTION',
actual: undefined,
expected: [Function (anonymous)],
operator: 'throws',
diff: 'simple'
}
Node.js v27.0.0-pre

panva · 2026-08-31T15:15:13Z

#65683

The JavaScript recursive watcher used on platforms without a native one (notably Linux) armed an fs.watch() handle and a stat() for every file in the tree, and answered every event by stat()ing and re-reading the whole directory it happened in. A 13k-entry tree cost 13.5k inotify watches, ~150 ms and ~50 MB to set up, and appending to one file in a 3900-entry directory cost ~9 ms of CPU per event. A file replaced by rename() (the usual editor save) also stopped being reported, since its watch stayed on the old inode. inotify reports changes to the entries of a watched directory, with their names, so on Linux watch each directory once (symbolic links keep their own watcher, as before), keep the set of known paths, and resolve an event with a single stat() of the named entry: unknown names are added and reported as 'rename', vanished ones are dropped and reported as 'rename', file changes are reported as 'change'. kqueue and event ports only report that a directory changed, so on the other platforms served by this fallback every file keeps its own watcher and a directory event rescans that directory, as before. unref() and ref() now reach the underlying handles. Signed-off-by: Shelley Vohr <shelley.vohr@gmail.com> PR-URL: #65486 Reviewed-By: Moshe Atlow <moshe@atlow.co.il>

codebytere · 2026-08-22T15:03:48Z

Makes the JavaScript recursive watcher (used where fs.watch() has no native recursive mode) arm one watcher per directory instead of one per file on Linux, and answer each event with one stat() instead of re-reading the directory.

Linux, this repository's test/ tree (13 500 entries, 896 directories):

	before	after
`fs.watch(test, { recursive: true })` setup	~150 ms, 13 501 handles, +52 MB RSS	~45 ms, 896 handles, +20 MB RSS
`benchmark/fs/bench-watch-recursive.js` (new), `test/fixtures`, 30 runs		+287 % ±4 %
CPU for 300 appends to one file in `test/parallel`	2 860 ms	11 ms
CPU for 100 create+unlink in `test/parallel`	2 890 ms	110 ms

The fallback armed an fs.watch() handle and ran a statSync() for every file in the tree, and handled every event by stat()ing and re-reading the whole directory it happened in. A file replaced by rename() (the usual editor save) also stopped being reported, because its watch stayed on the old inode, and watcher.ref()/unref() were no-ops on this path.

inotify reports changes to a watched directory's entries with the entry name, so on Linux the watcher now keeps one handle per directory (symbolic links keep their own, as before) plus the set of known paths, and resolves an event with a single stat() of the named entry: new names are reported as 'rename' and descended into if they are directories, vanished ones are dropped with their subtree and reported as 'rename', changes to known files are 'change'. kqueue and event ports only report that the directory itself changed, so on the other platforms this fallback serves (illumos, the BSDs, AIX) files keep a watcher each and a directory event rescans that directory, as today. Two event differences remain, both matching the native watchers: creating a file with content yields 'rename' then 'change', and a file keeps being reported after it is replaced by rename(). ref()/unref() now reach the handles.

Tests: all test-fs-watch-recursive-*, test-fs-watch-ignore-*, test-fs-promises-watch* and watch-mode tests pass in both modes (the per-file mode exercised on Linux by flipping the platform check; recursive ones 3/3 repeated runs); a new Linux-only test covers the per-directory handle count, rename-over reporting, events behind a symbolic link, removal of a watched root directory and root file, and ref()/unref().

Disclosure: the code, test, benchmark, measurements and this description were written by Claude Code, directed and reviewed by @codebytere.

nodejs-github-bot · 2026-08-22T15:03:54Z

Review requested:

@nodejs/performance

codecov · 2026-08-22T16:54:15Z

Codecov Report

❌ Patch coverage is 84.76821% with 23 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.14%. Comparing base (21f0f27) to head (7774d81).
⚠️ Report is 188 commits behind head on main.

Files with missing lines	Patch %	Lines
lib/internal/fs/recursive_watch.js	84.76%	22 Missing and 1 partial ⚠️

Additional details and impacted files

@@ Coverage Diff @@## main #65486 +/- ##
==========================================
+ Coverage 90.12% 90.14% +0.02% 
==========================================
Files 752 751 -1 Lines 252315 253482 +1167 Branches 47444 47747 +303 ==========================================
+ Hits 227395 228501 +1106 - Misses 16217 16252 +35 - Partials 8703 8729 +26

Files with missing lines	Coverage Δ
lib/internal/fs/recursive_watch.js	`86.47% <84.76%> (-0.74%)`	⬇️

... and 86 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

nodejs-github-bot · 2026-08-23T08:43:55Z

CI: https://ci.nodejs.org/job/node-test-pull-request/76280/

The JavaScript recursive watcher used on platforms without a native one (notably Linux) armed an fs.watch() handle and a stat() for every file in the tree, and answered every event by stat()ing and re-reading the whole directory it happened in. A 13k-entry tree cost 13.5k inotify watches, ~150 ms and ~50 MB to set up, and appending to one file in a 3900-entry directory cost ~9 ms of CPU per event. A file replaced by rename() (the usual editor save) also stopped being reported, since its watch stayed on the old inode. inotify reports changes to the entries of a watched directory, with their names, so on Linux watch each directory once (symbolic links keep their own watcher, as before), keep the set of known paths, and resolve an event with a single stat() of the named entry: unknown names are added and reported as 'rename', vanished ones are dropped and reported as 'rename', file changes are reported as 'change'. kqueue and event ports only report that a directory changed, so on the other platforms served by this fallback every file keeps its own watcher and a directory event rescans that directory, as before. unref() and ref() now reach the underlying handles. Signed-off-by: Shelley Vohr <shelley.vohr@gmail.com>

codebytere · 2026-08-23T20:44:56Z

@MoLow mind taking another look? the non-Linux path changed since your review

nodejs-github-bot · 2026-08-30T15:51:22Z

CI: https://ci.nodejs.org/job/node-test-pull-request/76735/

nodejs-github-bot · 2026-08-31T13:07:42Z

Landed in 2ec0f9a

aduh95 · 2026-08-31T15:04:09Z

CI on main is failing since this change:

=== release test-fs-watch-enoent === Path: parallel/test-fs-watch-enoent
node:internal/assert/utils:146
throw error;
^
AssertionError [ERR_ASSERTION]: Missing expected exception.
at Object.<anonymous> (/Users/duhamean/Documents/nodejs/node/test/parallel/test-fs-watch-enoent.js:112:12)
at Module._compile (node:internal/modules/cjs/loader:1937:14)
at Object..js (node:internal/modules/cjs/loader:2077:10)
at Module.load (node:internal/modules/cjs/loader:1659:32)
at Module._load (node:internal/modules/cjs/loader:1451:12)
at wrapModuleLoad (node:internal/modules/cjs/loader:261:19)
at Module.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:154:5)
at node:internal/main/run_main_module:33:47 {
generatedMessage: false,
code: 'ERR_ASSERTION',
actual: undefined,
expected: [Function (anonymous)],
operator: 'throws',
diff: 'simple'
}
Node.js v27.0.0-pre

panva · 2026-08-31T15:15:13Z

#65683

The JavaScript recursive watcher used on platforms without a native one (notably Linux) armed an fs.watch() handle and a stat() for every file in the tree, and answered every event by stat()ing and re-reading the whole directory it happened in. A 13k-entry tree cost 13.5k inotify watches, ~150 ms and ~50 MB to set up, and appending to one file in a 3900-entry directory cost ~9 ms of CPU per event. A file replaced by rename() (the usual editor save) also stopped being reported, since its watch stayed on the old inode. inotify reports changes to the entries of a watched directory, with their names, so on Linux watch each directory once (symbolic links keep their own watcher, as before), keep the set of known paths, and resolve an event with a single stat() of the named entry: unknown names are added and reported as 'rename', vanished ones are dropped and reported as 'rename', file changes are reported as 'change'. kqueue and event ports only report that a directory changed, so on the other platforms served by this fallback every file keeps its own watcher and a directory event rescans that directory, as before. unref() and ref() now reach the underlying handles. Signed-off-by: Shelley Vohr <shelley.vohr@gmail.com> PR-URL: #65486 Reviewed-By: Moshe Atlow <moshe@atlow.co.il>

codebytere · 2026-08-22T15:03:48Z

Makes the JavaScript recursive watcher (used where fs.watch() has no native recursive mode) arm one watcher per directory instead of one per file on Linux, and answer each event with one stat() instead of re-reading the directory.

Linux, this repository's test/ tree (13 500 entries, 896 directories):

	before	after
`fs.watch(test, { recursive: true })` setup	~150 ms, 13 501 handles, +52 MB RSS	~45 ms, 896 handles, +20 MB RSS
`benchmark/fs/bench-watch-recursive.js` (new), `test/fixtures`, 30 runs		+287 % ±4 %
CPU for 300 appends to one file in `test/parallel`	2 860 ms	11 ms
CPU for 100 create+unlink in `test/parallel`	2 890 ms	110 ms

The fallback armed an fs.watch() handle and ran a statSync() for every file in the tree, and handled every event by stat()ing and re-reading the whole directory it happened in. A file replaced by rename() (the usual editor save) also stopped being reported, because its watch stayed on the old inode, and watcher.ref()/unref() were no-ops on this path.

inotify reports changes to a watched directory's entries with the entry name, so on Linux the watcher now keeps one handle per directory (symbolic links keep their own, as before) plus the set of known paths, and resolves an event with a single stat() of the named entry: new names are reported as 'rename' and descended into if they are directories, vanished ones are dropped with their subtree and reported as 'rename', changes to known files are 'change'. kqueue and event ports only report that the directory itself changed, so on the other platforms this fallback serves (illumos, the BSDs, AIX) files keep a watcher each and a directory event rescans that directory, as today. Two event differences remain, both matching the native watchers: creating a file with content yields 'rename' then 'change', and a file keeps being reported after it is replaced by rename(). ref()/unref() now reach the handles.

Tests: all test-fs-watch-recursive-*, test-fs-watch-ignore-*, test-fs-promises-watch* and watch-mode tests pass in both modes (the per-file mode exercised on Linux by flipping the platform check; recursive ones 3/3 repeated runs); a new Linux-only test covers the per-directory handle count, rename-over reporting, events behind a symbolic link, removal of a watched root directory and root file, and ref()/unref().

Disclosure: the code, test, benchmark, measurements and this description were written by Claude Code, directed and reviewed by @codebytere.

nodejs-github-bot · 2026-08-22T15:03:54Z

Review requested:

@nodejs/performance

codecov · 2026-08-22T16:54:15Z

Codecov Report

❌ Patch coverage is 84.76821% with 23 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.14%. Comparing base (21f0f27) to head (7774d81).
⚠️ Report is 188 commits behind head on main.

Files with missing lines	Patch %	Lines
lib/internal/fs/recursive_watch.js	84.76%	22 Missing and 1 partial ⚠️

Additional details and impacted files

@@ Coverage Diff @@## main #65486 +/- ##
==========================================
+ Coverage 90.12% 90.14% +0.02% 
==========================================
Files 752 751 -1 Lines 252315 253482 +1167 Branches 47444 47747 +303 ==========================================
+ Hits 227395 228501 +1106 - Misses 16217 16252 +35 - Partials 8703 8729 +26

Files with missing lines	Coverage Δ
lib/internal/fs/recursive_watch.js	`86.47% <84.76%> (-0.74%)`	⬇️

... and 86 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

nodejs-github-bot · 2026-08-23T08:43:55Z

CI: https://ci.nodejs.org/job/node-test-pull-request/76280/

The JavaScript recursive watcher used on platforms without a native one (notably Linux) armed an fs.watch() handle and a stat() for every file in the tree, and answered every event by stat()ing and re-reading the whole directory it happened in. A 13k-entry tree cost 13.5k inotify watches, ~150 ms and ~50 MB to set up, and appending to one file in a 3900-entry directory cost ~9 ms of CPU per event. A file replaced by rename() (the usual editor save) also stopped being reported, since its watch stayed on the old inode. inotify reports changes to the entries of a watched directory, with their names, so on Linux watch each directory once (symbolic links keep their own watcher, as before), keep the set of known paths, and resolve an event with a single stat() of the named entry: unknown names are added and reported as 'rename', vanished ones are dropped and reported as 'rename', file changes are reported as 'change'. kqueue and event ports only report that a directory changed, so on the other platforms served by this fallback every file keeps its own watcher and a directory event rescans that directory, as before. unref() and ref() now reach the underlying handles. Signed-off-by: Shelley Vohr <shelley.vohr@gmail.com>

codebytere · 2026-08-23T20:44:56Z

@MoLow mind taking another look? the non-Linux path changed since your review

nodejs-github-bot · 2026-08-30T15:51:22Z

CI: https://ci.nodejs.org/job/node-test-pull-request/76735/

nodejs-github-bot · 2026-08-31T13:07:42Z

Landed in 2ec0f9a

aduh95 · 2026-08-31T15:04:09Z

CI on main is failing since this change:

=== release test-fs-watch-enoent === Path: parallel/test-fs-watch-enoent
node:internal/assert/utils:146
throw error;
^
AssertionError [ERR_ASSERTION]: Missing expected exception.
at Object.<anonymous> (/Users/duhamean/Documents/nodejs/node/test/parallel/test-fs-watch-enoent.js:112:12)
at Module._compile (node:internal/modules/cjs/loader:1937:14)
at Object..js (node:internal/modules/cjs/loader:2077:10)
at Module.load (node:internal/modules/cjs/loader:1659:32)
at Module._load (node:internal/modules/cjs/loader:1451:12)
at wrapModuleLoad (node:internal/modules/cjs/loader:261:19)
at Module.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:154:5)
at node:internal/main/run_main_module:33:47 {
generatedMessage: false,
code: 'ERR_ASSERTION',
actual: undefined,
expected: [Function (anonymous)],
operator: 'throws',
diff: 'simple'
}
Node.js v27.0.0-pre

panva · 2026-08-31T15:15:13Z

#65683

The JavaScript recursive watcher used on platforms without a native one (notably Linux) armed an fs.watch() handle and a stat() for every file in the tree, and answered every event by stat()ing and re-reading the whole directory it happened in. A 13k-entry tree cost 13.5k inotify watches, ~150 ms and ~50 MB to set up, and appending to one file in a 3900-entry directory cost ~9 ms of CPU per event. A file replaced by rename() (the usual editor save) also stopped being reported, since its watch stayed on the old inode. inotify reports changes to the entries of a watched directory, with their names, so on Linux watch each directory once (symbolic links keep their own watcher, as before), keep the set of known paths, and resolve an event with a single stat() of the named entry: unknown names are added and reported as 'rename', vanished ones are dropped and reported as 'rename', file changes are reported as 'change'. kqueue and event ports only report that a directory changed, so on the other platforms served by this fallback every file keeps its own watcher and a directory event rescans that directory, as before. unref() and ref() now reach the underlying handles. Signed-off-by: Shelley Vohr <shelley.vohr@gmail.com> PR-URL: #65486 Reviewed-By: Moshe Atlow <moshe@atlow.co.il>

codebytere · 2026-08-22T15:03:48Z

Makes the JavaScript recursive watcher (used where fs.watch() has no native recursive mode) arm one watcher per directory instead of one per file on Linux, and answer each event with one stat() instead of re-reading the directory.

Linux, this repository's test/ tree (13 500 entries, 896 directories):

	before	after
`fs.watch(test, { recursive: true })` setup	~150 ms, 13 501 handles, +52 MB RSS	~45 ms, 896 handles, +20 MB RSS
`benchmark/fs/bench-watch-recursive.js` (new), `test/fixtures`, 30 runs		+287 % ±4 %
CPU for 300 appends to one file in `test/parallel`	2 860 ms	11 ms
CPU for 100 create+unlink in `test/parallel`	2 890 ms	110 ms

The fallback armed an fs.watch() handle and ran a statSync() for every file in the tree, and handled every event by stat()ing and re-reading the whole directory it happened in. A file replaced by rename() (the usual editor save) also stopped being reported, because its watch stayed on the old inode, and watcher.ref()/unref() were no-ops on this path.

inotify reports changes to a watched directory's entries with the entry name, so on Linux the watcher now keeps one handle per directory (symbolic links keep their own, as before) plus the set of known paths, and resolves an event with a single stat() of the named entry: new names are reported as 'rename' and descended into if they are directories, vanished ones are dropped with their subtree and reported as 'rename', changes to known files are 'change'. kqueue and event ports only report that the directory itself changed, so on the other platforms this fallback serves (illumos, the BSDs, AIX) files keep a watcher each and a directory event rescans that directory, as today. Two event differences remain, both matching the native watchers: creating a file with content yields 'rename' then 'change', and a file keeps being reported after it is replaced by rename(). ref()/unref() now reach the handles.

Tests: all test-fs-watch-recursive-*, test-fs-watch-ignore-*, test-fs-promises-watch* and watch-mode tests pass in both modes (the per-file mode exercised on Linux by flipping the platform check; recursive ones 3/3 repeated runs); a new Linux-only test covers the per-directory handle count, rename-over reporting, events behind a symbolic link, removal of a watched root directory and root file, and ref()/unref().

Disclosure: the code, test, benchmark, measurements and this description were written by Claude Code, directed and reviewed by @codebytere.

nodejs-github-bot · 2026-08-22T15:03:54Z

Review requested:

@nodejs/performance

codecov · 2026-08-22T16:54:15Z

Codecov Report

❌ Patch coverage is 84.76821% with 23 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.14%. Comparing base (21f0f27) to head (7774d81).
⚠️ Report is 188 commits behind head on main.

Files with missing lines	Patch %	Lines
lib/internal/fs/recursive_watch.js	84.76%	22 Missing and 1 partial ⚠️

Additional details and impacted files

@@ Coverage Diff @@## main #65486 +/- ##
==========================================
+ Coverage 90.12% 90.14% +0.02% 
==========================================
Files 752 751 -1 Lines 252315 253482 +1167 Branches 47444 47747 +303 ==========================================
+ Hits 227395 228501 +1106 - Misses 16217 16252 +35 - Partials 8703 8729 +26

Files with missing lines	Coverage Δ
lib/internal/fs/recursive_watch.js	`86.47% <84.76%> (-0.74%)`	⬇️

... and 86 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

nodejs-github-bot · 2026-08-23T08:43:55Z

CI: https://ci.nodejs.org/job/node-test-pull-request/76280/

The JavaScript recursive watcher used on platforms without a native one (notably Linux) armed an fs.watch() handle and a stat() for every file in the tree, and answered every event by stat()ing and re-reading the whole directory it happened in. A 13k-entry tree cost 13.5k inotify watches, ~150 ms and ~50 MB to set up, and appending to one file in a 3900-entry directory cost ~9 ms of CPU per event. A file replaced by rename() (the usual editor save) also stopped being reported, since its watch stayed on the old inode. inotify reports changes to the entries of a watched directory, with their names, so on Linux watch each directory once (symbolic links keep their own watcher, as before), keep the set of known paths, and resolve an event with a single stat() of the named entry: unknown names are added and reported as 'rename', vanished ones are dropped and reported as 'rename', file changes are reported as 'change'. kqueue and event ports only report that a directory changed, so on the other platforms served by this fallback every file keeps its own watcher and a directory event rescans that directory, as before. unref() and ref() now reach the underlying handles. Signed-off-by: Shelley Vohr <shelley.vohr@gmail.com>

codebytere · 2026-08-23T20:44:56Z

@MoLow mind taking another look? the non-Linux path changed since your review

nodejs-github-bot · 2026-08-30T15:51:22Z

CI: https://ci.nodejs.org/job/node-test-pull-request/76735/

nodejs-github-bot · 2026-08-31T13:07:42Z

Landed in 2ec0f9a

aduh95 · 2026-08-31T15:04:09Z

CI on main is failing since this change:

=== release test-fs-watch-enoent === Path: parallel/test-fs-watch-enoent
node:internal/assert/utils:146
throw error;
^
AssertionError [ERR_ASSERTION]: Missing expected exception.
at Object.<anonymous> (/Users/duhamean/Documents/nodejs/node/test/parallel/test-fs-watch-enoent.js:112:12)
at Module._compile (node:internal/modules/cjs/loader:1937:14)
at Object..js (node:internal/modules/cjs/loader:2077:10)
at Module.load (node:internal/modules/cjs/loader:1659:32)
at Module._load (node:internal/modules/cjs/loader:1451:12)
at wrapModuleLoad (node:internal/modules/cjs/loader:261:19)
at Module.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:154:5)
at node:internal/main/run_main_module:33:47 {
generatedMessage: false,
code: 'ERR_ASSERTION',
actual: undefined,
expected: [Function (anonymous)],
operator: 'throws',
diff: 'simple'
}
Node.js v27.0.0-pre

panva · 2026-08-31T15:15:13Z

#65683

The JavaScript recursive watcher used on platforms without a native one (notably Linux) armed an fs.watch() handle and a stat() for every file in the tree, and answered every event by stat()ing and re-reading the whole directory it happened in. A 13k-entry tree cost 13.5k inotify watches, ~150 ms and ~50 MB to set up, and appending to one file in a 3900-entry directory cost ~9 ms of CPU per event. A file replaced by rename() (the usual editor save) also stopped being reported, since its watch stayed on the old inode. inotify reports changes to the entries of a watched directory, with their names, so on Linux watch each directory once (symbolic links keep their own watcher, as before), keep the set of known paths, and resolve an event with a single stat() of the named entry: unknown names are added and reported as 'rename', vanished ones are dropped and reported as 'rename', file changes are reported as 'change'. kqueue and event ports only report that a directory changed, so on the other platforms served by this fallback every file keeps its own watcher and a directory event rescans that directory, as before. unref() and ref() now reach the underlying handles. Signed-off-by: Shelley Vohr <shelley.vohr@gmail.com> PR-URL: #65486 Reviewed-By: Moshe Atlow <moshe@atlow.co.il>

codebytere · 2026-08-22T15:03:48Z

Makes the JavaScript recursive watcher (used where fs.watch() has no native recursive mode) arm one watcher per directory instead of one per file on Linux, and answer each event with one stat() instead of re-reading the directory.

Linux, this repository's test/ tree (13 500 entries, 896 directories):

	before	after
`fs.watch(test, { recursive: true })` setup	~150 ms, 13 501 handles, +52 MB RSS	~45 ms, 896 handles, +20 MB RSS
`benchmark/fs/bench-watch-recursive.js` (new), `test/fixtures`, 30 runs		+287 % ±4 %
CPU for 300 appends to one file in `test/parallel`	2 860 ms	11 ms
CPU for 100 create+unlink in `test/parallel`	2 890 ms	110 ms

The fallback armed an fs.watch() handle and ran a statSync() for every file in the tree, and handled every event by stat()ing and re-reading the whole directory it happened in. A file replaced by rename() (the usual editor save) also stopped being reported, because its watch stayed on the old inode, and watcher.ref()/unref() were no-ops on this path.

inotify reports changes to a watched directory's entries with the entry name, so on Linux the watcher now keeps one handle per directory (symbolic links keep their own, as before) plus the set of known paths, and resolves an event with a single stat() of the named entry: new names are reported as 'rename' and descended into if they are directories, vanished ones are dropped with their subtree and reported as 'rename', changes to known files are 'change'. kqueue and event ports only report that the directory itself changed, so on the other platforms this fallback serves (illumos, the BSDs, AIX) files keep a watcher each and a directory event rescans that directory, as today. Two event differences remain, both matching the native watchers: creating a file with content yields 'rename' then 'change', and a file keeps being reported after it is replaced by rename(). ref()/unref() now reach the handles.

Tests: all test-fs-watch-recursive-*, test-fs-watch-ignore-*, test-fs-promises-watch* and watch-mode tests pass in both modes (the per-file mode exercised on Linux by flipping the platform check; recursive ones 3/3 repeated runs); a new Linux-only test covers the per-directory handle count, rename-over reporting, events behind a symbolic link, removal of a watched root directory and root file, and ref()/unref().

Disclosure: the code, test, benchmark, measurements and this description were written by Claude Code, directed and reviewed by @codebytere.

nodejs-github-bot · 2026-08-22T15:03:54Z

Review requested:

@nodejs/performance

codecov · 2026-08-22T16:54:15Z

Codecov Report

❌ Patch coverage is 84.76821% with 23 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.14%. Comparing base (21f0f27) to head (7774d81).
⚠️ Report is 188 commits behind head on main.

Files with missing lines	Patch %	Lines
lib/internal/fs/recursive_watch.js	84.76%	22 Missing and 1 partial ⚠️

Additional details and impacted files

@@ Coverage Diff @@## main #65486 +/- ##
==========================================
+ Coverage 90.12% 90.14% +0.02% 
==========================================
Files 752 751 -1 Lines 252315 253482 +1167 Branches 47444 47747 +303 ==========================================
+ Hits 227395 228501 +1106 - Misses 16217 16252 +35 - Partials 8703 8729 +26

Files with missing lines	Coverage Δ
lib/internal/fs/recursive_watch.js	`86.47% <84.76%> (-0.74%)`	⬇️

... and 86 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

nodejs-github-bot · 2026-08-23T08:43:55Z

CI: https://ci.nodejs.org/job/node-test-pull-request/76280/

The JavaScript recursive watcher used on platforms without a native one (notably Linux) armed an fs.watch() handle and a stat() for every file in the tree, and answered every event by stat()ing and re-reading the whole directory it happened in. A 13k-entry tree cost 13.5k inotify watches, ~150 ms and ~50 MB to set up, and appending to one file in a 3900-entry directory cost ~9 ms of CPU per event. A file replaced by rename() (the usual editor save) also stopped being reported, since its watch stayed on the old inode. inotify reports changes to the entries of a watched directory, with their names, so on Linux watch each directory once (symbolic links keep their own watcher, as before), keep the set of known paths, and resolve an event with a single stat() of the named entry: unknown names are added and reported as 'rename', vanished ones are dropped and reported as 'rename', file changes are reported as 'change'. kqueue and event ports only report that a directory changed, so on the other platforms served by this fallback every file keeps its own watcher and a directory event rescans that directory, as before. unref() and ref() now reach the underlying handles. Signed-off-by: Shelley Vohr <shelley.vohr@gmail.com>

codebytere · 2026-08-23T20:44:56Z

@MoLow mind taking another look? the non-Linux path changed since your review

nodejs-github-bot · 2026-08-30T15:51:22Z

CI: https://ci.nodejs.org/job/node-test-pull-request/76735/

nodejs-github-bot · 2026-08-31T13:07:42Z

Landed in 2ec0f9a

aduh95 · 2026-08-31T15:04:09Z

CI on main is failing since this change:

=== release test-fs-watch-enoent === Path: parallel/test-fs-watch-enoent
node:internal/assert/utils:146
throw error;
^
AssertionError [ERR_ASSERTION]: Missing expected exception.
at Object.<anonymous> (/Users/duhamean/Documents/nodejs/node/test/parallel/test-fs-watch-enoent.js:112:12)
at Module._compile (node:internal/modules/cjs/loader:1937:14)
at Object..js (node:internal/modules/cjs/loader:2077:10)
at Module.load (node:internal/modules/cjs/loader:1659:32)
at Module._load (node:internal/modules/cjs/loader:1451:12)
at wrapModuleLoad (node:internal/modules/cjs/loader:261:19)
at Module.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:154:5)
at node:internal/main/run_main_module:33:47 {
generatedMessage: false,
code: 'ERR_ASSERTION',
actual: undefined,
expected: [Function (anonymous)],
operator: 'throws',
diff: 'simple'
}
Node.js v27.0.0-pre

panva · 2026-08-31T15:15:13Z

#65683

The JavaScript recursive watcher used on platforms without a native one (notably Linux) armed an fs.watch() handle and a stat() for every file in the tree, and answered every event by stat()ing and re-reading the whole directory it happened in. A 13k-entry tree cost 13.5k inotify watches, ~150 ms and ~50 MB to set up, and appending to one file in a 3900-entry directory cost ~9 ms of CPU per event. A file replaced by rename() (the usual editor save) also stopped being reported, since its watch stayed on the old inode. inotify reports changes to the entries of a watched directory, with their names, so on Linux watch each directory once (symbolic links keep their own watcher, as before), keep the set of known paths, and resolve an event with a single stat() of the named entry: unknown names are added and reported as 'rename', vanished ones are dropped and reported as 'rename', file changes are reported as 'change'. kqueue and event ports only report that a directory changed, so on the other platforms served by this fallback every file keeps its own watcher and a directory event rescans that directory, as before. unref() and ref() now reach the underlying handles. Signed-off-by: Shelley Vohr <shelley.vohr@gmail.com> PR-URL: #65486 Reviewed-By: Moshe Atlow <moshe@atlow.co.il>

codebytere · 2026-08-22T15:03:48Z

Makes the JavaScript recursive watcher (used where fs.watch() has no native recursive mode) arm one watcher per directory instead of one per file on Linux, and answer each event with one stat() instead of re-reading the directory.

Linux, this repository's test/ tree (13 500 entries, 896 directories):

	before	after
`fs.watch(test, { recursive: true })` setup	~150 ms, 13 501 handles, +52 MB RSS	~45 ms, 896 handles, +20 MB RSS
`benchmark/fs/bench-watch-recursive.js` (new), `test/fixtures`, 30 runs		+287 % ±4 %
CPU for 300 appends to one file in `test/parallel`	2 860 ms	11 ms
CPU for 100 create+unlink in `test/parallel`	2 890 ms	110 ms

The fallback armed an fs.watch() handle and ran a statSync() for every file in the tree, and handled every event by stat()ing and re-reading the whole directory it happened in. A file replaced by rename() (the usual editor save) also stopped being reported, because its watch stayed on the old inode, and watcher.ref()/unref() were no-ops on this path.

inotify reports changes to a watched directory's entries with the entry name, so on Linux the watcher now keeps one handle per directory (symbolic links keep their own, as before) plus the set of known paths, and resolves an event with a single stat() of the named entry: new names are reported as 'rename' and descended into if they are directories, vanished ones are dropped with their subtree and reported as 'rename', changes to known files are 'change'. kqueue and event ports only report that the directory itself changed, so on the other platforms this fallback serves (illumos, the BSDs, AIX) files keep a watcher each and a directory event rescans that directory, as today. Two event differences remain, both matching the native watchers: creating a file with content yields 'rename' then 'change', and a file keeps being reported after it is replaced by rename(). ref()/unref() now reach the handles.

Tests: all test-fs-watch-recursive-*, test-fs-watch-ignore-*, test-fs-promises-watch* and watch-mode tests pass in both modes (the per-file mode exercised on Linux by flipping the platform check; recursive ones 3/3 repeated runs); a new Linux-only test covers the per-directory handle count, rename-over reporting, events behind a symbolic link, removal of a watched root directory and root file, and ref()/unref().

Disclosure: the code, test, benchmark, measurements and this description were written by Claude Code, directed and reviewed by @codebytere.

nodejs-github-bot · 2026-08-22T15:03:54Z

Review requested:

@nodejs/performance

codecov · 2026-08-22T16:54:15Z

Codecov Report

❌ Patch coverage is 84.76821% with 23 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.14%. Comparing base (21f0f27) to head (7774d81).
⚠️ Report is 188 commits behind head on main.

Files with missing lines	Patch %	Lines
lib/internal/fs/recursive_watch.js	84.76%	22 Missing and 1 partial ⚠️

Additional details and impacted files

@@ Coverage Diff @@## main #65486 +/- ##
==========================================
+ Coverage 90.12% 90.14% +0.02% 
==========================================
Files 752 751 -1 Lines 252315 253482 +1167 Branches 47444 47747 +303 ==========================================
+ Hits 227395 228501 +1106 - Misses 16217 16252 +35 - Partials 8703 8729 +26

Files with missing lines	Coverage Δ
lib/internal/fs/recursive_watch.js	`86.47% <84.76%> (-0.74%)`	⬇️

... and 86 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

nodejs-github-bot · 2026-08-23T08:43:55Z

CI: https://ci.nodejs.org/job/node-test-pull-request/76280/

The JavaScript recursive watcher used on platforms without a native one (notably Linux) armed an fs.watch() handle and a stat() for every file in the tree, and answered every event by stat()ing and re-reading the whole directory it happened in. A 13k-entry tree cost 13.5k inotify watches, ~150 ms and ~50 MB to set up, and appending to one file in a 3900-entry directory cost ~9 ms of CPU per event. A file replaced by rename() (the usual editor save) also stopped being reported, since its watch stayed on the old inode. inotify reports changes to the entries of a watched directory, with their names, so on Linux watch each directory once (symbolic links keep their own watcher, as before), keep the set of known paths, and resolve an event with a single stat() of the named entry: unknown names are added and reported as 'rename', vanished ones are dropped and reported as 'rename', file changes are reported as 'change'. kqueue and event ports only report that a directory changed, so on the other platforms served by this fallback every file keeps its own watcher and a directory event rescans that directory, as before. unref() and ref() now reach the underlying handles. Signed-off-by: Shelley Vohr <shelley.vohr@gmail.com>

codebytere · 2026-08-23T20:44:56Z

@MoLow mind taking another look? the non-Linux path changed since your review

nodejs-github-bot · 2026-08-30T15:51:22Z

CI: https://ci.nodejs.org/job/node-test-pull-request/76735/

nodejs-github-bot · 2026-08-31T13:07:42Z

Landed in 2ec0f9a

aduh95 · 2026-08-31T15:04:09Z

CI on main is failing since this change:

=== release test-fs-watch-enoent === Path: parallel/test-fs-watch-enoent
node:internal/assert/utils:146
throw error;
^
AssertionError [ERR_ASSERTION]: Missing expected exception.
at Object.<anonymous> (/Users/duhamean/Documents/nodejs/node/test/parallel/test-fs-watch-enoent.js:112:12)
at Module._compile (node:internal/modules/cjs/loader:1937:14)
at Object..js (node:internal/modules/cjs/loader:2077:10)
at Module.load (node:internal/modules/cjs/loader:1659:32)
at Module._load (node:internal/modules/cjs/loader:1451:12)
at wrapModuleLoad (node:internal/modules/cjs/loader:261:19)
at Module.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:154:5)
at node:internal/main/run_main_module:33:47 {
generatedMessage: false,
code: 'ERR_ASSERTION',
actual: undefined,
expected: [Function (anonymous)],
operator: 'throws',
diff: 'simple'
}
Node.js v27.0.0-pre

panva · 2026-08-31T15:15:13Z

#65683

The JavaScript recursive watcher used on platforms without a native one (notably Linux) armed an fs.watch() handle and a stat() for every file in the tree, and answered every event by stat()ing and re-reading the whole directory it happened in. A 13k-entry tree cost 13.5k inotify watches, ~150 ms and ~50 MB to set up, and appending to one file in a 3900-entry directory cost ~9 ms of CPU per event. A file replaced by rename() (the usual editor save) also stopped being reported, since its watch stayed on the old inode. inotify reports changes to the entries of a watched directory, with their names, so on Linux watch each directory once (symbolic links keep their own watcher, as before), keep the set of known paths, and resolve an event with a single stat() of the named entry: unknown names are added and reported as 'rename', vanished ones are dropped and reported as 'rename', file changes are reported as 'change'. kqueue and event ports only report that a directory changed, so on the other platforms served by this fallback every file keeps its own watcher and a directory event rescans that directory, as before. unref() and ref() now reach the underlying handles. Signed-off-by: Shelley Vohr <shelley.vohr@gmail.com> PR-URL: #65486 Reviewed-By: Moshe Atlow <moshe@atlow.co.il>

codebytere · 2026-08-22T15:03:48Z

Makes the JavaScript recursive watcher (used where fs.watch() has no native recursive mode) arm one watcher per directory instead of one per file on Linux, and answer each event with one stat() instead of re-reading the directory.

Linux, this repository's test/ tree (13 500 entries, 896 directories):

	before	after
`fs.watch(test, { recursive: true })` setup	~150 ms, 13 501 handles, +52 MB RSS	~45 ms, 896 handles, +20 MB RSS
`benchmark/fs/bench-watch-recursive.js` (new), `test/fixtures`, 30 runs		+287 % ±4 %
CPU for 300 appends to one file in `test/parallel`	2 860 ms	11 ms
CPU for 100 create+unlink in `test/parallel`	2 890 ms	110 ms

The fallback armed an fs.watch() handle and ran a statSync() for every file in the tree, and handled every event by stat()ing and re-reading the whole directory it happened in. A file replaced by rename() (the usual editor save) also stopped being reported, because its watch stayed on the old inode, and watcher.ref()/unref() were no-ops on this path.

inotify reports changes to a watched directory's entries with the entry name, so on Linux the watcher now keeps one handle per directory (symbolic links keep their own, as before) plus the set of known paths, and resolves an event with a single stat() of the named entry: new names are reported as 'rename' and descended into if they are directories, vanished ones are dropped with their subtree and reported as 'rename', changes to known files are 'change'. kqueue and event ports only report that the directory itself changed, so on the other platforms this fallback serves (illumos, the BSDs, AIX) files keep a watcher each and a directory event rescans that directory, as today. Two event differences remain, both matching the native watchers: creating a file with content yields 'rename' then 'change', and a file keeps being reported after it is replaced by rename(). ref()/unref() now reach the handles.

Tests: all test-fs-watch-recursive-*, test-fs-watch-ignore-*, test-fs-promises-watch* and watch-mode tests pass in both modes (the per-file mode exercised on Linux by flipping the platform check; recursive ones 3/3 repeated runs); a new Linux-only test covers the per-directory handle count, rename-over reporting, events behind a symbolic link, removal of a watched root directory and root file, and ref()/unref().

Disclosure: the code, test, benchmark, measurements and this description were written by Claude Code, directed and reviewed by @codebytere.

nodejs-github-bot · 2026-08-22T15:03:54Z

Review requested:

@nodejs/performance

codecov · 2026-08-22T16:54:15Z

Codecov Report

❌ Patch coverage is 84.76821% with 23 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.14%. Comparing base (21f0f27) to head (7774d81).
⚠️ Report is 188 commits behind head on main.

Files with missing lines	Patch %	Lines
lib/internal/fs/recursive_watch.js	84.76%	22 Missing and 1 partial ⚠️

Additional details and impacted files

@@ Coverage Diff @@## main #65486 +/- ##
==========================================
+ Coverage 90.12% 90.14% +0.02% 
==========================================
Files 752 751 -1 Lines 252315 253482 +1167 Branches 47444 47747 +303 ==========================================
+ Hits 227395 228501 +1106 - Misses 16217 16252 +35 - Partials 8703 8729 +26

Files with missing lines	Coverage Δ
lib/internal/fs/recursive_watch.js	`86.47% <84.76%> (-0.74%)`	⬇️

... and 86 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

nodejs-github-bot · 2026-08-23T08:43:55Z

CI: https://ci.nodejs.org/job/node-test-pull-request/76280/

The JavaScript recursive watcher used on platforms without a native one (notably Linux) armed an fs.watch() handle and a stat() for every file in the tree, and answered every event by stat()ing and re-reading the whole directory it happened in. A 13k-entry tree cost 13.5k inotify watches, ~150 ms and ~50 MB to set up, and appending to one file in a 3900-entry directory cost ~9 ms of CPU per event. A file replaced by rename() (the usual editor save) also stopped being reported, since its watch stayed on the old inode. inotify reports changes to the entries of a watched directory, with their names, so on Linux watch each directory once (symbolic links keep their own watcher, as before), keep the set of known paths, and resolve an event with a single stat() of the named entry: unknown names are added and reported as 'rename', vanished ones are dropped and reported as 'rename', file changes are reported as 'change'. kqueue and event ports only report that a directory changed, so on the other platforms served by this fallback every file keeps its own watcher and a directory event rescans that directory, as before. unref() and ref() now reach the underlying handles. Signed-off-by: Shelley Vohr <shelley.vohr@gmail.com>

codebytere · 2026-08-23T20:44:56Z

@MoLow mind taking another look? the non-Linux path changed since your review

nodejs-github-bot · 2026-08-30T15:51:22Z

CI: https://ci.nodejs.org/job/node-test-pull-request/76735/

nodejs-github-bot · 2026-08-31T13:07:42Z

Landed in 2ec0f9a

aduh95 · 2026-08-31T15:04:09Z

CI on main is failing since this change:

=== release test-fs-watch-enoent === Path: parallel/test-fs-watch-enoent
node:internal/assert/utils:146
throw error;
^
AssertionError [ERR_ASSERTION]: Missing expected exception.
at Object.<anonymous> (/Users/duhamean/Documents/nodejs/node/test/parallel/test-fs-watch-enoent.js:112:12)
at Module._compile (node:internal/modules/cjs/loader:1937:14)
at Object..js (node:internal/modules/cjs/loader:2077:10)
at Module.load (node:internal/modules/cjs/loader:1659:32)
at Module._load (node:internal/modules/cjs/loader:1451:12)
at wrapModuleLoad (node:internal/modules/cjs/loader:261:19)
at Module.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:154:5)
at node:internal/main/run_main_module:33:47 {
generatedMessage: false,
code: 'ERR_ASSERTION',
actual: undefined,
expected: [Function (anonymous)],
operator: 'throws',
diff: 'simple'
}
Node.js v27.0.0-pre

panva · 2026-08-31T15:15:13Z

#65683

The JavaScript recursive watcher used on platforms without a native one (notably Linux) armed an fs.watch() handle and a stat() for every file in the tree, and answered every event by stat()ing and re-reading the whole directory it happened in. A 13k-entry tree cost 13.5k inotify watches, ~150 ms and ~50 MB to set up, and appending to one file in a 3900-entry directory cost ~9 ms of CPU per event. A file replaced by rename() (the usual editor save) also stopped being reported, since its watch stayed on the old inode. inotify reports changes to the entries of a watched directory, with their names, so on Linux watch each directory once (symbolic links keep their own watcher, as before), keep the set of known paths, and resolve an event with a single stat() of the named entry: unknown names are added and reported as 'rename', vanished ones are dropped and reported as 'rename', file changes are reported as 'change'. kqueue and event ports only report that a directory changed, so on the other platforms served by this fallback every file keeps its own watcher and a directory event rescans that directory, as before. unref() and ref() now reach the underlying handles. Signed-off-by: Shelley Vohr <shelley.vohr@gmail.com> PR-URL: #65486 Reviewed-By: Moshe Atlow <moshe@atlow.co.il>

nodejs-github-bot added fs Issues and PRs related to file-system APIs and the fs module. needs-ci PRs that need a full CI run. labels Aug 22, 2026

codebytere requested review from Qard, mcollina and trivikr August 22, 2026 16:56

codebytere force-pushed the perf/fs-watch-recursive-linux-dir-watches branch from 6a5d660 to bd967d5Compare August 22, 2026 16:57

MoLow approved these changes Aug 23, 2026
View reviewed changes

codebytere force-pushed the perf/fs-watch-recursive-linux-dir-watches branch from bd967d5 to 7774d81Compare August 23, 2026 20:44

codebytere requested a review from MoLow August 25, 2026 08:13

MoLow approved these changes Aug 25, 2026
View reviewed changes

codebytere added the request-ci Add this label to start a Jenkins CI on a PR. label Aug 25, 2026

github-actionsBot removed the request-ci Add this label to start a Jenkins CI on a PR. label Aug 25, 2026

This comment was marked as outdated.
Sign in to view

codebytere added commit-queue PRs queued for automated landing through the Commit Queue. and removed needs-ci PRs that need a full CI run. labels Aug 31, 2026

nodejs-github-bot merged commit 2ec0f9a into nodejs:mainAug 31, 2026
72 checks passed

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

panva mentioned this pull request Aug 31, 2026
test: fix recursive fs.watch error fixture #65683
Closed

panva added the needs-ci PRs that need a full CI run. label Aug 31, 2026