Watch-util NPM

Versatile watcher lib and shell commands for watching files, running and restarting shell commands

Watch files, run and restart shell commands on changes.

Provides both API and shell commands with consistent options naming.

var watch = require("watch-util");

// with callback

var globs = ["**/*", "!node_modules/", "!test/", "test/test.js"];
var options = { events: ["create", "change"], combineEvents: false };
var w = new watch.Watcher(globs, options, function (filePath, event) {
	/* ... */
});
w.start();

// or listen to events

var w = new watch.Watcher(["**/*"]);
w.start();
w.on("create", function (filePath) { /* ... */ });
w.on("change", function (filePath) { /* ... */ });
w.on("delete", function (filePath) { /* ... */ });
w.on("all", function (filePath, event) { /* ... */ });

// or run cmd

var options = { waitDone: true, stdio: [null, "pipe", "pipe"] };
var w = watch.exec(["**/*.js"], options, "echo file %relFile is changed");
w.stdout.on("data", function (data) { /* ... */ });
w.stderr.on("data", function (data) { /* ... */ });

// or run server/daemon-like cmd

var options = { throttle: 1000, stdio: [null, "inherit", "inherit"] };
var w = watch.restart(["**/*", "!node_modules/"], options, "node server.js");

watch-exec -g '**/*.js, !node_modules/' --debounce 5000 -- echo changed files: %relFiles
watch-exec -g '**/*.js, !node_modules/' -C -- echo event=%event relFile=%relFile
watch-restart -g '**/*.js,!node_modules/' --check-md5 -- node server.js

Install:

npm install watch-util

API:

watch.Watcher - watch files and execute callback when files are changed or listen to events
watch.exec(globs, options, cmd) - execute cmd when files are changed
watch.restart(globs, options, cmd) - run and restart cmd when files are changed

Shell commands:

watch-exec - shell analog of watch.exec
watch-restart - shell analog of watch.restart

Features

Watch by globs, negate globs, apply globs sequentially
Compare MD5 of files
Compare mtime of files
Doesn't fire duplicate events
Handle 2-step save that is used in most of the popular editors
Execute cmd on changes
Pass file path, event, etc. to cmd
Execute cmd for each changed file in parallel
Execute cmd in queue
Restart cmd on changes
Debounce change events
Throttle cmd exec/restart
Kill processes reliably

watch.Watcher #

new watch.Watcher(globs, options, callback)
new watch.Watcher(globs, callback)
new watch.Watcher(globs)
new watch.Watcher(globs, options)

globs <Array> Glob patterns to watch, see Globs option
options <Object> debounce <integer> Callback and events will not fire until N ms will pass from the last event, default 50 throttle <integer> Call callback and fire events no more then once in N ms, default 0 reglob <integer> Interval to rerun glob to check for added directories and files, default 1000 events <Array> Call callback and fire events only for specified list of watch events, default ["create", "change", "delete"] combineEvents <boolean> Combine all files changes during the debounce into single event, default true checkMD5 <boolean> Check MD5 of files to prevent firing when content is not changed, default false checkMtime <boolean> Check modified time of files, used for 2-step save, default true deleteCheckInterval <integer> Interval to check if file is replaced, default 25 deleteCheckTimeout <integer> Delay to determine if file is replaced or deleted, default 100 debug Print debug information, default false
callback <Function>

Watch files by glob. Could be used without callback.

Doesn't start in constructor. Call watcher.start() to start watching files.

Note! Don't forget to call watcher.stop() in process.on("exit") or process.on(signal) to kill all running processes before exiting.

`globs` option #

To ignore specific pattern prefix it with '!'. To ignore directory with everything within it end pattern with '/' or '/**'.

Patterns are applied sequentially to allow for globs like:

	["**/*.js", "!test/", "test/test.js"]

For more info about glob syntax see: glob.

watcher.start(callback)

Start watching files. Callback is called after mathing files with glob and creating watchers.

Note! Changes may not be recognized rignt after the .start callback, fs.watch watchers start watching files with small delay.

watcher.stop(callback)

Stop all watchers and clear all timers.

watcher.stdout

Pass-through for running cmd stdout.

When options .stdio[1] is set to 'pipe' creates pass-through stream for the running commands. Stream doesn't end when cmd process exits.

