Awesome Open Source
Awesome Open Source

node-watch Status

A wrapper and enhancements for fs.watch.

NPM

Installation

npm install node-watch

Example

var watch = require('node-watch');

watch('file_or_dir', { recursive: true }, function(evt, name) {
  console.log('%s changed.', name);
});

Now it's fast to watch deep directories on macOS and Windows, since the recursive option is natively supported except on Linux.

// watch the whole disk
watch('/', { recursive: true }, console.log);

Why?

  • Some editors will generate temporary files which will cause the callback function to be triggered multiple times.
  • The callback function will only be triggered once on watching a single file.
  • Missing an option to watch a directory recursively.
  • Recursive watch is not supported on Linux or in older versions of nodejs.
  • Keep it simple, stupid.

Options

The usage and options of node-watch are compatible with fs.watch.

  • persistent: Boolean (default true)
  • recursive: Boolean (default false)
  • encoding: String (default 'utf8')

Extra options

  • filter: RegExp | Function

    Return that matches the filter expression.

    // filter with regular expression
    watch('./', { filter: /\.json$/ });
    
    // filter with custom function
    watch('./', { filter: f => !/node_modules/.test(f) });
    
  • delay: Number (in ms, default 200)

    Delay time of the callback function.

    // log after 5 seconds
    watch('./', { delay: 5000 }, console.log);
    

Events

The events provided by the callback function is either update or remove, which is less confusing to fs.watch's rename or change.

watch('./', function(evt, name) {

  if (evt == 'update') {
    // on create or modify
  }

  if (evt == 'remove') {
    // on delete
  }

});

Watcher object

The watch function returns a fs.FSWatcher like object as the same as fs.watch (>= v0.4.0).

Watcher events

watcher.on('change', function(evt, name) {
  // callback
});

watcher.on('error', function(err) {
  // handle error
});

watcher.on('ready', function() {
  // the watcher is ready to respond to changes
});

Close

// close
watcher.close();

// is closed?
watcher.isClosed()

List of methods

  • .on
  • .once
  • .emit
  • .close
  • .listeners
  • .setMaxListeners
  • .getMaxListeners
Extra methods
  • .isClosed detect if the watcher is closed

Known issues

Windows, node < v4.2.5

  • Failed to detect remove event
  • Failed to get deleted filename or directory name

MacOS, node 0.10.x

  • Will emit double event if the directory name is of one single character.

Misc

1. Watch multiple files or directories in one place

watch(['file1', 'file2'], console.log);

2. Customize watch command line tool

#!/usr/bin/env node

// https://github.com/nodejs/node-v0.x-archive/issues/3211
require('epipebomb')();

var watcher = require('node-watch')(
  process.argv[2] || './', { recursive: true }, console.log
);

process.on('SIGINT', watcher.close);

Monitoring chrome from disk:

$ watch / | grep -i chrome

3. Got ENOSPC error?

If you get ENOSPC error, but you actually have free disk space - it means that your OS watcher limit is too low and you probably want to recursively watch a big tree of files.

Follow this description to increase the limit: https://confluence.jetbrains.com/display/IDEADEV/Inotify+Watches+Limit

Alternatives

Contributors

Thanks goes to these wonderful people (emoji key):


Yuan Chuan

💻 📖 ⚠️

Greg Thornton

💻 🤔

Amir Arad

💻 📖 ⚠️

Gary Burgess

💻

Peter deHaan

💻

kcliu

💻

Hoovinator

💬

Steve Shreeve

💻

Blake Regalia

💻

Mike Collins

💻

Timo Tijhof

💻

Bailey Herbert

💻

Anthony Rey

💻

This project follows the all-contributors specification. Contributions of any kind welcome!

License

MIT

Copyright (c) 2020 yuanchuan


Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
javascript (63,884) 
wrapper (195) 
watcher (25) 

Find Open Source By Browsing 7,000 Topics Across 59 Categories