glob-watcher

What is glob-watcher?

The glob-watcher package is a wrapper around the chokidar library, providing a way to watch file sets defined with glob patterns for changes. It is commonly used in build tools and scripts to automate tasks like reloading, testing, or compiling code when changes are detected in the file system.

What are glob-watcher's main functionalities?

Watching files for changes

This feature allows you to monitor a set of files defined by glob patterns for any changes. When a change is detected, a callback function is executed. It's useful for triggering rebuilds or tests automatically during development.

const { watch } = require('glob-watcher');
watch(['src/**/*.js'], (done) => {
  console.log('Files have changed!');
  done();
});

Debouncing and throttling events

This feature helps in controlling the rate at which events are handled. By debouncing or throttling, you can limit the number of times your callback function is called, which is particularly useful for reducing unnecessary processing during rapid file changes.

const { watch } = require('glob-watcher');
const watcher = watch('src/**/*.js', { delay: 100 });
watcher.on('change', (path) => console.log(`${path} has changed`));

Other packages similar to glob-watcher

chokidar

Chokidar is a more direct and flexible file watching library that glob-watcher depends on. It offers more detailed control over file watching events and options, making it a good choice for projects that need fine-grained event handling.

watchify

Watchify is a browserify plugin that provides a similar file watching capability, specifically optimized for incremental builds with Browserify. While it serves a similar purpose to glob-watcher, it is more tightly integrated with the Browserify ecosystem.

nodemon

Nodemon is a tool that helps develop node.js based applications by automatically restarting the node application when file changes in the directory are detected. It's similar to glob-watcher but is more focused on server-side applications.

README

glob-watcher

Watch globs and execute a function upon change, with intelligent defaults for debouncing and queueing.

Usage

var watch = require('glob-watcher');

watch(['./*.js', '!./something.js'], function (done) {
  // This function will be called each time a globbed file is changed
  // but is debounced with a 200ms delay (default) and queues subsequent calls

  // Make sure to signal async completion with the callback
  // or by returning a stream, promise, observable or child process
  done();

  // if you need access to the `path` or `stat` object, listen
  // for the `change` event (see below)

  // if you need to listen to specific events, use the returned
  // watcher instance (see below)
});

// Raw chokidar instance
var watcher = watch(['./*.js', '!./something.js']);

// Listen for the 'change' event to get `path`/`stat`
// No async completion available because this is the raw chokidar instance
watcher.on('change', function (path, stat) {
  // `path` is the path of the changed file
  // `stat` is an `fs.Stat` object (not always available)
});

// Listen for other events
// No async completion available because this is the raw chokidar instance
watcher.on('add', function (path, stat) {
  // `path` is the path of the changed file
  // `stat` is an `fs.Stat` object (not always available)
});

API

watch(globs[, options][, fn])

Takes a path string, an array of path strings, a glob string or an array of glob strings as globs to watch on the filesystem. Also optionally takes options to configure the watcher and a fn to execute when a file changes.

Note: As of 5.0.0, globs must use / as the separator character because \\ is reserved for escape sequences (as per the Bash 4.3 & Micromatch specs). This means you can't use path.join() or **dirnamein Windows environments. If you need to usepath.join(), you can use normalize-path against your paths afterwards. If you need to use **dirname, you can set it as the cwd option that gets passed directly to chokidar. The micromatch docs contain more information about backslashes.

Returns an instance of chokidar.

fn([callback])

If the fn is passed, it will be called when the watcher emits a change, add or unlink event. It is automatically debounced with a default delay of 200 milliseconds and subsequent calls will be queued and called upon completion. These defaults can be changed using the options.

The fn is passed a single argument, callback, which is a function that must be called when work in the fn is complete. Instead of calling the callback function, async completion can be signalled by:

• Returning a Stream or EventEmitter
• Returning a Child Process
• Returning a Promise
• Returning an Observable

Once async completion is signalled, if another run is queued, it will be executed.

options

options.ignoreInitial

If set to false the fn is called during chokidar instantiation as it discovers the file paths. Useful if it is desirable to trigger the fn during startup.

Passed through to chokidar, but defaulted to true instead of false.

Type: Boolean

Default: true

options.delay

The delay to wait before triggering the fn. Useful for waiting on many changes before doing the work on changed files, e.g. find-and-replace on many files.

Type: Number

Default: 200 (milliseconds)

options.queue

Whether or not a file change should queue the fn execution if the fn is already running. Useful for a long running fn.

Type: Boolean

Default: true

options.events

An event name or array of event names to listen for. Useful if you only need to watch specific events.

Type: String | Array<String>

Default: [ 'add', 'change', 'unlink' ]

other

Options are passed directly to chokidar.

License

MIT