# file-watch-iterator

> Watch files as an async iterator

Latest version **0.7.0** (published 2019-12-16) · 0 weekly downloads

## Install

```sh
npm install file-watch-iterator
pnpm add file-watch-iterator
yarn add file-watch-iterator
bun add file-watch-iterator
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.7.0 |
| Published | 2019-12-16 |
| First published | 2018-08-12 |
| Weekly downloads | 0 |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 4 |
| Unpacked size | 5.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 2 |
| Maintainers | laggingreflex |

## Links

- npm: https://www.npmjs.com/package/file-watch-iterator
- Repository: https://github.com/laggingreflex/file-watch-iterator
- Homepage: https://github.com/laggingreflex/file-watch-iterator#readme
- Issues: https://github.com/laggingreflex/file-watch-iterator/issues
- npm.io page: https://npm.io/package/file-watch-iterator

## Dependencies (4)

- [p-defer](https://npm.io/package/p-defer.md) ^3.0.0
- [chokidar](https://npm.io/package/chokidar.md) ^3.3.0
- [debounce-queue](https://npm.io/package/debounce-queue.md) ^0.3.1
- [break-async-iterator](https://npm.io/package/break-async-iterator.md) ^0.1.0

## Recent versions

- 0.7.0 (latest) — 2019-12-16
- 0.6.3 — 2018-12-23
- 0.6.2 — 2018-12-22
- 0.6.1 — 2018-12-22
- 0.6.0 — 2018-08-23
- 0.5.0 — 2018-08-13
- 0.4.1 — 2018-08-13
- 0.4.0 — 2018-08-13
- 0.3.0 — 2018-08-13
- 0.2.0 — 2018-08-13
- 0.1.1 — 2018-08-13
- 0.1.0 — 2018-08-12

## README

# file-watch-iterator

A simple wrapper around [chokidar] that returns an [async iterator][async-iteration] which you can [for-await] on to get the initial, and then later changed files.

**Requires ES2018 [Async Iteration][async-iteration]**

[chokidar]: https://github.com/paulmillr/chokidar
[async-iteration]: https://github.com/tc39/proposal-async-iteration
[for-await]: https://github.com/tc39/proposal-async-iteration#the-async-iteration-statement-for-await-of

## Install

```
npm i file-watch-iterator
```

## Usage

```js
const watch = require('file-watch-iterator')

for await (const files of watch('.')) {
  for (const file of files.changed(a)) {
    // ...
  }
  for (const file of files.deleted()) {
    // ...
  }
}
```

### API

* **`watch(paths, chokidarOpts, opts)`**

  * **`paths`** Paths/globs to watch (passed to chokidar)

  * **`chokidarOpts`** Options passed to chokidar

  * **`opts`**

    * **`debounce=100`** Debounce between file change as well as an indicator of first ever "ready" event (when (initially) the files are "changed" (discovered) very rapidly)

  * **Returns** an async-iterable which yields a **`Files`** instance with the following structure:

    * **`.files`** Complete and updated list of files:

      Eg.:

      ```js
      {
        '/example/a': {changed: false, event: 'add'},    // previously added
        '/example/b': {changed: true,  event: 'change'}, // newly modified
        '/example/c': {changed: true,  event: 'add'},    // newly added
        '/example/d': {changed: true,  event: 'unlink'}, // newly deleted
      }
      ```

      * **`<key>`** The `keys` are the actual file paths and values are:

        * **`changed`** A boolean that's `true` for files that changed, `false` for the rest
        * **`event`** Chokidar `event` corresponding to the file change

      Note: This is more meant for internal use. You may find other methods more useful.

    * **`.toArray()`** Returns an iterable of a modified `.files` object as: `{file, changed, event}` objects

      Eg.:

      ```js
      for(const file of files) {
        console.log(file)
      }
      ```
      ```
      {file: '/example/a', changed: false, event: 'add'}
      {file: '/example/b', changed: true,  event: 'change'}
      {file: '/example/c', changed: true,  event: 'add'}
      {file: '/example/d', changed: true,  event: 'unlink'}
      ```

    * **`.changed(events)`** Returns an iterable of files whose `.changed = true` and `.event` is one of the `events` provided

      * **`events = ['change', 'add']`** Events to match with the file's `.event`

      Eg.:

      ```js
      for(const file of files.changed()) {
        console.log(file)
      }
      ```
      ```
      /example/b
      /example/c
      ```

    * **`.deleted()`** Alias for `.changed(['unlink'])`

      Eg.:

      ```js
      for(const file of files.deleted()) {
        console.log(file)
      }
      ```
      ```
      /example/d
      ```

---
_Source: https://npm.io/package/file-watch-iterator · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._