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:

• Always use fs.watch (unless polling is forced) and sensibly workaround the various issues with it
• Sane is all JavaScript, no native components
• Stay away from polling because it's very slow and cpu intensive
• Support polling for environments like Vagrant shared directory where there are no native filesystem events

Install

$ npm install sane

If you're using node < v0.10.0 then make sure to start sane with poll: true.

API

sane(dir, globs, options)

Watches a directory and all it's descendant directorys for changes, deletions, and additions on files and directories. Shortcut for new sane.Watcher(dir, {glob: globs, ..options}).

var watcher = sane('path/to/dir', ['**/*.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();

For options see sane.Watcher.

sane.Watcher(dir, options)

options:

• persistent: boolean indicating that the process shouldn't die while we're watching files.
• 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.
• interval: indicates how often the files should be polled. (passed to fs.watchFile)

For the glob pattern documentation, see minimatch.

sane.Watcher#close

Stops watching.

sane.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

License

MIT