sane

What is sane?

The 'sane' npm package is a file watcher that provides a simple and efficient way to monitor file changes in a directory. It is particularly useful for development workflows where you need to automatically trigger actions when files are modified, added, or deleted.

What are sane's main functionalities?

Basic File Watching

This feature allows you to watch a directory for changes to specific file types. The code sample demonstrates how to set up a watcher for JavaScript and CSS files, and how to handle events for file changes, additions, and deletions.

const sane = require('sane');
const watcher = sane('./path/to/dir', {glob: ['**/*.js', '**/*.css']});

watcher.on('ready', () => { console.log('Ready to watch files'); });
watcher.on('change', (filepath, root, stat) => { console.log('File changed:', filepath); });
watcher.on('add', (filepath, root, stat) => { console.log('File added:', filepath); });
watcher.on('delete', (filepath, root) => { console.log('File deleted:', filepath); });

Custom Watcher Options

This feature allows you to customize the behavior of the file watcher. The code sample shows how to enable polling with a specific interval, which can be useful in environments where native file watching is not reliable.

const sane = require('sane');
const watcher = sane('./path/to/dir', {
  glob: ['**/*.js'],
  poll: true,
  interval: 1000
});

watcher.on('ready', () => { console.log('Ready to watch files with custom options'); });
watcher.on('change', (filepath, root, stat) => { console.log('File changed:', filepath); });

Ignoring Files and Directories

This feature allows you to ignore specific files or directories from being watched. The code sample demonstrates how to ignore the 'node_modules' directory and any JavaScript test files.

const sane = require('sane');
const watcher = sane('./path/to/dir', {
  ignored: ['node_modules', '**/*.test.js']
});

watcher.on('ready', () => { console.log('Ready to watch files, ignoring specified patterns'); });
watcher.on('change', (filepath, root, stat) => { console.log('File changed:', filepath); });

Other packages similar to sane

chokidar

Chokidar is a popular and highly performant file watcher for Node.js. It provides a rich set of features, including support for recursive watching, custom ignore patterns, and the ability to watch individual files. Compared to 'sane', Chokidar is known for its robustness and extensive configuration options.

watch

The 'watch' package is a simple and lightweight file watcher for Node.js. It provides basic functionality for watching files and directories, with a focus on simplicity and ease of use. While it may not offer as many features as 'sane' or 'chokidar', it is a good choice for straightforward use cases.

gaze

Gaze is another file watcher for Node.js that offers a balance between simplicity and functionality. It supports glob patterns, custom ignore patterns, and event handling for file changes, additions, and deletions. Gaze is similar to 'sane' in terms of features but may have different performance characteristics depending on the use case.

README

sane

I've been driven to insanity by node filesystem watcher wrappers. Sane aims to be fast, small, and reliable file system watcher. It does that by:

• By default stays away from fs polling because it's very slow and cpu intensive
• Uses fs.watch by default and sensibly works around the various issues
• Maintains a consistent API across different platforms
• Where fs.watch is not reliable you have the choice of using the following alternatives:
  • the facebook watchman library
  • the watchexec library
  • polling

Install

$ npm install sane

How to choose a mode

Don't worry too much about choosing the correct mode upfront because sane maintains the same API across all modes and will be easy to switch.

• If you're only supporting Linux and OS X, watchman would be the most reliable mode
• If you're using node > v0.10.0 use the default mode
• If you're running OS X and you're watching a lot of directories and you're running into https://github.com/joyent/node/issues/5463, use watchman
• If you're in an environment where native file system events aren't available (like Vagrant), you should use polling
• Otherwise, the default mode should work well for you

API

sane(dir, options)

Watches a directory and all its descendant directories for changes, deletions, and additions on files and directories.

var watcher = sane('path/to/dir', {glob: ['**/*.js', '**/*.css']});
watcher.on('ready', function () { console.log('ready') });
watcher.on('change', function (filepath, root, stat) { console.log('file changed', filepath); });
watcher.on('add', function (filepath, root, stat) { console.log('file added', filepath); });
watcher.on('delete', function (filepath, root) { console.log('file deleted', filepath); });
// close
watcher.close();

options:

• glob: a single string glob pattern or an array of them.
• poll: puts the watcher in polling mode. Under the hood that means fs.watchFile.
• watchman: makes the watcher use watchman.
• watchmanPath: sets a custom path for watchman binary.
• watchexec: makes the watcher use watchexec.
• dot: enables watching files/directories that start with a dot.
• ignored: a glob, regex, function, or array of any combination.

For the glob pattern documentation, see micromatch. If you choose to use watchman you'll have to install watchman yourself). If you choose to use watchexec you'll have to install watchexec yourself). For the ignored options, see anymatch.

sane.NodeWatcher(dir, options)

The default watcher class. Uses fs.watch under the hood, and takes the same options as sane(dir, options).

sane.WatchmanWatcher(dir, options)

The watchman watcher class. Takes the same options as sane(dir, options).

sane.Watchexec(dir, options)

The watchexec watcher class. Takes the same options as sane(dir, options).

sane.PollWatcher(dir, options)

The polling watcher class. Takes the same options as sane(dir, options) with the addition of:

• interval: indicates how often the files should be polled. (passed to fs.watchFile)

sane.{Node|Watchman|Watchexec|Poll}Watcher#close

Stops watching.

sane.{Node|Watchman|Watchexec|Poll}Watcher events

Emits the following events:

All events are passed the file/dir path relative to the root directory

• ready when the program is ready to detect events in the directory
• change when a file changes
• add when a file or directory has been added
• delete when a file or directory has been deleted

CLI

This module includes a simple command line interface, which you can install with npm install sane -g.

Usage: sane <command> [...directory] [--glob=<filePattern>] [--poll] [--watchman] [--watchman-path=<watchmanBinaryPath>] [--dot] [--wait=<seconds>]

OPTIONS:
    --glob=<filePattern>
      A single string glob pattern or an array of them.

    --ignored=<filePattern>
      A glob, regex, function, or array of any combination.

    --poll, -p
      Use polling mode.

    --watchman, -w
      Use watchman (if available).

    --watchman-path=<watchmanBinaryPath>
      Sets a custom path for watchman binary (if using this mode).

    --dot, -d
      Enables watching files/directories that start with a dot.

    --wait=<seconds>
      Duration, in seconds, that watching will be disabled
      after running <command>. Setting this option will
      throttle calls to <command> for the specified duration.
    --quiet, -q
      Disables sane's console output

    --changes-only, -o
      Runs <command> only when a change occur. Skips running <command> at startup

It will watch the given directory and run the given every time a file changes.

CLI example usage

• sane 'echo "A command ran"'
• sane 'echo "A command ran"' --glob='**/*.css'
• sane 'echo "A command ran"' site/assets/css --glob='**/*.css'
• sane 'echo "A command ran"' --glob='**/*.css' --ignored='**/ignore.css'
• sane 'echo "A command ran"' --wait=3
• sane 'echo "A command ran"' -p

License

MIT

Credits

The CLI was originally based on the watch CLI. Watch is licensed under the Apache License Version 2.0.