gaze

What is gaze?

The 'gaze' npm package is a file watcher that uses native OS events to notify you of changes to files and directories. It is useful for tasks such as automatically reloading a server, rebuilding assets, or running tests when files change.

What are gaze's main functionalities?

Watch Files

This feature allows you to watch for changes in JavaScript files in the current directory. When a change is detected, it logs the event type and the file path.

const gaze = require('gaze');
gaze('*.js', function(err, watcher) {
  if (err) throw err;
  console.log('Watching files...');
  this.on('all', function(event, filepath) {
    console.log(event + ': ' + filepath);
  });
});

Watch Directories

This feature allows you to watch for changes in JavaScript files within the 'lib' directory and its subdirectories. It logs the event type and the file path when a change is detected.

const gaze = require('gaze');
gaze('lib/**/*.js', function(err, watcher) {
  if (err) throw err;
  console.log('Watching directories...');
  this.on('all', function(event, filepath) {
    console.log(event + ': ' + filepath);
  });
});

Get Watched Files

This feature allows you to retrieve a list of files currently being watched. It logs the list of watched files to the console.

const gaze = require('gaze');
gaze('*.js', function(err, watcher) {
  if (err) throw err;
  console.log('Watching files...');
  console.log(this.watched());
});

Other packages similar to gaze

chokidar

Chokidar is a highly efficient and reliable file watcher that uses native OS events. It offers more features and better performance compared to 'gaze', including support for recursive watching, symlink following, and more robust handling of edge cases.

watch

The 'watch' package is a simple file watcher that uses polling to detect changes. It is less efficient than 'gaze' and 'chokidar' but can be useful for simpler use cases where native OS events are not required.

node-watch

Node-watch is another file watcher that uses native OS events. It is similar to 'gaze' but offers a simpler API and fewer features. It is suitable for basic file watching tasks.

README

gaze

A globbing fs.watch wrapper built from the best parts of other fine watch libs.
Compatible with Node.js 0.10/0.8, Windows, OSX and Linux.

Usage

Install the module with: npm install gaze or place into your package.json and run npm install.

var gaze = require('gaze');

// Watch all .js files/dirs in process.cwd()
gaze('**/*.js', function(err, watcher) {
  // Files have all started watching
  // watcher === this

  // Get all watched files
  console.log(this.watched());

  // On file changed
  this.on('changed', function(filepath) {
    console.log(filepath + ' was changed');
  });

  // On file added
  this.on('added', function(filepath) {
    console.log(filepath + ' was added');
  });

  // On file deleted
  this.on('deleted', function(filepath) {
    console.log(filepath + ' was deleted');
  });

  // On changed/added/deleted
  this.on('all', function(event, filepath) {
    console.log(filepath + ' was ' + event);
  });

  // Get watched files with relative paths
  console.log(this.relative());
});

// Also accepts an array of patterns
gaze(['stylesheets/*.css', 'images/**/*.png'], function() {
  // Add more patterns later to be watched
  this.add(['js/*.js']);
});

Alternate Interface

var Gaze = require('gaze').Gaze;

var gaze = new Gaze('**/*');

// Files have all started watching
gaze.on('ready', function(watcher) { });

// A file has been added/changed/deleted has occurred
gaze.on('all', function(event, filepath) { });

Errors

gaze('**/*', function() {
  this.on('error', function(err) {
    // Handle error here
  });
});

Minimatch / Glob

See isaacs's minimatch for more information on glob patterns.

Documentation

gaze(patterns, [options], callback)

• patterns {String|Array} File patterns to be matched
• options {Object}
• callback {Function}
  • err {Error | null}
  • watcher {Object} Instance of the Gaze watcher

Class: gaze.Gaze

Create a Gaze object by instanting the gaze.Gaze class.

var Gaze = require('gaze').Gaze;
var gaze = new Gaze(pattern, options, callback);

Properties

• options The options object passed in.
  • interval {integer} Interval to pass to fs.watchFile
  • debounceDelay {integer} Delay for events called in succession for the same file/event

Events

• ready(watcher) When files have been globbed and watching has begun.
• all(event, filepath) When an added, changed or deleted event occurs.
• added(filepath) When a file has been added to a watch directory.
• changed(filepath) When a file has been changed.
• deleted(filepath) When a file has been deleted.
• renamed(newPath, oldPath) When a file has been renamed.
• end() When the watcher is closed and watches have been removed.
• error(err) When an error occurs.
• nomatch When no files have been matched.

Methods

• emit(event, [...]) Wrapper for the EventEmitter.emit. added|changed|deleted events will also trigger the all event.
• close() Unwatch all files and reset the watch instance.
• add(patterns, callback) Adds file(s) patterns to be watched.
• remove(filepath) removes a file or directory from being watched. Does not recurse directories.
• watched() Returns the currently watched files.
• relative([dir, unixify]) Returns the currently watched files with relative paths.
  • dir {string} Only return relative files for this directory.
  • unixify {boolean} Return paths with / instead of \\ if on Windows.

FAQs

Why Another fs.watch Wrapper?

I liked parts of other fs.watch wrappers but none had all the features I needed. This lib combines the features I needed from other fine watch libs: Speedy data behavior from paulmillr's chokidar, API interface from mikeal's watch and file globbing using isaacs's glob which is also used by cowboy's Grunt.

How do I fix the error EMFILE: Too many opened files.?

This is because of your system's max opened file limit. For OSX the default is very low (256). Increase your limit temporarily with ulimit -n 10480, the number being the new max limit.

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using grunt.

Release History

• 0.5.0 - Process is now kept alive while watching files. Emits a nomatch event when no files are matching.
• 0.4.3 - Track file additions in newly created folders (@brett-shwom).
• 0.4.2 - Fix .remove() method to remove a single file in a directory (@kaelzhang). Fixing Cannot call method 'call' of undefined (@krasimir). Track new file additions within folders (@brett-shwom).
• 0.4.1 - Fix watchDir not respecting close in race condition (@chrisirhc).
• 0.4.0 - Drop support for node v0.6. Use globule for file matching. Avoid node v0.10 path.resolve/join errors. Register new files when added to non-existent folder. Multiple instances can now poll the same files (@jpommerening).
• 0.3.4 - Code clean up. Fix path must be strings errors (@groner). Fix incorrect added events (@groner).
• 0.3.3 - Fix for multiple patterns with negate.
• 0.3.2 - Emit end before removeAllListeners.
• 0.3.1 - Fix added events within subfolder patterns.
• 0.3.0 - Handle safewrite events, forceWatchMethod option removed, bug fixes and watch optimizations (@rgaskill).
• 0.2.2 - Fix issue where subsequent add calls dont get watched (@samcday). removeAllListeners on close.
• 0.2.1 - Fix issue with invalid added events in current working dir.
• 0.2.0 - Support and mark folders with path.sep. Add forceWatchMethod option. Support renamed events.
• 0.1.6 - Recognize the cwd option properly
• 0.1.5 - Catch too many open file errors
• 0.1.4 - Really fix the race condition with 2 watches
• 0.1.3 - Fix race condition with 2 watches
• 0.1.2 - Read triggering changed event fix
• 0.1.1 - Minor fixes
• 0.1.0 - Initial release

License

Copyright (c) 2013 Kyle Robinson Young
Licensed under the MIT license.