A sensible wrapper around Node's fs.watch
CoffeeScript JavaScript
Pull request Compare This branch is 3 commits behind TrevorBurnham:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
lib
src
test
.gitignore
Cakefile
README.mdown
package.json
test.coffee

README.mdown

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 from fs.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 to fs.watch's persistent 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:

  1. fs.watch-style: Bind a callback that takes the event name, filename, and possibly other args with emitter.on('all', callback). (Note: With fs.watch, this would be emitter.on 'change'. Unfortunately, 'change' is also one of the two event names that fs.watch can return; to avoid confusion, Watchit uses the 'all' convention from Backbone.js.)
  2. 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).

Major differences vs. fs.watch

With Watchit:

  1. Duplicate changes (those that do not modify mtime) are ignored; this works around a notable fs.watch bug under OS X.
  2. 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.)
  3. Emitted events differ (see below)

Events

  • 'success'/'failure': When a target is first watched, a 'success' event will be emitted if it already exists, and failure if it does not exist. ('failure' is not emitted if the retain option is set.)
  • 'change': Same as fs.watch's 'change'.
  • 'create': Emitted when the target is created (or, in include mode, when a child of the target directory is created).
  • 'unlink': Emitted when the target no longer exists at its current location (or, in include 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

Run tests via ./node_modules/.bin/mocha --compilers coffee:coffee-script --require test/common.js --colors --reporter spec.

License

http://trevorburnham.mit-license.org