A file system watcher.

What's this?

package:watcher monitors changes to contents of directories and sends notifications when files have been added, removed, or modified.

What you can rely on

Events converge on the state of the filesystem. If you apply them to a model of the watched paths then, once changes stop, your model matches what is on disk. That is the guarantee, and it is what the tests check: they apply random series of file operations and require the state rebuilt from events to match the state on disk.

There is deliberately no guarantee of one event per change. Platform notifications are batched, and arrive in an order that often does not determine what happened, so watchers resolve them by reading the paths involved. A path that is deleted and written again between reads is reported as a single modification; a path that is created and deleted may produce no event at all.

So, use an event to learn that a path is worth looking at, and read the path to learn what it now contains. Code that counts events, pairs them up, or waits for a particular event to arrive is relying on something this package does not promise, and will fail intermittently on some platforms.