dirWatcher

a directory watcher that supplies some feature the fs.watch() doesn't have.

• more events(including added, removed, modified, renamed, moved).
• more options(see below).
• also watches the directory itself, not only its children.

usage

var watcher = new fswin.dirWatcher(dirToWatch, callback, [options]);

• watcher is an object that is constructed by fswin.dirWatcher. it has a method close().
• dirToWatch is a string that specifies a directory you want to watch.
• callback is a function to make callback with. it takes 2 arguments event and message. see the example for details.
• options is not required, see the example for details.

example

var fswin = require('fswin');
var options = {
	WATCH_SUB_DIRECTORIES: true, //watch the directory tree
	CHANGE_FILE_SIZE: true, //watch file size changes, will fire in 'MODIFIED' event
	CHANGE_LAST_WRITE: true, //watch last write time changes, will fire in 'MODIFIED' event
	CHANGE_LAST_ACCESS: false, //watch last access time changes, will fire in 'MODIFIED' event
	CHANGE_CREATION: false, //watch creation time changes, will fire in 'MODIFIED' event
	CHANGE_ATTRIBUTES: false, //watch attributes changes, will fire in 'MODIFIED' event
	CHANGE_SECUTITY: false //watch security changes, will fire in 'MODIFIED' event
};
var watcher = new fswin.dirWatcher( //the 'new' operator can be ignored
	'c:\\windows', //the directory you are about to watch
	function (event, message) {
		if (event === 'STARTED') {
			console.log('watcher started in: "' + message + '". the message is a full path. and it could be different from the path that you passed in, as symlink will resolve to its target.');
		} else if (event === 'MOVED') {
			console.log('the directory you are watching is moved to "' + message + '". the message is a full path. just like the "STARTED" event');
		} else if (event === 'ADDED') {
			console.log('"' + message + '" is added. it could be created or moved to here.');
		} else if (event === 'REMOVED') {
			console.log('"' + message + '" is removed. it could be deleted or moved from here.');
		} else if (event === 'MODIFIED') {
			console.log('"' + message + '" is modified. this event does not contain any detail of what change is made.');
		} else if (event === 'RENAMED') {
			console.log('"' + message.OLD_NAME + '" is renamed to "' + message.NEW_NAME + '"');
		} else if (event === 'ENDED') {
			console.log('the watcher is about to quit. it is safe to set the watcher to null or any other value now.');
		} else if (event === 'ERROR') {
			if (message === 'INITIALIZATION_FAILED') {
				console.log('failed to initialize the watcher. any failure during the initialization may case this error. such as the path is inaccessible or nonexistent.');
			} else if (message === 'UNABLE_TO_WATCH_SELF') {
				console.log('failed to watch parent directory. it means the "MOVED" event will no longer fire.');
			} else if (message === 'UNABLE_TO_CONTINUE_WATCHING') {
				console.log('some error makes the watcher stop working. perhaps the directory you are watching is deleted or becoming inaccessible. the "ENDED" event will fire after this error.');
			}
		}
		//if you want to stop watching, call the close method
		//note: this method returns false if the watcher is already or being closed. otherwise true
		//if (this.close()) {
		//	console.log('closing the watcher.');
		//} else {
		//	console.log('no need to close the watcher again.');
		//}
	},
	options //not required, and this is the default value, since filesize+lastwrite is usually enough to indicate a content change in most case.
);