1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
|
# node-watch [](https://github.com/yuanchuan/node-watch/actions/workflows/ci.yml/badge.svg)
A wrapper and enhancements for [fs.watch](http://nodejs.org/api/fs.html#fs_fs_watch_filename_options_listener).
[](https://nodei.co/npm/node-watch.png/)
## Installation
```bash
npm install node-watch
```
## Example
```js
var watch = require('node-watch');
watch('file_or_dir', { recursive: true }, function(evt, name) {
console.log('%s changed.', name);
});
```
Now it's fast to watch **deep** directories on macOS and Windows, since the `recursive` option is natively supported except on Linux.
```js
// watch the whole disk
watch('/', { recursive: true }, console.log);
```
## Why?
* Some editors will generate temporary files which will cause the callback function to be triggered multiple times.
* The callback function will only be triggered once on watching a single file.
* <del>Missing an option to watch a directory recursively.</del>
* Recursive watch is not supported on Linux or in older versions of nodejs.
* Keep it simple, stupid.
## Options
The usage and options of `node-watch` are compatible with [fs.watch](https://nodejs.org/dist/latest-v7.x/docs/api/fs.html#fs_fs_watch_filename_options_listener).
* `persistent: Boolean` (default **true**)
* `recursive: Boolean` (default **false**)
* `encoding: String` (default **'utf8'**)
**Extra options**
* `filter: RegExp | Function`
Return that matches the filter expression.
```js
// filter with regular expression
watch('./', { filter: /\.json$/ });
// filter with custom function
watch('./', { filter: f => !/node_modules/.test(f) });
```
Each file and directory will be passed to the filter to determine whether
it will then be passed to the callback function. Like `Array.filter` does in `JavaScript`.
There are three kinds of return values for filter function:
* **`true`**: Will be passed to callback.
* **`false`**: Will not be passed to callback.
* **`skip`**: Same with `false`, and skip to watch all its subdirectories.
On Linux, where the `recursive` option is not natively supported,
it is more efficient to skip ignored directories by returning the `skip` flag:
```js
watch('./', {
recursive: true,
filter(f, skip) {
// skip node_modules
if (/\/node_modules/.test(f)) return skip;
// skip .git folder
if (/\.git/.test(f)) return skip;
// only watch for js files
return /\.js$/.test(f);
}
});
```
If you prefer glob patterns you can use [minimatch](https://www.npmjs.com/package/minimatch) or [picomatch](https://www.npmjs.com/package/picomatch)
together with filter:
```js
const pm = require('picomatch');
let isMatch = pm('*.js');
watch('./', {
filter: f => isMatch(f)
});
```
* `delay: Number` (in ms, default **200**)
Delay time of the callback function.
```js
// log after 5 seconds
watch('./', { delay: 5000 }, console.log);
```
## Events
The events provided by the callback function is either `update` or `remove`, which is less confusing to `fs.watch`'s `rename` or `change`.
```js
watch('./', function(evt, name) {
if (evt == 'update') {
// on create or modify
}
if (evt == 'remove') {
// on delete
}
});
```
## Watcher object
The watch function returns a [fs.FSWatcher](https://nodejs.org/api/fs.html#fs_class_fs_fswatcher) like object as the same as `fs.watch` (>= v0.4.0).
#### Watcher events
```js
let watcher = watch('./', { recursive: true });
watcher.on('change', function(evt, name) {
// callback
});
watcher.on('error', function(err) {
// handle error
});
watcher.on('ready', function() {
// the watcher is ready to respond to changes
});
```
#### Close
```js
// close
watcher.close();
// is closed?
watcher.isClosed()
```
#### List of methods
* `.on`
* `.once`
* `.emit`
* `.close`
* `.listeners`
* `.setMaxListeners`
* `.getMaxListeners`
##### Extra methods
* `.isClosed` detect if the watcher is closed
* `.getWatchedPaths` get all the watched paths
## Known issues
**Windows, node < v4.2.5**
* Failed to detect `remove` event
* Failed to get deleted filename or directory name
**MacOS, node 0.10.x**
* Will emit double event if the directory name is of one single character.
## Misc
#### 1. Watch multiple files or directories in one place
```js
watch(['file1', 'file2'], console.log);
```
#### 2. Customize watch command line tool
```js
#!/usr/bin/env node
// https://github.com/nodejs/node-v0.x-archive/issues/3211
require('epipebomb')();
let watcher = require('node-watch')(
process.argv[2] || './', { recursive: true }, console.log
);
process.on('SIGINT', watcher.close);
```
Monitoring chrome from disk:
```bash
$ watch / | grep -i chrome
```
#### 3. Got ENOSPC error?
If you get ENOSPC error, but you actually have free disk space - it means that your OS watcher limit is too low and you probably want to recursively watch a big tree of files.
Follow this description to increase the limit:
[https://confluence.jetbrains.com/display/IDEADEV/Inotify+Watches+Limit](https://confluence.jetbrains.com/display/IDEADEV/Inotify+Watches+Limit)
## Alternatives
* [chokidar](https://github.com/paulmillr/chokidar)
* [gaze](https://github.com/shama/gaze)
* [mikeal/watch](https://github.com/mikeal/watch)
## Contributors
Thanks goes to [all wonderful people](https://github.com/yuanchuan/node-watch/graphs/contributors) who have helped this project.
## License
MIT
Copyright (c) 2012-2021 [yuanchuan](https://github.com/yuanchuan)
|
