README.md

Monocle -- a tool for watching things

Have you ever wanted to watch a folder and all of its files/nested folders for changes. well now you can!

Installation

npm install monocle

Usage

Watch a directory:

var monocle = require('monocle')()
monocle.watchDirectory({
  root: <root directory>,
  fileFilter: <optional>,
  directoryFilter: <optional>,
  listener: fn(fs.stat+ object), //triggered on file change / addition
  complete: <fn> //file watching all set up
});

The listener will recive an object with the following

  name: <filename>,
  path: <filepath-relative>,
  fullPath: <filepath-absolute>,
  parentDir: <parentDir-relative>,
  fullParentDir: <parentDir-absolute>,
  stat: <see fs.stats>

fs.stats

When a new file is added to the directoy it triggers a file change and thus will be passed to your specified listener.

The two filters are passed through to readdirp. More documentation can be found here

Watch a list of files:

Monocle.watchFiles({
  files: [], //path of file(s)
  listener: <fn(fs.stat+ object)>, //triggered on file / addition
  complete: <fn> //file watching all set up
});

Just watch path

Just an alias of watchFiles and watchDirectory so you don't need to tell if that's a file or a directory by yourself. Parameter passed to path can be a string or a array of string.

Monocle.watchPaths({
  path: [], //list of paths, or a string of path
  fileFilter: <optional>, // `*.js` for example
  listener: <fn(fs.stat+ object)>, //triggered on file / addition
  complete: <fn> //file watching all set up
});

Force to use fs.watch

You can use the USE_FS_WATCH env variable set to true, to force this behavior regardless of platform.

Why not just use fs.watch ?

• file watching is really bad cross platforms in node
• you need to be smart when using fs.watch as compared to fs.watchFile
• Monocle takes care of this logic for you!
• windows systems use fs.watch
• osx and linux uses fs.watchFile

License

BSD