Never Pet Marmots

    gargoyle

    1.0.1 • Public • Published

    Gargoyle

    Build Status NPM version

    Monitor a directory for changes. You can detect file changes, creations, deletions and renames. You know it works because it actually has tests!

    Installation

    Via NPM: npm install gargoyle

    Usage

    There is one export: gargoyle.monitor(path[, options, callback]). path should be a filename (file or directory). IF it's a directory, it'll be traversed recursively.

    When something changes, it'll emit one of the following events:

    • modify - when a file is modified
    • create - when a file is created
    • delete - when a file is deleted
    • rename - when a file is renamed (only when options.type === "watch")

    Your event listener should be a function that takes one argument: the absolute path of the file that got modified/created/deleted/renamed.

    Example

    Monitor a directory tree:

    var gargoyle = require('gargoyle');
    gargoyle.monitor('/some/dir', function(err, monitor) {
        if (err) {
            console.error(err);
            return;
        }
     
        //monitor is an EventEmitter with the following properties:
        //  files is a hash of filename -> FSWatcher
     
        monitor.on('modify', function(filename) {
            console.log(filename + ' was modified');
        });
        monitor.on('delete', function(filename) {
            console.log(filename + ' was deleted');
        });
        monitor.on('create', function(filename) {
            console.log(filename + ' was created');
        });
     
        //only when options.type === "watch"
        monitor.on('rename', function(filename) {
            console.log(filename + ' was renamed');
        });
    });

    Stop monitoring:

    monitor.stop(function() {
        console.log('watchers stopped');
    });
     
    //monitor is now worthless

    Options

    There are a few different options you can pass as an optional second parameter to gargoyle.monitor.

    Exclude certain files

    var path = require('path');
    var options = {
        exclude: function(filename, stat) {
            //note: filename is absolute
            var basename = path.basename(filename);
     
            //ignore dotfiles
            if (basename.charAt(0) === '.') {
                return true;
            }
     
            //ignore the static directory
            if (stat.isDirectory() && basename === 'static') {
                return true;
            }
     
            //javascript/coffeescript files are okay
            if (!/\.(js|coffee)$/.test(basename)) {
                return true;
            }
     
            return false;
        }
    };
    gargoyle.monitor('/some/dir', options, function(err, monitor) {
        //...
    });

    Watch type

    Use fs.watchFile instead of fs.watch. If you're on OS X, or trying to watch a network directory (e.g. a shared folder in a VM), you'll want to use fs.watchFile. fs.watch is far more efficient, and much faster, but doesn't work all the time.

    var options = {
        type: 'watchFile' //default is 'watch'
    };
    gargoyle.monitor('/some/dir', options, function(err, monitor) {
        //...
    });

    Poll interval

    If you use the watchFile type, you can define the poll interval for stating the filesystem (this is part of the watchFile Node API). The default is 507, which is 10x as fast as the Node default.

    var options = {
        type: 'watchFile',
        interval: 50 //poll 20 times a second
    };
    gargoyle.monitor('/some/dir', options, function(err, monitor) {
        //...
    });

    Development

    git clone git@github.com:tmont/gargoyle.git
    cd gargoyle
    npm install
    npm test

    When running the tests, you'll notice the fs.watchFile tests take much longer. This is due to the fact that some file systems do not have millisecond resolution, which means we have to wait at least one second to detect a modification.

    Keywords

    Install

    npm i gargoyle

    DownloadsWeekly Downloads

    6

    Version

    1.0.1

    License

    none

    Last publish

    Collaborators

    • tmont