watcher.stderr

Pass-through for running cmd stderr.

When options .stdio[2] is set to 'pipe' creates pass-through stream for the running commands. Stream doesn't end when cmd process exits.

Events: "create", "change", "delete"

file|files <string>|<Array> Relative path/paths of changed files

Is emitted when file/files are created, changed or deleted.

Is not emitted when option .combineEvents == true

Event: "all"

file|files <string>|<Array> Relative paths/paths of changed files
event "create", "change" or "delete"

Is emitted when file/files are created, changed or deleted.

Event: "error"

err

Is emitted when fs operations fail, most of the fails will not prevent watcher from working.

Note! Add handler to this event or it will be thrown instead.

Event: "start"

Is called after .start() is finished.

Event: "stop"

Is called after .stop() is finished.

watch.exec(globs, options, cmd) #

Run cmd every time files are changed. Creates watchers immediately.

watch.exec(globs, options, cmd)
watch.exec(globs, cmd)

globs <Array> Glob patterns to watch, see Globs option
options <Object> All new watch.Watcher options waitDone <boolean> Wait until cmd exit until executing again, default true parallelLimit <boolean> Number of parallel running cmds when .combineEvents == false, default 8 restartOnError <boolean> Restart cmd if it crashed or exited with non 0 code, default false shell <boolean>|<string> Use default shell to run cmd, when is string specifies custom shell, default true stdio <array, default [null, "ignore", "ignore"] * kill <Object> Options for kill(), see kill-with-style
cmd <string> Command to run on changes
Returns <watch.Watcher> with additional events

When option .waitDone == true all changes will be placed into queue, if .combineEvents == false uses separate queues per file.

Changes in queue are optimized, that way if there are multiple changes for the file between runs, cmd will be executed only once.

When options .waitDone == false current running cmd will be killed and run again, if .combineEvents == false kills/runs only cmd that is processing the same file that is changed.

When .stop() is called all running processes will be killed. Calllback is called after all processes are killed.

Note! Don't forget to call watcher.stop() in process.on("exit") or process.on(signal) to kill all running processes before exiting.

cmd could contain variables that will be replaced with changed file names, events, etc.

cmd interpolation variables:

%relFiles Relative changed files paths
%files Absolute changed files paths
%cwd Dir to resolve relative paths

cmd interpolation variables with -C, --no-combine-events:

%relFile Relative changed file path
%file Absolute changed file path
%relDir Relative dir containing changed file
%dir Absolute dir containing changed file
%cwd Dir to resolve relative paths
%event File event: create, change or delete

Event: "exec"

cmd <string> Interpolated command

Is fired when cmd is run.

Event: "exit"

cmd <string> Interpolated command

Is fired when cmd is exited with any code.

Event: "crash"

cmd <string> Interpolated command

Is fired when cmd is exited with code other then 0.

Event: "kill"

cmd <string> Interpolated command

Is fired when cmd is killed.

watch.restart(globs, options, cmd) #

watch.restart(globs, options, cmd)
watch.restart(globs, cmd)

Run cmd and restart every time files are changed. Creates watchers and runs cmd immediately.

globs <Array> Glob patterns to watch, see Globs option
options <Object> All new watch.Watcher options restartOnError <boolean> Restart cmd if it crashed or exited with non 0 code, default true restartOnSuccess <boolean> Restart cmd is it exited with 0 code, default true shell <boolean>|<string> Use default shell to run cmd, when is string specifies custom shell, default true stdio <array, Parameters for child stdio in fs.spawn, default [null, "ignore", "ignore"] kill <Object> Options for kill(), see kill-with-style
cmd <string> Command to run and restart on changes
Returns <watch.Watcher> with additional events

When .stop() is called all running processes will be killed. Calllback is called after all processes are killed.

Note! Don't forget to call watcher.stop() in process.on("exit") or process.on(signal) to kill all running processes before exiting.

Event: "exec"

cmd <string>

Is fired when cmd is run.

Event: "exit"

cmd <string>

Is fired when cmd is exited with any code.

Event: "crash"

cmd <string>

Is fired when cmd is exited with code other then 0.

Event: "kill"

cmd <string>

Is fired when cmd is killed.

