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.
gaze
![Build status](https://ci.appveyor.com/api/projects/status/vtx65w9eg511tgo4)
A globbing fs.watch wrapper built from the best parts of other fine watch libs.
Compatible with Node.js 4.x/0.12/0.10, Windows, OSX and Linux.
![gaze](http://dontkry.com/images/repos/gaze.png)
![NPM](https://nodei.co/npm/gaze.png?downloads=true)
Usage
Install the module with: npm install gaze
or place into your package.json
and run npm install
.
var gaze = require('gaze');
gaze('**/*.js', function(err, watcher) {
var watched = this.watched();
this.on('changed', function(filepath) {
console.log(filepath + ' was changed');
});
this.on('added', function(filepath) {
console.log(filepath + ' was added');
});
this.on('deleted', function(filepath) {
console.log(filepath + ' was deleted');
});
this.on('all', function(event, filepath) {
console.log(filepath + ' was ' + event);
});
var files = this.relative();
});
gaze(['stylesheets/*.css', 'images/**/*.png'], function() {
this.add(['js/*.js']);
});
Alternate Interface
var Gaze = require('gaze').Gaze;
var gaze = new Gaze('**/*');
gaze.on('ready', function(watcher) { });
gaze.on('all', function(event, filepath) { });
Errors
gaze('**/*', function(error, watcher) {
if (error) {
}
});
var gaze = new Gaze();
gaze.on('error', function(error) {
});
gaze.add('**/*');
Minimatch / Glob
See isaacs's minimatch for more
information on glob patterns.
Documentation
gaze([patterns, options, callback])
patterns
{String|Array} File patterns to be matchedoptions
{Object}callback
{Function}
err
{Error | null}watcher
{Object} Instance of the Gaze watcher
Class: gaze.Gaze
Create a Gaze object by instancing 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.watchFiledebounceDelay
{integer} Delay for events called in succession for the same
file/event in millisecondsmode
{string} Force the watch mode. Either 'auto'
(default), 'watch'
(force native events), or 'poll'
(force stat polling).cwd
{string} The current working directory to base file patterns from. Default is process.cwd()
.
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.
Similar Projects
Other great watch libraries to try are:
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
- 1.1.1 - Prevent fs.watch errors from escaping error handler (@rosen-vladimirov). Fix _addToWatched without path.sep (@wyicwx).
- 1.1.0 - Update to
globule@1.0.0
with minimatch >= 3.0.0
. - 1.0.0 - Revert back to 0.5.2. Drop support for Node.js v0.8. Fix for
maxListeners
. Update globule to 0.2.0
. - 0.6.4 - Catch and emit error from readdir (@oconnore). Fix for 0 maxListeners. Use graceful-fs to avoid EMFILE errors in other places fs is used. Better method to determine if pathwatcher was built. Fix keeping process alive too much, only init pathwatcher if a file is being watched. Set min required to Windows Vista when building on Windows (@pvolok).
- 0.6.3 - Add support for node v0.11
- 0.6.2 - Fix argument error with watched(). Fix for erroneous added events on folders. Ignore msvs build error 4244.
- 0.6.1 - Fix for absolute paths.
- 0.6.0 - Uses native OS events (fork of pathwatcher) but can fall back to stat polling. Everything is async to avoid blocking, including
relative()
and watched()
. Better error handling. Update to globule@0.2.0. No longer watches cwd
by default. Added mode
option. Better EMFILE
message. Avoids ENOENT
errors with symlinks. All constructor arguments are optional. - 0.5.2 - Fix for ENOENT error with non-existent symlinks [BACKPORTED].
- 0.5.1 - Use setImmediate (process.nextTick for node v0.8) to defer ready/nomatch events (@amasad).
- 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) 2015 Kyle Robinson Young
Licensed under the MIT license.