1
Fork 0
If it works, why use something else? https://conduitry.dev/cheap-watch
Go to file
Conduitry 223ab2758a v0.2.0 2018-04-02 19:50:36 -04:00
.eslintrc.yaml initial copy of code 2018-04-02 16:33:41 -04:00
.gitignore initial copy of code 2018-04-02 16:33:41 -04:00
.prettierrc initial copy of code 2018-04-02 16:33:41 -04:00
CHANGELOG.md v0.2.0 2018-04-02 19:50:36 -04:00
CheapWatch.js various improvements: 2018-04-02 19:26:40 -04:00
LICENSE docs 2018-04-02 17:17:52 -04:00
README.md update docs 2018-04-02 19:47:44 -04:00
package.json v0.2.0 2018-04-02 19:50:36 -04:00
rollup.config.js initial copy of code 2018-04-02 16:33:41 -04:00

README.md

Cheap Watch: If it works, why use something else?

npm version

Cheap Watch is a small, simple, dependency-free, cross-platform file system watcher for Node.js 8+.

Constructor

new CheapWatch({ dir, filter, watch = true, debounce = 10 })

  • dir - The directory whose contents to watch. It's recommended, though not required, for this to be an absolute path, say one returned by path.resolve.
  • filter({ path, stats }) - (optional) A function to decide whether a given file or directory should be watched. It's passed an object containing the file or directory's relative path and its stats. It should return true or false (or a Promise resolving to one of those). Returning false for a directory means that none of its contents will be watched.
  • watch - (optional) Whether to actually watch the directory for changes. Defaults to true. If false, you can retrieve all of the files and directories within a given directory along with their Stats but changes will not actually be monitored.
  • debounce - (optional) Length of timeout in milliseconds to use to debounce incoming events from fs.watch. Defaults to 10. Multiple events are often emitted for a single change, and events can also be emitted before fs.stat reports the changes. Cheap Watch will wait until debounce milliseconds have passed since the last fs.watch event for a file or directory before reporting it. The default of 10ms Works On My Machine.

Methods

cheapWatch.init()

Initialize the watcher, traverse the directory to find the initial files and directories, and set up watchers to look for changes.

This returns a Promise that resolves once the initial contents of the directory have been traversed and all of the watchers have been set up.

cheapWatch.close()

Close all FSWatcher instances, and stop watching for file changes.

Properties

cheapWatch.files

A Map of the watched files and directories. Each key is a relative path from the CheapWatch's dir, and each value is a Stats object for the file or directory. This is kept up to date as files are changed on disk.

You can use stats.isFile() and stats.isDirectory() to determine whether something is a file or a directory.

Events

CheapWatch is a subclass of EventEmitter, and emits two events to report a new, updated, or deleted file or directory.

+ { path, stats }

A + event is emitted with an object containing a path string and a stats object whenever a watched file or directory is created or updated.

- { path, stats }

A - event is emitted with an object containing a path string and a stats object whenever a watched file or directory is deleted. stats will be the most recent Stats collected for the file or directory before it was deleted.

Usage

import CheapWatch from 'cheap-watch';

const watch = new CheapWatch({ dir, /* ... */ });

await watch.init();

for (const [path, stats] of watch.files) {
	/* ... */
}

watch.on('+', ({ path, stats }) => /* ... */ );
watch.on('-', ({ path, stats }) => /* ... */);

License

Copyright (c) 2018 Conduitry