watch

What is watch?

The 'watch' npm package is a utility that allows you to monitor files and directories for changes. It can be used to trigger actions when files are modified, added, or deleted, making it useful for tasks such as automated testing, live reloading, and continuous integration.

What are watch's main functionalities?

Watch a single file

This feature allows you to watch a single file for changes. When the file is modified, the callback function is triggered.

const watch = require('watch');

watch.watchFile('/path/to/file', function (curr, prev) {
  console.log('File changed');
});

Watch a directory

This feature allows you to watch a directory and its subdirectories for changes. The callback function is triggered when files are added, removed, or modified.

const watch = require('watch');

watch.watchTree('/path/to/dir', function (f, curr, prev) {
  if (typeof f == 'object' && prev === null && curr === null) {
    console.log('Finished walking the tree');
  } else if (prev === null) {
    console.log('New file added: ' + f);
  } else if (curr.nlink === 0) {
    console.log('File removed: ' + f);
  } else {
    console.log('File changed: ' + f);
  }
});

Ignore specific files or directories

This feature allows you to ignore specific files or directories while watching. In this example, dot files and the 'node_modules' directory are ignored.

const watch = require('watch');

watch.watchTree('/path/to/dir', {
  ignoreDotFiles: true,
  filter: function (f, stat) {
    return !/node_modules/.test(f);
  }
}, function (f, curr, prev) {
  console.log('File changed: ' + f);
});

Other packages similar to watch

chokidar

Chokidar is a highly efficient and feature-rich file watcher. It uses native OS events to provide fast and reliable file watching. Compared to 'watch', Chokidar offers more advanced features such as debouncing, polling, and support for various file system events.

gaze

Gaze is another file watcher that provides a simple API for watching files and directories. It supports recursive watching and can be used as a drop-in replacement for 'watch'. Gaze is known for its ease of use and flexibility.

node-watch

Node-watch is a lightweight file watcher that provides a simple API for watching files and directories. It is similar to 'watch' but offers better performance and reliability. Node-watch is suitable for projects that require minimal dependencies and fast file watching.

README

watch -- Utilities for watching file trees in node.js

Install

  npm install watch

Purpose

The intention of this module is provide tools that make managing the watching of file & directory trees easier.

watch.watchTree(root, [options,] callback)

The first argument is the directory root you want to watch.

The options object is passed to fs.watchFile but can also be used to provide to additional watchTree specific options:

• 'ignoreDotFiles' - When true this option means that when the file tree is walked it will ignore files that being with "."
• 'filter' - You can use this option to provide a function that returns true or false for each file and directory that is walked to decide whether or not that file/directory is included in the watcher.

The callback takes 3 arguments. The first is the file that was modified. The second is the current stat object for that file and the third is the previous stat object.

When a file is new the previous stat object is null.

When watchTree is finished walking the tree and adding all the listeners it passes the file hash (key if the file/directory names and the values are the current stat objects) as the first argument and null as both the previous and current stat object arguments.

  watch.watchTree('/home/mikeal', function (f, curr, prev) {
    if (typeof f == "object" && prev === null && curr === null) {
      // Finished walking the tree
    } else if (prev === null) {
      // f is a new file
    } else if (curr.nlink === 0) {
      // f was removed
    } else {
      // f was changed
    }
  })

watch.createMonitor(root, [options,] callback)

This function creates an EventEmitter that gives notifications for different changes that happen to the file and directory tree under the given root argument.

The options object is passed to watch.watchTree.

The callback receives the monitor object.

The monitor object contains a property, files, which is a hash of files and directories as keys with the current stat object as the value.

The monitor has the following events.

• 'created' - New file has been created. Two arguments, the filename and the stat object.
• 'removed' - A file has been moved or deleted. Two arguments, the filename and the stat object for the fd.
• 'changed' - A file has been changed. Three arguments, the filename, the current stat object, and the previous stat object.

  watch.createMonitor('/home/mikeal', function (monitor) {
    monitor.files['/home/mikeal/.zshrc'] // Stat object for my zshrc.
    monitor.on("created", function (f, stat) {
      // Handle file changes
    })
    monitor.on("changed", function (f, curr, prev) {
      // Handle new files
    })
    monitor.on("removed", function (f, stat) {
      // Handle removed files
    })
  }