.. | ||
lib | ||
LICENSE-MIT | ||
package.json | ||
README.md |
gaze
A globbing fs.watch
wrapper built from the best parts of other fine watch libs.
Compatible with Node.js >= 4.x, Windows, macOS, 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
var watched = 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
var files = 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(error, watcher) {
if (error) {
// Handle error if it occurred while starting up
}
});
// Or with the alternative interface
var gaze = new Gaze();
gaze.on('error', function(error) {
// Handle error here
});
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 theGaze
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 tofs.watchFile
debounceDelay
{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 isprocess.cwd()
.
Events
ready(watcher)
When files have been globbed and watching has begun.all(event, filepath)
When anadded
,changed
,renamed
, ordeleted
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 forEventEmitter.emit
.added
|changed
|renamed
|deleted
events will also trigger theall
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.3 - Fix for Node 10 support (@aredridel). Officially dropping support for Node < 4.
- 1.1.2 - Prevent more
ENOENT
errors from escaping (@alexgorbatchev). - 1.1.1 - Prevent
fs.watch
errors from escaping error handler (@rosen-vladimirov). Fix_addToWatched
withoutpath.sep
(@wyicwx). - 1.1.0 - Update to
globule@1.0.0
withminimatch >= 3.0.0
. - 1.0.0 - Revert back to 0.5.2. Drop support for Node.js v0.8. Fix for
maxListeners
. Updateglobule
to0.2.0
. - 0.6.4 - Catch and emit
error
fromreaddir
(@oconnore). Fix for0 maxListeners
. Usegraceful-fs
to avoidEMFILE
errors in other placesfs
is used. Better method to determine ifpathwatcher
was built. Fix keeping process alive too much, only initpathwatcher
if a file is being watched. Set min required to Windows Vista when building on Windows (@pvolok). - 0.6.3 - Add support for Node.js v0.11
- 0.6.2 - Fix argument error with
watched()
. Fix for erroneousadded
events on folders. Ignoremsvs
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, includingrelative()
andwatched()
. Better error handling. Update toglobule@0.2.0
. No longer watchescwd
by default. Addedmode
option. BetterEMFILE
message. AvoidsENOENT
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.js v0.8) to deferready
/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.js v0.6. Use
globule
for file matching. Avoid Node.js v0.10path.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 incorrectadded
events (@groner). - 0.3.3 - Fix for multiple patterns with negate.
- 0.3.2 - Emit
end
beforeremoveAllListeners
. - 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
onclose
. - 0.2.1 - Fix issue with invalid
added
events in current working dir. - 0.2.0 - Support and mark folders with
path.sep
. AddforceWatchMethod
option. Supportrenamed
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) 2018 Kyle Robinson Young
Licensed under the MIT license.