Watchit
A sensible wrapper around fs.watch.
Written in CoffeeScript by the author of CoffeeScript: Accelerated JavaScript Development.
Usage
Install with npm. Then:
watchit = require('watchit');
watchit('target', options, callback);
where target
is the path to a file or directory, options
is a hash (see
below) and callback
is a function of the form
callback = function(event) { ... }
Both options
and callback
are optional.
watchit
also returns an EventEmitter
that emits the same events received
by callback
(more on that below). You can also call close()
on the emitter
to "unwatch" the target.
Options
watchit
is designed to work as a drop-in replacement for fs.watch
by
default, but in most cases you'll want to modify one or more of these options:
retain
(default: false) means that if something is later created at the same location as the target, the new entity will be watched.debounce
(default: false) means that changes that occur within 1 second of each other will be treated as a single change. This also allows "echo" events that occur under OS X to be ignored.include
(default: false) means that if the target is a directory, files contained in that directory will be treated like targets. (Otherwise, directory events will be forwarded directly fromfs.watch
.)recurse
(default: false) means that if the target is a directory, all of its subdirectories will also be counted as targets.persistent
is identical tofs.watch
'spersistent
option. If disabled, the process may exit while files are still being watched.
The emitter
The emitter returned by watchit
emits events in two ways:
- fs.watch-style: Bind a callback that takes the event name, filename,
and possibly other args with
emitter.on('all', callback)
. (Note: Withfs.watch
, this would beemitter.on 'change'
. Unfortunately,'change'
is also one of the two event names thatfs.watch
can return; to avoid confusion, Watchit uses the'all'
convention from Backbone.js.) - By event: Bind a callback that takes the filename, and possibly other
args, to a specific event:
'change'
,'create'
or'unlink'
. For example,emitter.on('change', callback)
.
fs.watch
Major differences vs. With Watchit:
- Duplicate changes (those that do not modify
mtime
) are ignored; this works around a notablefs.watch
bug under OS X. - After a file is renamed, it will no longer emit events. That is, Watchit
does not "follow" moved files the way
fs.watch
does. (Why? Because this behavior is inconsistent across OSes, and there's currently no way to determine the new location of the file.) - Emitted events differ (see below)
Events
'success'
/'failure'
: When a target is first watched, a'success'
event will be emitted if it already exists, andfailure
if it does not exist. ('failure'
is not emitted if theretain
option is set.)'change'
: Same asfs.watch
's'change'
.'create'
: Emitted when the target is created (or, ininclude
mode, when a child of the target directory is created).'unlink'
: Emitted when the target no longer exists at its current location (or, ininclude
mode, when a child of the target directory no long exists).
Note that create
and unlink
are finer-grained versions of fs.watch
's
rename
.
A word of warning
The Node team is, as of version 0.6.2, still working the kinks out of
fs.watch
. Watchit should be considered a good alternative to dealing with
fs.watch
yourself, but you may nonetheless encounter some quirks--and even
fatal errors. Check the issue tracker:
https://github.com/joyent/node/issues/search?q=fs.watch&state=open
In addition, watchit itself is a new project, and the test suites are incomplete. If you run into any problems that you can replicate in a small test case, please don't hesitate to report them.
Contributing
- Install dependencies with
npm install
- Make changes in
src
- Build with
cake build
- Add tests under
test
- Run tests via
npm test