watchr

Watchr provides a normalised API the file watching APIs of different node versions, nested/recursive file and directory watching, and accurate detailed events for file/directory creations, updates, and deletions.

Install

NPM

Install: npm install --save watchr

Module: require('watchr')

Editions

This package is published with the following editions:

watchr aliases watchr/index.js which uses Editions to automatically select the correct edition for the consumers environment
watchr/source/index.js is Source + ESNext + Require + Flow Type Comments
watchr/es2015/index.js is Babel Compiled + ES2015 + Require

Older environments may need Babel's Polyfill or something similar.

Usage

API Documentation

There are two concepts in watchr, they are:

Watcher - this wraps the native file system watching, makes it reliable, and supports deep watching
Stalker - this wraps the watcher, such that for any given path, there can be many stalkers, but only one watcher

The simplest usage is:

// Import the watching library 
var watchr = require('watchr')
 
// Define our watching parameters 
var path = process.cwd()
function listener (changeType, fullPath, currentStat, previousStat) {
    switch ( changeType ) {
        case 'update':
            console.log('the file', fullPath, 'was updated', currentStat, previousStat)
            break
        case 'create':
            console.log('the file', fullPath, 'was created', currentStat)
            break
        case 'delete':
            console.log('the file', fullPath, 'was deleted', previousStat)
            break
    }
}
function next (err) {
    if ( err )  return console.log('watch failed on', path, 'with error', err)
    console.log('watch successful on', path)
}
 
// Watch the path with the change listener and completion callback 
var stalker = watchr.open(path, listener, next)
 
// Close the stalker of the watcher 
stalker.close()

More advanced usage is:

// Create the stalker for the path 
var stalker = watchr.create(path)
 
// Listen to the events for the stalker/watcher 
// http://rawgit.com/bevry/watchr/master/docs/index.html#watcher 
stalker.on('change', listener)
stalker.on('log', console.log)
stalker.once('close', function (reason) {
    console.log('closed', path, 'because', reason)
    stalker.removeAllListeners()  // as it is closed, no need for our change or log listeners any more 
})
 
// Set the default configuration for the stalker/watcher 
// http://rawgit.com/bevry/watchr/master/docs/index.html#Watcher%23setConfig 
stalker.setConfig({
    stat: null,
    interval: 5007,
    persistent: true,
    catchupDelay: 2000,
    preferredMethods: ['watch', 'watchFile'],
    followLinks: true,
    ignorePaths: false,
    ignoreHiddenFiles: false,
    ignoreCommonPatterns: true,
    ignoreCustomPatterns: null
})
 
// Start watching 
stalker.watch(next)
 
// Stop watching 
stalker.close()