https://github.com/lukeed/watchlist

Recursively watch a list of directories & run a command on any file system changes
https://github.com/lukeed/watchlist

Last synced: 5 months ago
JSON representation

Recursively watch a list of directories & run a command on any file system changes

• Host: GitHub
• URL: https://github.com/lukeed/watchlist
• Owner: lukeed
• License: mit
• Created: 2020-07-14T07:02:54.000Z (almost 5 years ago)
• Default Branch: master
• Last Pushed: 2022-10-26T21:02:40.000Z (over 2 years ago)
• Last Synced: 2024-11-03T13:05:41.121Z (6 months ago)
• Language: JavaScript
• Homepage:
• Size: 67.4 KB
• Stars: 262
• Watchers: 7
• Forks: 15
• Open Issues: 5
• Metadata Files:
  • Readme: readme.md
  • Funding: .github/FUNDING.yml
  • License: license

Awesome Lists containing this project

• awesome-list - watchlist
• jimsghstars - lukeed/watchlist - Recursively watch a list of directories & run a command on any file system changes (JavaScript)

README

        


  





  

    

  

  

    

  

  

    

  

  

    

  





  Recursively watch a list of directories & run a command on any file system changes



## Features

* Extremely lightweight

* Simple [`fs.watch`](https://nodejs.org/api/fs.html#fs_fs_watch_filename_options_listener) wrapper†

* Runs on macOS, Linux, and Windows

* Recursively monitors all subdirectories

* Optional ignore patterns

> † While `fs.watch` has its inconsistencies, efforts are made to normalize behavior across platforms.

## Install

```

$ npm install --save-dev watchlist

```

## Usage

***CLI***

```sh

# Run `npm test` on changes within "src" and "test" contents change

$ watchlist src test -- npm test

# Run `npm test` on changes within "packages", ignoring /fixtures/i

$ watchlist packages --ignore fixtures -- npm test

# Run `lint` script on ANY change

$ watchlist -- npm run lint

```

***API***

```js

import { watch } from 'watchlist';

async function task() {

  console.log('~> something updated!');

  await execute_example(); // linter, tests, build, etc

}

// Run `task()` when "{src,test}/**/*" changes

// Must also ignore changes to any `/fixture/i` match

await watch(['src', 'test'], task, {

  ignore: 'fixtures'

});

```

## CLI

The `watchlist` binary expects the following usage:

```sh

$ watchlist [...directory] [options] -- 

```

> **Important:** The `--` is required! It separates your `command` from your `watchlist` arguments.

Please run `watchlist --help` for additional information.

## API

### watch(dirs: string[], handler: Function, options?: Options)

Returns: `Promise`

Watch a list of directories recursively, calling `handler` whenever their contents are modified.

#### dirs

Type: `Array`

The list of directories to watch.

May be relative or absolute paths. 
All paths are resolved from the `opts.cwd` location.

#### handler

Type: `Function`

The callback function to run.

> **Note:** This may be a Promise/`async` function. Return values are ignored.

#### options.cwd

Type: `String`


Default: `.`

The current working directory. All paths are resolved from this location. 
Defaults to `process.cwd()`.

#### options.ignore

Type: `String` or `RegExp` or `Array`

A list of patterns that should **not** be watched nor should trigger a `handler` execution. 
Ignore patterns are applied to file and directory paths alike.

> **Note:** Any `String` values will be converted into a `RegExp` automatically.

#### options.clear

Type: `Boolean`


Default: `false`

Whether or not the `console` should be cleared before re-running your `handler` function.

> **Note:** Defaults to `true` for the CLI! Pass `--no-clear` to disable.

#### options.eager

Type: `Boolean`


Default: `false`

When enabled, runs the `command` one time, after `watchlist` has initialized. When disabled, a change within the `dirs` list must be observed before the first `command` execution.

### run(command: string, ...args)

Returns: `Promise`

All arguments to `watchlist.run` are passed to [`child_process.exec`][child_exec] directly.

> **Note:** Any `stdout` or `stderr` content will be piped/forwarded to your console.

#### command

Type: `String`

The command string to execute. 
View [`child_process.exec`][child_exec] for more information.

#### args

Type: `String`

Additional [`child_process.exec`][child_exec] arguments.

> **Important:** The `callback` argument is not available!

## License

MIT © [Luke Edwards](https://lukeed.com)

[child_exec]: https://nodejs.org/api/child_process.html#child_process_child_process_exec_command_options_callback