1
Fork 0
cheap-watch/README.md

68 lines
3.5 KiB
Markdown
Raw Permalink Normal View History

2018-04-02 21:17:52 +00:00
# Cheap Watch: If it works, why use something else?
2018-10-24 10:55:02 +00:00
[![npm version](https://img.shields.io/npm/v/cheap-watch.svg?style=flat-square)](https://www.npmjs.com/package/cheap-watch) [![Build Status](https://travis-ci.org/Conduitry/cheap-watch.svg?branch=master)](https://travis-ci.org/Conduitry/cheap-watch)
2018-04-02 21:17:52 +00:00
**Cheap Watch** is a small, simple, dependency-free, cross-platform file system watcher for Node.js 8+.
## Constructor
2018-04-02 21:24:44 +00:00
### `new CheapWatch({ dir, filter, watch = true, debounce = 10 })`
2018-04-02 21:17:52 +00:00
- `dir` - The directory whose contents to watch. It's recommended, though not required, for this to be an absolute path, say one returned by `path.resolve`.
2018-04-02 23:47:44 +00:00
- `filter({ path, stats })` - _(optional)_ A function to decide whether a given file or directory should be watched. It's passed an object containing the file or directory's relative `path` and its `stats`. It should return `true` or `false` (or a `Promise` resolving to one of those). Returning `false` for a directory means that none of its contents will be watched.
2018-04-03 12:24:38 +00:00
- `watch` - _(optional)_ Whether to actually watch the directory for changes. Defaults to `true`. If `false`, you can retrieve all of the files and directories within a given directory along with their initial `Stats` but changes will not be monitored.
- `debounce` - _(optional)_ Length of timeout in milliseconds to use to debounce incoming events from `fs.watch`. Defaults to 10. Multiple events are often emitted for a single change, and events can also be emitted before `fs.stat` reports the changes. So we will wait until `debounce` milliseconds have passed since the last `fs.watch` event for a file or directory before handling it. The default of 10ms Works On My Machine.
2018-04-02 21:17:52 +00:00
## Methods
2018-04-04 01:19:48 +00:00
### `init()`
2018-04-02 21:17:52 +00:00
2018-04-02 23:47:44 +00:00
Initialize the watcher, traverse the directory to find the initial files and directories, and set up watchers to look for changes.
2018-04-02 21:17:52 +00:00
2018-04-02 23:47:44 +00:00
This returns a `Promise` that resolves once the initial contents of the directory have been traversed and all of the watchers have been set up.
2018-04-02 21:17:52 +00:00
2018-04-04 01:19:48 +00:00
### `close()`
2018-04-02 21:17:52 +00:00
Close all `FSWatcher` instances, and stop watching for file changes.
2018-04-02 23:47:44 +00:00
## Properties
2018-04-04 01:19:48 +00:00
### `paths`
2018-04-02 23:47:44 +00:00
2018-04-03 12:24:38 +00:00
A `Map` of the watched files and directories. Each key is a relative path from the `CheapWatch`'s `dir`, and each value is a `Stats` object for the file or directory. Paths are always separated by forward slashes, regardless of platform. This `Map` is kept up to date as files are changed on disk.
2018-04-02 23:47:44 +00:00
You can use `stats.isFile()` and `stats.isDirectory()` to determine whether something is a file or a directory.
2018-04-02 21:17:52 +00:00
## Events
2018-04-03 12:24:38 +00:00
A `CheapWatch` is an `EventEmitter`, and emits two events to report a new, updated, or deleted file or directory.
2018-04-02 21:17:52 +00:00
2018-04-04 01:50:57 +00:00
### `+` `{ path, stats, isNew }`
2018-04-02 21:17:52 +00:00
2018-04-04 01:50:57 +00:00
A `+` event is emitted whenever a watched file or directory is created or updated. It's emitted with an object containing a `path` string, a `stats` object, and an `isNew` boolean which will be `true` for newly created files and directories and `false` for updated ones.
2018-04-02 21:17:52 +00:00
2018-04-02 23:47:44 +00:00
### `-` `{ path, stats }`
2018-04-02 21:17:52 +00:00
2018-04-04 01:50:57 +00:00
A `-` event is emitted whenever a watched file or directory is deleted. It's emitted with an object containing a `path` string and a `stats` object. `stats` will be the most recent `Stats` collected for the file or directory before it was deleted.
2018-04-02 21:17:52 +00:00
## Usage
```javascript
import CheapWatch from 'cheap-watch';
2018-04-04 01:19:48 +00:00
const watch = new CheapWatch({ dir, /* ... */ });
2018-04-02 21:17:52 +00:00
2018-04-04 01:19:48 +00:00
await watch.init();
2018-04-02 23:47:44 +00:00
2018-04-04 01:19:48 +00:00
for (const [path, stats] of watch.paths) {
2018-04-02 23:47:44 +00:00
/* ... */
}
2018-04-02 21:17:52 +00:00
2018-04-04 01:58:50 +00:00
watch.on('+', ({ path, stats, isNew }) => { /* ... */ });
2018-04-04 01:19:48 +00:00
watch.on('-', ({ path, stats }) => { /* ... */ });
2018-04-02 21:17:52 +00:00
```
## License
2018-12-10 20:58:25 +00:00
[MIT](LICENSE)