conduitry/cheap-watch

If it works, why use something else? // Mirror of https://git.chor.date/Conduitry/cheap-watch

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

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 initial Stats but changes will not 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. So we will wait until debounce milliseconds have passed since the last fs.watch event for a file or directory before handling it. The default of 10ms Works On My Machine.

Methods

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.

close()

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

Properties

paths

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. Paths are always separated by forward slashes, regardless of platform. This Map 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

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

+ { path, stats, isNew }

A + event is emitted whenever a watched file or directory is created or updated. It's emitted with an object containing a path string, a stats object, and an isNew boolean which will be true for newly created files and directories and false for updated ones.

- { path, stats }

A - event is emitted whenever a watched file or directory is deleted. It's emitted with an object containing a path string and a stats object. 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.paths) {
	/* ... */
}

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

License

MIT

cheap-watch's Issues

"+" event not firing on directory when modifying, adding or removing a file inside given directory

the problem

when watching a directory, if a file changes, the directory it is placed within also gets an update, except for the given directory

to reproduce

make a testing directory, write

const CheapWatch = require("cheap-watch") // or a local import
const { join } = require("path")

const watcher = new CheapWatch({ dir: join(__dirname, "testing") })
watcher.init()

watcher.on("+", ({ path, stats }) => stats.isDirectory() && console.log(path))

into any javascript file, run it and then add files to the testing directory. nothing should happen, but if you add a directory into the testing directory and then add files to that directory the name of the new directory should be console-logged

expectation

i would expect cheap-watch to fire an event on the parent directory too, if a file in it would be changed, added or removed

system and version

i am running on Windows 10, 64bit with node version 16.3.0

fsevents support

Ahoy. It's been mentioned in a few places (most recently rollup/rollup#2988) that one of the primary benefits of chokidar over cheap-watch is fsevents support, which is natively available on MacOS. The Rollup team is exploring which watching library would be most beneficial to include by default, and while this is by no means a competition, during weighting of directions the lack of fsevents support in cheap-watch did get raised.

I'm curious if supporting fsevents is something you'd be interested in for this lib.

Feedback on experience

Hi, Conduitry!

I'd like to ask how your experience with cheap-watch has been about the possible problems and inconsistencies with the original Node.js implementation to watch files, that others libraries (like yours, facebook watchman, jung, sane, gaze, chokidar, watch, pathwatcher, watchr, etc) are trying to solve.

Many people need to know your library.

Has cheap-watch worked well, including on multiple operational systems?

I'm playing a little with cheap-watch and my main concern right now is about the possibility to inform multiple directories and also final files, instead of directories only.

Thanks for your attention!

ESM: TypeError: Class extends value [object Module] is not a constructor or null error

class CheapWatch extends EventEmitter {
                         ^

TypeError: Class extends value [object Module] is not a constructor or null

This issue was addressed in the comments of #4. I'm getting this when importing cheap-watch from a "type": "module" project.

Type 'typeof EventEmitter' is not a constructor function type.

When running tsc in a project folder with cheap-watch

You are an asshole

Thank you for closing my issue which had valid issue and valid criticism.

Bye!