Event: "restart"

cmd <string>

Is fired when cmd is restarted.

watch-exec #

Run <shell cmd> every time files are changed.

If -C, --no-combine-events cmd will be executed for each file in parallel, debounce and throttle will be used per file.

Usage:

watch-exec --glob <globs> [options] -- <shell cmd>

Examples:

watch-exec -g '*.js,test/*' -- './node_modules/.bin/mocha --colors test/test.js'
watch-exec -g '**/*.js, !node_modules/' --debounce 5000 -- echo changed files: %relFiles
watch-exec -g '**/*.js, !node_modules/' -C -- echo event=%event relFile=%relFile

Options:

-g, --globs <patterns> Glob patterns to watch, separated by comma, to ignore pattern start it with '!'
--events <events> Exec only for specified events, separated by comma, possible values: create, change, delete
-d, --debounce <ms> Exec cmd only after no events for N ms, default 50
-t, --throttle <ms> Exec cmd no more then once in N ms, default 0
-C, --no-combine-events Don't combine all events during debounce into single call
--run-on-start" Run after starting the command, before any change events
--reglob <ms> Glob files every N ms to track added files/dirs, default 1000
--check-md5 Check md5 checksum of files and fire events only if checksum is changed
--no-check-mtime Don't check mtime of files and fire events only if mtime is changed
--parallel-limit <n> Max number of parallel running cmds
-w, --wait-done Don't kill cmd on event, queue another run after it's done
--restart-on-error Restart cmd if cmd crashed or exited with non 0 code
--shell <shell cmd> Custom shell to use for running cmd
--no-shell Run directly without shell
--kill-signal <signals> Signal to send to child when process.kill(pid, signal), separated by comma
--kill-timeout <ms> After which return with error
--kill-retry-interval <intervals> Intervals between sending of kill signal, separated by comma
--kill-retry-count <n> Number of retries
--kill-check-interval <ms> Interval between checks if process is dead
--kill-use-pgid Use PGID to get all children on mac/linux
--kill-children-immediately Kill children immediately, don't wait for parent to die
--silent No output from watcher and running cmd
-v, --verbose Log when files are changed and cmd is executed
-V, --version Output version

watch-restart #

Run <shell cmd> and restart every time files are changed.

Usage:

watch-restart --glob <globs> [options] -- <shell cmd>

Examples:

watch-restart -g '**/*.js,!node_modules/' node server.js");
watch-restart -g '**/*.js,!node_modules/' --debounce 500 --throttle 2000 node server.js
watch-restart -g '**/*.js,!node_modules/' --check-md5 --kill-signal 'SIGTERM,SIGTERM,SIGKILL' --kill-retry-interval '100,200,500' -- node server.js
watch-restart -g '**/*.js,!node_modules/' --shell node 'console.log(\"run\"); setInterval(()=>{}, 1000)'

Options:

-g, --globs <patterns> Glob patterns to watch, separated by comma, to ignore pattern start it with '!'
--events <events> Restart only for specified events, separated by comma, possible values: create, change, delete
-d, --debounce <ms> Restart cmd only after no events for N ms, default 50
-t, --throttle <ms> Restart cmd no more then once in N ms, default 0
--reglob <ms> Glob files every N ms to track added files/dirs, default 1000
--check-md5 Check md5 checksum of files and fire events only if checksum is changed
--no-check-mtime Don't check mtime of files and fire events only if mtime is changed
--no-restart-on-error Don't restart cmd if cmd crashed or exited with non 0 code
--no-restart-on-success Don't restart cmd if cmd exited with 0 code
--shell <shell cmd> Custom shell to use for running cmd
--no-shell Run directly without shell
--kill-signal <signals> Signal to send to child when process.kill(pid, signal), separated by comma
--kill-timeout <ms> After which return with error
--kill-retry-interval <intervals> Intervals between sending of kill signal, separated by comma
--kill-retry-count <n> Number of retries
--kill-check-interval <ms> Interval between checks if process is dead
--kill-use-pgid Use PGID to get all children on mac/linux
--kill-children-immediately Kill children immediately, don't wait for parent to die
--silent No output from running cmd
-v, --verbose Log when files are changed and cmd is restarted
-V, --version Output version