@ms-cloudpack/file-watcher

An abstraction on the file watching capabilities used in Cloudpack.

Example usage

1. Create a watcher:

``ts
const watcher = createWatcher();
`

2. Subscribe to a particular package path using watch. (Returns an unwatch function.)

`ts
const unwatch = await watcher.watch({ path: 'path/to/package' }, () => console.log(package changed));
`

3. To dispose, call the returned unwatch, or call watcher.dispose to unsubscribe from all watchers.

`ts
// Dispose an individual watcher.
await unwatch();

// Dispose all watchers.
await watcher.dispose();
`

$3

- type ('default' | 'fork', optional): By default, this will create a watcher in the same thread. Use type: 'fork' to create the watcher in a forked process.
- backend ('default' | 'parcel', optional): Choose the file watching backend.
- 'default': Uses chokidar (default)
- 'parcel': Uses @parcel/watcher for better performance
- policies (optional): Enable performance optimizations
- 'shared-root': Multiplexes N package watches into 1 root watch (for monorepos with 100+ packages)
- 'debounce': Batches rapid file changes into single notifications

$3

For optimal performance when watching many packages (100+), use SharedRootWatcher - an orchestrator that wraps any watcher:

`ts
import { SharedRootWatcher, createWatcher } from '@ms-cloudpack/file-watcher';

// Create underlying watcher (can be any backend)
const underlyingWatcher = createWatcher({ backend: 'default' });

// Wrap it with SharedRootWatcher orchestrator
const watcher = new SharedRootWatcher(underlyingWatcher, '/path/to/monorepo');

// Watch multiple packages efficiently (single OS watcher)
await watcher.watch({ path: '/path/to/monorepo/packages/pkg1' }, onPkg1Change);
await watcher.watch({ path: '/path/to/monorepo/packages/pkg2' }, onPkg2Change);
// ... 1000+ packages
`

This uses a single file system watcher at the root instead of creating one per package.

With Parcel backend for maximum performance:

`ts
const underlyingWatcher = createWatcher({ backend: 'parcel' });
const watcher = new SharedRootWatcher(underlyingWatcher, '/path/to/monorepo');
`

$3

- path (string): The absolute root path to be watched.
- id (string, optional): ID for the watch job (defaults to path). If you call watch twice using the same id, subsequent calls will be ignored.
- watchPaths (string[], optional): Relative paths/globs from the root path. Currently, only negative globs (starting with !) are supported and will be used to ignore files. Positive globs are ignored - the watcher will watch all files in the root path by default. Defaults are under "@ms-cloudpack/path-utilities" in sourceFilesGlobs`.