UNPKG

1.8 kBMarkdownView Raw
1[![Build Status](https://travis-ci.org/samccone/monocle.png?branch=master)](https://travis-ci.org/samccone/monocle)
2
3# Monocle -- a tool for watching things
4
5[![logo](https://raw.github.com/samccone/monocle/master/logo.png)](https://raw.github.com/samccone/monocle/master/logo.png)
6
7Have you ever wanted to watch a folder and all of its files/nested folders for changes. well now you can!
8
9## Installation
10
11```
12npm install monocle
13```
14
15## Usage
16
17### Watch a directory:
18
19```js
20var monocle = require('monocle')()
21monocle.watchDirectory({
22 root: <root directory>,
23 fileFilter: <optional>,
24 directoryFilter: <optional>,
25 listener: fn(fs.stat+ object), //triggered on file change / addition
26 complete: <fn> //file watching all set up
27});
28```
29
30The listener will recive an object with the following
31
32```js
33 name: <filename>,
34 path: <filepath-relative>,
35 fullPath: <filepath-absolute>,
36 parentDir: <parentDir-relative>,
37 fullParentDir: <parentDir-absolute>,
38 stat: <see fs.stats>
39```
40
41[fs.stats](http://nodejs.org/api/fs.html#fs_class_fs_stats)
42
43When a new file is added to the directoy it triggers a file change and thus will be passed to your specified listener.
44
45The two filters are passed through to `readdirp`. More documentation can be found [here](https://github.com/thlorenz/readdirp#filters)
46
47### Watch a list of files:
48
49```js
50Monocle.watchFiles({
51 files: [], //path of file(s)
52 listener: <fn(fs.stat+ object)>, //triggered on file / addition
53 complete: <fn> //file watching all set up
54});
55```
56
57## Why not just use fs.watch ?
58
59 - file watching is really bad cross platforms in node
60 - you need to be smart when using fs.watch as compared to fs.watchFile
61 - Monocle takes care of this logic for you!
62 - windows systems use fs.watch
63 - osx and linux uses fs.watchFile
64
65
66## License
67
68BSD