| Linux | OS X | Windows |
|---|---|---|
|
|
|
|
NSFW is a native abstraction for Linux, Windows, and OSX file watching services which tries to keep a consistent interface and feature set across operating systems. NSFW offers recursive file watching into deep file systems all at no additional cost to the Javascript layer. In Linux, NSFW recursively builds an inotify watch tree natively, which collects events concurrently to the javascript thread. In OSX, NSFW utilizes the FSEventsService, which recursively watches for file system changes in a specified directory. In Windows, NSFW implements a server around the ReadDirectoryChangesW method.
When NSFW has events and is not being throttled, it will group those events in the order that they occurred and report them to the Javascript layer in a single callback. This is an improvement over services that utilize Node FS.watch, which uses a callback for every file event that is triggered. Every callback FS.watch makes to the event queue is a big bonus to NSFW's performance when watching large file system operations, because NSFW will only make 1 callback with many events within a specified throttle period.
So why NSFW? Because it has a consistent and minimal footprint in the Javascript layer, manages recursive watching for you, and is super easy to use.
var nsfw = require('nsfw');
var path = require('path');
var watcher1;
return nsfw(
'/home/nsfw/dir1',
function(events) {
// handle events
})
.then(function(watcher) {
watcher1 = watcher;
return watcher.start();
})
.then(function() {
// we are now watching dir1 for events!
// To stop watching
watcher1.stop()
});
// With options
var dir2 = '/home/nsfw/dir2';
var watcher2;
return nsfw(
dir2,
function(events) {
// handles other events
},
{
debounceMS: 250,
errorCallback(errors) {
//handle errors
},
excludedPaths: [path.join(dir2, 'node_modules')]
})
.then(function(watcher) {
watcher2 = watcher;
return watcher.start();
})
.then(function() {
// we are now watching dir2 for events!
// we can update excludedPaths array
return watcher2.updateExcludedPaths([path.join(dir2, 'node_modules'), path.join(dir2, '.git')]);
})
.then(function() {
// To stop watching
watcher2.stop();
})- debounceMS: delays notifications emitted by the library. Default 500 ms.
- errorCallback(errors): the library will call this callback when an error happens.
On Linux that includes an overflow of the inotify event queue (
fs.inotify.max_queued_events), which means events were lost: restart the watcher and rescan what you track. A directory watcher retires the failed run and releases that run's native resources before callingerrorCallback. Errors queued by a run that has already been explicitly stopped or replaced are discarded. After fixing the cause (for example, recreating a deleted directory), callstart()to watch again; callingstop()first is unnecessary. A previously queuedstart()may already have restarted the watcher, in which case anotherstart()rejects as already running.stop()on an already stopped watcher rejects. For directory watchers,start(),stop(),pause()andresume()run in call order. Thusstop(); start()restarts the watcher even whenstop()is not awaited. Each operation still returns a promise that should be handled for errors. - excludedPaths: array with the absolute paths we want to exclude watching. A relative one makes the promise
nsfw()returns reject; the ones outside the watched path are ignored. Paths match on whole path components: excluding/home/nsfw/dir2/builddoes not exclude/home/nsfw/dir2/build-tools. Trailing separators are dropped. You can update the excludedPaths array without restarting the service using theupdateExcludedPathsfunction, which handles the paths the same way and resolves with the paths that call set, without the ignored ones.getExcludedPathsresolves with the current ones.
An array of events as they have happened in a directory, it's children, or to a file.
[
{
"action": 2, // nsfw.actions.MODIFIED
"directory": "/home/nsfw/watchDir",
"file": "file1.ext"
},
{
"action": 0, // nsfw.actions.CREATED
"directory": "/home/nsfw/watchDir",
"file": "folder"
},
{
"action": 1, // nsfw.actions.DELETED
"directory": "home/nsfw/watchDir/testFolder",
"file": "test.ext"
},
{
"action": 3, // nsfw.actions.RENAMED
"directory": "home/nsfw/watchDir",
"oldFile": "oldname.ext",
"newDirectory": "home/nsfw/watchDir/otherDirectory"
"newFile": "newname.ext"
}
]Event are enumerated by the nsfw.actions enumeration
nsfw.actions = {
CREATED: 0,
DELETED: 1,
MODIFIED: 2,
RENAMED: 3
};NSFW is a native node module and requires Node-Gyp to be functional before you can install it. Make sure you have completed installing all of the dependencies listed for Node-Gyp on your operating system.