From d6d30234c7957d07c2cf2548466d19f9cf215d32 Mon Sep 17 00:00:00 2001 From: AyushAnand-28 Date: Mon, 1 Dec 2025 00:32:22 +0530 Subject: [PATCH] doc: improve fs.watch documentation for rapid file operations Refs: https://github.com/nodejs/node/issues/60859 Add a new section to the fs.watch documentation explaining that rapid file operations may cause missed or coalesced events due to underlying OS file watching mechanisms. Provide recommendations for applications requiring reliable event detection, including using third-party libraries like chokidar, fs.watchFile for critical files, or implementing debouncing logic. --- doc/api/fs.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/doc/api/fs.md b/doc/api/fs.md index c0c88a3abb90c1..2a52aca1f36c81 100644 --- a/doc/api/fs.md +++ b/doc/api/fs.md @@ -4842,6 +4842,29 @@ implemented by monitoring changes in a directory versus specific files. This allows substitution of a file and fs reporting changes on the new file with the same filename. +##### Event Reliability with Rapid Operations + + + +When files are created, modified, or deleted in rapid succession, `fs.watch` +may miss events or coalesce multiple events into one. This is due to the +underlying operating system file watching mechanisms (such as `inotify` on +Linux, `FSEvents` on macOS, and `ReadDirectoryChangesW` on Windows) which +may debounce or batch events to reduce system overhead. + +For applications requiring reliable detection of all file system events, +especially during rapid operations, consider using: + +* **Third-party libraries** like [`chokidar`][] which provide more robust + event handling and cross-platform consistency. +* **`fs.watchFile()`** for individual files where guaranteed event detection + is critical, though this uses polling and is less efficient. +* **Debouncing logic** in your event handlers to handle potential duplicate + or coalesced events. + +[`chokidar`]: https://github.com/paulmillr/chokidar + + ##### Availability