watchr

4.1.0 • Public • Published 4 months ago

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 esnext source code with require for modules
watchr/edition-node-0.12/index.js is esnext compiled for node.js 0.12 with require for modules

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()