1 | # watchpack
|
2 |
|
3 | Wrapper library for directory and file watching.
|
4 |
|
5 | [![Build Status](https://travis-ci.org/webpack/watchpack.svg?branch=master)](https://travis-ci.org/webpack/watchpack) [![Build status](https://ci.appveyor.com/api/projects/status/e5u2qvmugtv0r647/branch/master?svg=true)](https://ci.appveyor.com/project/sokra/watchpack/branch/master)
|
6 |
|
7 | ## Concept
|
8 |
|
9 | watchpack high level API don't map directly to watchers. Instead a three level architecture ensures that for each directory only a single watcher exists.
|
10 |
|
11 | * The high level API requests `DirectoryWatchers` from a `WatcherManager`, which ensures that only a single `DirectoryWatcher` per directory is created.
|
12 | * A user-faced `Watcher` can be obtained from a `DirectoryWatcher` and provides a filtered view on the `DirectoryWatcher`.
|
13 | * Reference-counting is used on the `DirectoryWatcher` and `Watcher` to decide when to close them.
|
14 | * The real watchers (currently chokidar) are created by the `DirectoryWatcher`.
|
15 | * Files are never watched directly. This should keep the watcher count low.
|
16 | * Watching can be started in the past. This way watching can start after file reading.
|
17 | * Symlinks are not followed, instead the symlink is watched.
|
18 |
|
19 | ## API
|
20 |
|
21 | ``` javascript
|
22 | var Watchpack = require("watchpack");
|
23 |
|
24 | var wp = new Watchpack({
|
25 | // options:
|
26 | aggregateTimeout: 1000
|
27 | // fire "aggregated" event when after a change for 1000ms no additonal change occured
|
28 | });
|
29 |
|
30 | // Watchpack.prototype.watch(string[] files, string[] directories, [number startTime])
|
31 | wp.watch(listOfFiles, listOfDirectories, Date.now() - 10000);
|
32 | // starts watching these files and directories
|
33 | // calling this again will override the files and directories
|
34 |
|
35 | wp.on("change", function(filePath, mtime) {
|
36 | // filePath: the changed file
|
37 | // mtime: last modified time for the changed file
|
38 | });
|
39 |
|
40 | wp.on("aggregated", function(changes) {
|
41 | // changes: an array of all changed files
|
42 | });
|
43 |
|
44 | // Watchpack.prototype.pause()
|
45 | wp.pause();
|
46 | // stops emitting events, but keeps watchers open
|
47 |
|
48 | // Watchpack.prototype.close()
|
49 | wp.close();
|
50 | // stops emitting events and closes all watchers
|
51 |
|
52 | // Watchpack.prototype.getTimes()
|
53 | var fileTimes = wp.getTimes();
|
54 | // returns an object with all know change times for files
|
55 | // this include timestamps from files not directly watched
|
56 | // key: absolute path, value: timestamp as number
|
57 | ```
|
58 |
|