@ms-cloudpack/file-watcher 0.4.19 → 0.4.20

package/README.md

@@ -29,6 +29,40 @@ await watcher.dispose();
 ### `createWatcher` options
 
 - `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
+
+### Shared Root Watcher for Large Monorepos
+
+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');
+```
 
 ### `watcher.watch` options
 

package/lib/DebouncedWatcher.d.ts

@@ -0,0 +1,50 @@
+import type { UnwatchCallback, WatchChangeCallback, Watcher, WatchOptions } from './types/Watcher.js';
+/**
+ * Decorator that adds debouncing/batching to any Watcher implementation.
+ *
+ * Uses a hybrid flush strategy:
+ * - First change: immediate flush (0ms latency)
+ * - Subsequent changes within debounce window: batched together
+ * - After debounce window expires: returns to immediate flush mode
+ *
+ * This provides zero-latency for single file saves while efficiently batching
+ * bulk operations (git checkout, npm install, etc.).
+ *
+ * @example
+ * ```typescript
+ * // Debounce any watcher
+ * const watcher = new DebouncedWatcher(new DefaultWatcher(), { debounceMs: 10 });
+ *
+ * // Compose with SharedRootWatcher
+ * const shared = new SharedRootWatcher(new DefaultWatcher(), '/monorepo');
+ * const debounced = new DebouncedWatcher(shared, { debounceMs: 10 });
+ * ```
+ */
+export declare class DebouncedWatcher implements Watcher {
+    private _watcher;
+    private _debounceMs;
+    private _subscribers;
+    /**
+     * @param watcher - The watcher to wrap with debouncing
+     * @param options - Configuration options
+     * @param options.debounceMs - Debounce delay in milliseconds (default: 10ms)
+     */
+    constructor(watcher: Watcher, options?: {
+        debounceMs?: number;
+    });
+    watch(options: WatchOptions, onChange: WatchChangeCallback): Promise<UnwatchCallback>;
+    unwatch(id: string): Promise<void>;
+    dispose(): Promise<void>;
+    /**
+     * Add changed paths to pending notifications for a subscriber.
+     * Implements hybrid flush strategy:
+     * - Idle state (no timer): flush immediately, start timer
+     * - Debouncing state (timer active): accumulate, reset timer
+     */
+    private _addPending;
+    /**
+     * Flush pending notifications for a subscriber and clear its state.
+     */
+    private _flushSubscriber;
+}
+//# sourceMappingURL=DebouncedWatcher.d.ts.map

package/lib/DebouncedWatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DebouncedWatcher.d.ts","sourceRoot":"","sources":["../src/DebouncedWatcher.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,mBAAmB,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAWtG;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,gBAAiB,YAAW,OAAO;IAC9C,OAAO,CAAC,QAAQ,CAAU;IAC1B,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,YAAY,CAAsC;IAE1D;;;;OAIG;gBACS,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE;IAKzD,KAAK,CAAC,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,mBAAmB,GAAG,OAAO,CAAC,eAAe,CAAC;IAmBrF,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMlC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAS9B;;;;;OAKG;IACH,OAAO,CAAC,WAAW;IA2BnB;;OAEG;IACH,OAAO,CAAC,gBAAgB;CAYzB"}

package/lib/DebouncedWatcher.js

@@ -0,0 +1,108 @@
+/**
+ * Decorator that adds debouncing/batching to any Watcher implementation.
+ *
+ * Uses a hybrid flush strategy:
+ * - First change: immediate flush (0ms latency)
+ * - Subsequent changes within debounce window: batched together
+ * - After debounce window expires: returns to immediate flush mode
+ *
+ * This provides zero-latency for single file saves while efficiently batching
+ * bulk operations (git checkout, npm install, etc.).
+ *
+ * @example
+ * ```typescript
+ * // Debounce any watcher
+ * const watcher = new DebouncedWatcher(new DefaultWatcher(), { debounceMs: 10 });
+ *
+ * // Compose with SharedRootWatcher
+ * const shared = new SharedRootWatcher(new DefaultWatcher(), '/monorepo');
+ * const debounced = new DebouncedWatcher(shared, { debounceMs: 10 });
+ * ```
+ */
+export class DebouncedWatcher {
+    _watcher;
+    _debounceMs;
+    _subscribers = new Map();
+    /**
+     * @param watcher - The watcher to wrap with debouncing
+     * @param options - Configuration options
+     * @param options.debounceMs - Debounce delay in milliseconds (default: 10ms)
+     */
+    constructor(watcher, options) {
+        this._watcher = watcher;
+        this._debounceMs = options?.debounceMs ?? 10;
+    }
+    async watch(options, onChange) {
+        const { id = options.path } = options;
+        // Wrap the user's callback with debouncing logic
+        const debouncedCallback = (changedPaths) => {
+            this._addPending(id, changedPaths, onChange);
+        };
+        // Delegate to wrapped watcher
+        const unwatch = await this._watcher.watch(options, debouncedCallback);
+        // Return unwatch callback that flushes pending and cleans up
+        return async () => {
+            this._flushSubscriber(id);
+            this._subscribers.delete(id);
+            await unwatch();
+        };
+    }
+    async unwatch(id) {
+        this._flushSubscriber(id);
+        this._subscribers.delete(id);
+        await this._watcher.unwatch(id);
+    }
+    async dispose() {
+        // Flush all pending notifications before disposing
+        for (const id of this._subscribers.keys()) {
+            this._flushSubscriber(id);
+        }
+        this._subscribers.clear();
+        await this._watcher.dispose();
+    }
+    /**
+     * Add changed paths to pending notifications for a subscriber.
+     * Implements hybrid flush strategy:
+     * - Idle state (no timer): flush immediately, start timer
+     * - Debouncing state (timer active): accumulate, reset timer
+     */
+    _addPending(id, changedPaths, callback) {
+        let state = this._subscribers.get(id);
+        if (!state) {
+            state = { callback, pendingPaths: new Set() };
+            this._subscribers.set(id, state);
+        }
+        // Hybrid flush strategy
+        if (!state.flushTimer && state.pendingPaths.size === 0) {
+            // Idle state - flush immediately (zero latency)
+            callback(changedPaths);
+            // Start timer to enable debouncing for subsequent rapid changes
+            state.flushTimer = setTimeout(() => {
+                state.flushTimer = undefined;
+            }, this._debounceMs);
+        }
+        else {
+            // Debouncing state - accumulate paths and reset timer
+            changedPaths.forEach((p) => state.pendingPaths.add(p));
+            clearTimeout(state.flushTimer);
+            state.flushTimer = setTimeout(() => {
+                this._flushSubscriber(id);
+            }, this._debounceMs);
+        }
+    }
+    /**
+     * Flush pending notifications for a subscriber and clear its state.
+     */
+    _flushSubscriber(id) {
+        const state = this._subscribers.get(id);
+        if (!state)
+            return;
+        clearTimeout(state.flushTimer);
+        state.flushTimer = undefined;
+        if (state.pendingPaths.size > 0) {
+            state.callback(Array.from(state.pendingPaths));
+            state.pendingPaths.clear();
+        }
+    }
+}
+//# sourceMappingURL=DebouncedWatcher.js.map

package/lib/DebouncedWatcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DebouncedWatcher.js","sourceRoot":"","sources":["../src/DebouncedWatcher.ts"],"names":[],"mappings":"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","sourcesContent":["import type { UnwatchCallback, WatchChangeCallback, Watcher, WatchOptions } from './types/Watcher.js';\n\ninterface SubscriberState {\n  /** Original callback provided by the user */\n  callback: WatchChangeCallback;\n  /** Paths accumulated during debouncing */\n  pendingPaths: Set<string>;\n  /** Timer for debouncing subsequent changes */\n  flushTimer?: NodeJS.Timeout;\n}\n\n/**\n * Decorator that adds debouncing/batching to any Watcher implementation.\n *\n * Uses a hybrid flush strategy:\n * - First change: immediate flush (0ms latency)\n * - Subsequent changes within debounce window: batched together\n * - After debounce window expires: returns to immediate flush mode\n *\n * This provides zero-latency for single file saves while efficiently batching\n * bulk operations (git checkout, npm install, etc.).\n *\n * @example\n * ```typescript\n * // Debounce any watcher\n * const watcher = new DebouncedWatcher(new DefaultWatcher(), { debounceMs: 10 });\n *\n * // Compose with SharedRootWatcher\n * const shared = new SharedRootWatcher(new DefaultWatcher(), '/monorepo');\n * const debounced = new DebouncedWatcher(shared, { debounceMs: 10 });\n * ```\n */\nexport class DebouncedWatcher implements Watcher {\n  private _watcher: Watcher;\n  private _debounceMs: number;\n  private _subscribers = new Map<string, SubscriberState>();\n\n  /**\n   * @param watcher - The watcher to wrap with debouncing\n   * @param options - Configuration options\n   * @param options.debounceMs - Debounce delay in milliseconds (default: 10ms)\n   */\n  constructor(watcher: Watcher, options?: { debounceMs?: number }) {\n    this._watcher = watcher;\n    this._debounceMs = options?.debounceMs ?? 10;\n  }\n\n  async watch(options: WatchOptions, onChange: WatchChangeCallback): Promise<UnwatchCallback> {\n    const { id = options.path } = options;\n\n    // Wrap the user's callback with debouncing logic\n    const debouncedCallback = (changedPaths: string[]) => {\n      this._addPending(id, changedPaths, onChange);\n    };\n\n    // Delegate to wrapped watcher\n    const unwatch = await this._watcher.watch(options, debouncedCallback);\n\n    // Return unwatch callback that flushes pending and cleans up\n    return async () => {\n      this._flushSubscriber(id);\n      this._subscribers.delete(id);\n      await unwatch();\n    };\n  }\n\n  async unwatch(id: string): Promise<void> {\n    this._flushSubscriber(id);\n    this._subscribers.delete(id);\n    await this._watcher.unwatch(id);\n  }\n\n  async dispose(): Promise<void> {\n    // Flush all pending notifications before disposing\n    for (const id of this._subscribers.keys()) {\n      this._flushSubscriber(id);\n    }\n    this._subscribers.clear();\n    await this._watcher.dispose();\n  }\n\n  /**\n   * Add changed paths to pending notifications for a subscriber.\n   * Implements hybrid flush strategy:\n   * - Idle state (no timer): flush immediately, start timer\n   * - Debouncing state (timer active): accumulate, reset timer\n   */\n  private _addPending(id: string, changedPaths: string[], callback: WatchChangeCallback): void {\n    let state = this._subscribers.get(id);\n    if (!state) {\n      state = { callback, pendingPaths: new Set() };\n      this._subscribers.set(id, state);\n    }\n\n    // Hybrid flush strategy\n    if (!state.flushTimer && state.pendingPaths.size === 0) {\n      // Idle state - flush immediately (zero latency)\n      callback(changedPaths);\n\n      // Start timer to enable debouncing for subsequent rapid changes\n      state.flushTimer = setTimeout(() => {\n        state.flushTimer = undefined;\n      }, this._debounceMs);\n    } else {\n      // Debouncing state - accumulate paths and reset timer\n      changedPaths.forEach((p) => state.pendingPaths.add(p));\n\n      clearTimeout(state.flushTimer);\n      state.flushTimer = setTimeout(() => {\n        this._flushSubscriber(id);\n      }, this._debounceMs);\n    }\n  }\n\n  /**\n   * Flush pending notifications for a subscriber and clear its state.\n   */\n  private _flushSubscriber(id: string): void {\n    const state = this._subscribers.get(id);\n    if (!state) return;\n\n    clearTimeout(state.flushTimer);\n    state.flushTimer = undefined;\n\n    if (state.pendingPaths.size > 0) {\n      state.callback(Array.from(state.pendingPaths));\n      state.pendingPaths.clear();\n    }\n  }\n}\n"]}

package/lib/ForkWatcher.d.ts

@@ -1,11 +1,15 @@
 import type { Backend, UnwatchCallback, WatchOptions } from './types/Watcher.js';
+import type { WatcherPolicies } from './types/WatcherPolicy.js';
 import { BaseWatcher } from './BaseWatcher.js';
 /**
  * Creates a watcher in a fork which can watch a package and notify the client when it changes.
+ *
+ * Policies (shared-root, debounce) are applied inside the child process for better performance
+ * and reduced IPC message overhead.
  */
 export declare class ForkWatcher extends BaseWatcher {
     private _child;
-    constructor(backend?: Backend);
+    constructor(backend?: Backend, policies?: WatcherPolicies);
     protected _watch(options: Required<WatchOptions>): UnwatchCallback;
     protected _dispose(): Promise<void>;
     protected _isDisposed(): boolean;

package/lib/ForkWatcher.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ForkWatcher.d.ts","sourceRoot":"","sources":["../src/ForkWatcher.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACjF,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAK/C;;GAEG;AACH,qBAAa,WAAY,SAAQ,WAAW;IAC1C,OAAO,CAAC,MAAM,CAA2B;gBAE7B,OAAO,GAAE,OAAmB;IAuBxC,SAAS,CAAC,MAAM,CAAC,OAAO,EAAE,QAAQ,CAAC,YAAY,CAAC,GAAG,eAAe;cAQlD,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAYzC,SAAS,CAAC,WAAW,IAAI,OAAO;IAIhC,6EAA6E;IAC7E,OAAO,CAAC,YAAY;CAOrB"}
+{"version":3,"file":"ForkWatcher.d.ts","sourceRoot":"","sources":["../src/ForkWatcher.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACjF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAK/C;;;;;GAKG;AACH,qBAAa,WAAY,SAAQ,WAAW;IAC1C,OAAO,CAAC,MAAM,CAA2B;gBAE7B,OAAO,GAAE,OAAmB,EAAE,QAAQ,CAAC,EAAE,eAAe;IAyBpE,SAAS,CAAC,MAAM,CAAC,OAAO,EAAE,QAAQ,CAAC,YAAY,CAAC,GAAG,eAAe;cAQlD,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAYzC,SAAS,CAAC,WAAW,IAAI,OAAO;IAIhC,6EAA6E;IAC7E,OAAO,CAAC,YAAY;CAOrB"}

package/lib/ForkWatcher.js

@@ -6,12 +6,17 @@ const currentDir = path.dirname(fileURLToPath(import.meta.url));
 const watcherForkWrapper = path.resolve(currentDir, 'watcherForkWrapper.js');
 /**
  * Creates a watcher in a fork which can watch a package and notify the client when it changes.
+ *
+ * Policies (shared-root, debounce) are applied inside the child process for better performance
+ * and reduced IPC message overhead.
  */
 export class ForkWatcher extends BaseWatcher {
     _child;
-    constructor(backend = 'default') {
+    constructor(backend = 'default', policies) {
         super();
-        this._child = fork(watcherForkWrapper, [backend]);
+        // Pass backend and serialized policies to child process
+        const args = [backend, JSON.stringify(policies || {})];
+        this._child = fork(watcherForkWrapper, args);
         this._child.on('message', (message) => {
             switch (message.type) {
                 case 'change':

package/lib/ForkWatcher.js.map

@@ -1 +1 @@
-{"version":3,"file":"ForkWatcher.js","sourceRoot":"","sources":["../src/ForkWatcher.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,EAAE,IAAI,EAAqB,MAAM,eAAe,CAAC;AACxD,OAAO,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC;AAGpC,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAE/C,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAChE,MAAM,kBAAkB,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,uBAAuB,CAAC,CAAC;AAE7E;;GAEG;AACH,MAAM,OAAO,WAAY,SAAQ,WAAW;IAClC,MAAM,CAA2B;IAEzC,YAAY,UAAmB,SAAS;QACtC,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,kBAAkB,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;QAElD,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC,OAAqB,EAAE,EAAE;YAClD,QAAQ,OAAO,CAAC,IAAI,EAAE,CAAC;gBACrB,KAAK,QAAQ;oBACX,IAAI,IAAI,CAAC,WAAW,EAAE,EAAE,CAAC;wBACvB,MAAM,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAAC;oBAChD,CAAC;oBACD,IAAI,CAAC,kBAAkB,CAAC,OAAO,CAAC,EAAE,CAAC,EAAE,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;oBAC5D,MAAM;gBAER,KAAK,OAAO;oBACV,OAAO,CAAC,KAAK,CAAC,2CAA2C,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;oBAC1E,MAAM;gBAER;oBACE,OAAO,CAAC,IAAI,CAAC,yBAAyB,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;YACrE,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC;IAES,MAAM,CAAC,OAA+B;QAC9C,IAAI,CAAC,YAAY,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC;QAE9C,OAAO,GAAG,EAAE;YACV,IAAI,CAAC,YAAY,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,OAAO,CAAC,EAAE,EAAE,CAAC,CAAC;QACzD,CAAC,CAAC;IACJ,CAAC;IAES,KAAK,CAAC,QAAQ;QACtB,MAAM,IAAI,OAAO,CAAO,CAAC,CAAC,EAAE,EAAE;YAC5B,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;gBACjB,OAAO,CAAC,EAAE,CAAC;YACb,CAAC;YAED,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;YAC3B,IAAI,CAAC,YAAY,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,CAAC;YACxC,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC;QAC1B,CAAC,CAAC,CAAC;IACL,CAAC;IAES,WAAW;QACnB,OAAO,CAAC,IAAI,CAAC,MAAM,IAAI,KAAK,CAAC,WAAW,EAAE,CAAC;IAC7C,CAAC;IAED,6EAA6E;IACrE,YAAY,CAAC,OAAsB;QACzC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE;YACnC,IAAI,KAAK,EAAE,CAAC;gBACV,OAAO,CAAC,KAAK,CAAC,0DAA0D,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;YAC3F,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC;CACF","sourcesContent":["import path from 'path';\nimport { fork, type ChildProcess } from 'child_process';\nimport { fileURLToPath } from 'url';\nimport type { ChildMessage, ParentMessage } from './types/WatchMessages.js';\nimport type { Backend, UnwatchCallback, WatchOptions } from './types/Watcher.js';\nimport { BaseWatcher } from './BaseWatcher.js';\n\nconst currentDir = path.dirname(fileURLToPath(import.meta.url));\nconst watcherForkWrapper = path.resolve(currentDir, 'watcherForkWrapper.js');\n\n/**\n * Creates a watcher in a fork which can watch a package and notify the client when it changes.\n */\nexport class ForkWatcher extends BaseWatcher {\n  private _child: ChildProcess | undefined;\n\n  constructor(backend: Backend = 'default') {\n    super();\n    this._child = fork(watcherForkWrapper, [backend]);\n\n    this._child.on('message', (message: ChildMessage) => {\n      switch (message.type) {\n        case 'change':\n          if (this._isDisposed()) {\n            throw new Error('Watcher has been disposed.');\n          }\n          this._onChangeCallbacks[message.id]?.(message.changedPaths);\n          break;\n\n        case 'error':\n          console.error(`An error occurred while watching files: ${message.error}`);\n          break;\n\n        default:\n          console.warn(`Unknown message type: ${JSON.stringify(message)}`);\n      }\n    });\n  }\n\n  protected _watch(options: Required<WatchOptions>): UnwatchCallback {\n    this._sendMessage({ type: 'watch', options });\n\n    return () => {\n      this._sendMessage({ type: 'unwatch', id: options.id });\n    };\n  }\n\n  protected async _dispose(): Promise<void> {\n    await new Promise<void>((r) => {\n      if (!this._child) {\n        return r();\n      }\n\n      this._child.on('close', r);\n      this._sendMessage({ type: 'shutdown' });\n      this._child = undefined;\n    });\n  }\n\n  protected _isDisposed(): boolean {\n    return !this._child || super._isDisposed();\n  }\n\n  /** Typed wrapper for `this._child.send()`. No-op if `_child` is disposed. */\n  private _sendMessage(message: ParentMessage): void {\n    this._child?.send(message, (error) => {\n      if (error) {\n        console.error(`Failed to send message to file watcher process. Error: ${error.message}`);\n      }\n    });\n  }\n}\n"]}
+{"version":3,"file":"ForkWatcher.js","sourceRoot":"","sources":["../src/ForkWatcher.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,EAAE,IAAI,EAAqB,MAAM,eAAe,CAAC;AACxD,OAAO,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC;AAIpC,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAE/C,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAChE,MAAM,kBAAkB,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,uBAAuB,CAAC,CAAC;AAE7E;;;;;GAKG;AACH,MAAM,OAAO,WAAY,SAAQ,WAAW;IAClC,MAAM,CAA2B;IAEzC,YAAY,UAAmB,SAAS,EAAE,QAA0B;QAClE,KAAK,EAAE,CAAC;QACR,wDAAwD;QACxD,MAAM,IAAI,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,CAAC;QACvD,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,kBAAkB,EAAE,IAAI,CAAC,CAAC;QAE7C,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC,OAAqB,EAAE,EAAE;YAClD,QAAQ,OAAO,CAAC,IAAI,EAAE,CAAC;gBACrB,KAAK,QAAQ;oBACX,IAAI,IAAI,CAAC,WAAW,EAAE,EAAE,CAAC;wBACvB,MAAM,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAAC;oBAChD,CAAC;oBACD,IAAI,CAAC,kBAAkB,CAAC,OAAO,CAAC,EAAE,CAAC,EAAE,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;oBAC5D,MAAM;gBAER,KAAK,OAAO;oBACV,OAAO,CAAC,KAAK,CAAC,2CAA2C,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;oBAC1E,MAAM;gBAER;oBACE,OAAO,CAAC,IAAI,CAAC,yBAAyB,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;YACrE,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC;IAES,MAAM,CAAC,OAA+B;QAC9C,IAAI,CAAC,YAAY,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC;QAE9C,OAAO,GAAG,EAAE;YACV,IAAI,CAAC,YAAY,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,OAAO,CAAC,EAAE,EAAE,CAAC,CAAC;QACzD,CAAC,CAAC;IACJ,CAAC;IAES,KAAK,CAAC,QAAQ;QACtB,MAAM,IAAI,OAAO,CAAO,CAAC,CAAC,EAAE,EAAE;YAC5B,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;gBACjB,OAAO,CAAC,EAAE,CAAC;YACb,CAAC;YAED,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;YAC3B,IAAI,CAAC,YAAY,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,CAAC;YACxC,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC;QAC1B,CAAC,CAAC,CAAC;IACL,CAAC;IAES,WAAW;QACnB,OAAO,CAAC,IAAI,CAAC,MAAM,IAAI,KAAK,CAAC,WAAW,EAAE,CAAC;IAC7C,CAAC;IAED,6EAA6E;IACrE,YAAY,CAAC,OAAsB;QACzC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE;YACnC,IAAI,KAAK,EAAE,CAAC;gBACV,OAAO,CAAC,KAAK,CAAC,0DAA0D,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;YAC3F,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC;CACF","sourcesContent":["import path from 'path';\nimport { fork, type ChildProcess } from 'child_process';\nimport { fileURLToPath } from 'url';\nimport type { ChildMessage, ParentMessage } from './types/WatchMessages.js';\nimport type { Backend, UnwatchCallback, WatchOptions } from './types/Watcher.js';\nimport type { WatcherPolicies } from './types/WatcherPolicy.js';\nimport { BaseWatcher } from './BaseWatcher.js';\n\nconst currentDir = path.dirname(fileURLToPath(import.meta.url));\nconst watcherForkWrapper = path.resolve(currentDir, 'watcherForkWrapper.js');\n\n/**\n * Creates a watcher in a fork which can watch a package and notify the client when it changes.\n *\n * Policies (shared-root, debounce) are applied inside the child process for better performance\n * and reduced IPC message overhead.\n */\nexport class ForkWatcher extends BaseWatcher {\n  private _child: ChildProcess | undefined;\n\n  constructor(backend: Backend = 'default', policies?: WatcherPolicies) {\n    super();\n    // Pass backend and serialized policies to child process\n    const args = [backend, JSON.stringify(policies || {})];\n    this._child = fork(watcherForkWrapper, args);\n\n    this._child.on('message', (message: ChildMessage) => {\n      switch (message.type) {\n        case 'change':\n          if (this._isDisposed()) {\n            throw new Error('Watcher has been disposed.');\n          }\n          this._onChangeCallbacks[message.id]?.(message.changedPaths);\n          break;\n\n        case 'error':\n          console.error(`An error occurred while watching files: ${message.error}`);\n          break;\n\n        default:\n          console.warn(`Unknown message type: ${JSON.stringify(message)}`);\n      }\n    });\n  }\n\n  protected _watch(options: Required<WatchOptions>): UnwatchCallback {\n    this._sendMessage({ type: 'watch', options });\n\n    return () => {\n      this._sendMessage({ type: 'unwatch', id: options.id });\n    };\n  }\n\n  protected async _dispose(): Promise<void> {\n    await new Promise<void>((r) => {\n      if (!this._child) {\n        return r();\n      }\n\n      this._child.on('close', r);\n      this._sendMessage({ type: 'shutdown' });\n      this._child = undefined;\n    });\n  }\n\n  protected _isDisposed(): boolean {\n    return !this._child || super._isDisposed();\n  }\n\n  /** Typed wrapper for `this._child.send()`. No-op if `_child` is disposed. */\n  private _sendMessage(message: ParentMessage): void {\n    this._child?.send(message, (error) => {\n      if (error) {\n        console.error(`Failed to send message to file watcher process. Error: ${error.message}`);\n      }\n    });\n  }\n}\n"]}

package/lib/MockWatcher.d.ts

@@ -0,0 +1,26 @@
+import type { UnwatchCallback, WatchChangeCallback, Watcher, WatchOptions } from './types/Watcher.js';
+/**
+ * Mock watcher for testing purposes.
+ * Allows manual triggering of file change events without actual file system watching.
+ */
+export declare class MockWatcher implements Watcher {
+    private _watches;
+    private _isDisposed;
+    watch(options: WatchOptions, onChange: WatchChangeCallback): Promise<UnwatchCallback>;
+    unwatch(id: string): Promise<void>;
+    dispose(): Promise<void>;
+    /**
+     * Manually trigger a file change event for testing.
+     * This will call all registered onChange callbacks that match the given path.
+     */
+    triggerChange(changedPaths: string[]): void;
+    /**
+     * Get the number of active watches (for testing)
+     */
+    get watchCount(): number;
+    /**
+     * Check if a specific path is being watched (for testing)
+     */
+    isWatching(id: string): boolean;
+}
+//# sourceMappingURL=MockWatcher.d.ts.map

package/lib/MockWatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MockWatcher.d.ts","sourceRoot":"","sources":["../src/MockWatcher.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,mBAAmB,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEtG;;;GAGG;AACH,qBAAa,WAAY,YAAW,OAAO;IACzC,OAAO,CAAC,QAAQ,CAA0C;IAC1D,OAAO,CAAC,WAAW,CAAS;IAE5B,KAAK,CAAC,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,mBAAmB,GAAG,OAAO,CAAC,eAAe,CAAC;IAarF,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKlC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAMxB;;;OAGG;IACH,aAAa,CAAC,YAAY,EAAE,MAAM,EAAE,GAAG,IAAI;IAW3C;;OAEG;IACH,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED;;OAEG;IACH,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;CAGhC"}

package/lib/MockWatcher.js

@@ -0,0 +1,53 @@
+/**
+ * Mock watcher for testing purposes.
+ * Allows manual triggering of file change events without actual file system watching.
+ */
+export class MockWatcher {
+    _watches = new Map();
+    _isDisposed = false;
+    watch(options, onChange) {
+        if (this._isDisposed) {
+            throw new Error('MockWatcher has been disposed');
+        }
+        const { id = options.path } = options;
+        this._watches.set(id, onChange);
+        return Promise.resolve(() => {
+            this._watches.delete(id);
+        });
+    }
+    unwatch(id) {
+        this._watches.delete(id);
+        return Promise.resolve();
+    }
+    dispose() {
+        this._isDisposed = true;
+        this._watches.clear();
+        return Promise.resolve();
+    }
+    /**
+     * Manually trigger a file change event for testing.
+     * This will call all registered onChange callbacks that match the given path.
+     */
+    triggerChange(changedPaths) {
+        if (this._isDisposed) {
+            throw new Error('MockWatcher has been disposed');
+        }
+        // Call all watch callbacks (in real scenario, filtering would happen in underlying watcher)
+        for (const callback of this._watches.values()) {
+            callback(changedPaths);
+        }
+    }
+    /**
+     * Get the number of active watches (for testing)
+     */
+    get watchCount() {
+        return this._watches.size;
+    }
+    /**
+     * Check if a specific path is being watched (for testing)
+     */
+    isWatching(id) {
+        return this._watches.has(id);
+    }
+}
+//# sourceMappingURL=MockWatcher.js.map

package/lib/MockWatcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MockWatcher.js","sourceRoot":"","sources":["../src/MockWatcher.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,OAAO,WAAW;IACd,QAAQ,GAAG,IAAI,GAAG,EAA+B,CAAC;IAClD,WAAW,GAAG,KAAK,CAAC;IAE5B,KAAK,CAAC,OAAqB,EAAE,QAA6B;QACxD,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACrB,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAC;QACnD,CAAC;QAED,MAAM,EAAE,EAAE,GAAG,OAAO,CAAC,IAAI,EAAE,GAAG,OAAO,CAAC;QACtC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC;QAEhC,OAAO,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE;YAC1B,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QAC3B,CAAC,CAAC,CAAC;IACL,CAAC;IAED,OAAO,CAAC,EAAU;QAChB,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACzB,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;IAC3B,CAAC;IAED,OAAO;QACL,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;QACxB,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;QACtB,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;IAC3B,CAAC;IAED;;;OAGG;IACH,aAAa,CAAC,YAAsB;QAClC,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACrB,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAC;QACnD,CAAC;QAED,4FAA4F;QAC5F,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,EAAE,CAAC;YAC9C,QAAQ,CAAC,YAAY,CAAC,CAAC;QACzB,CAAC;IACH,CAAC;IAED;;OAEG;IACH,IAAI,UAAU;QACZ,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;IAC5B,CAAC;IAED;;OAEG;IACH,UAAU,CAAC,EAAU;QACnB,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC/B,CAAC;CACF","sourcesContent":["import type { UnwatchCallback, WatchChangeCallback, Watcher, WatchOptions } from './types/Watcher.js';\n\n/**\n * Mock watcher for testing purposes.\n * Allows manual triggering of file change events without actual file system watching.\n */\nexport class MockWatcher implements Watcher {\n  private _watches = new Map<string, WatchChangeCallback>();\n  private _isDisposed = false;\n\n  watch(options: WatchOptions, onChange: WatchChangeCallback): Promise<UnwatchCallback> {\n    if (this._isDisposed) {\n      throw new Error('MockWatcher has been disposed');\n    }\n\n    const { id = options.path } = options;\n    this._watches.set(id, onChange);\n\n    return Promise.resolve(() => {\n      this._watches.delete(id);\n    });\n  }\n\n  unwatch(id: string): Promise<void> {\n    this._watches.delete(id);\n    return Promise.resolve();\n  }\n\n  dispose(): Promise<void> {\n    this._isDisposed = true;\n    this._watches.clear();\n    return Promise.resolve();\n  }\n\n  /**\n   * Manually trigger a file change event for testing.\n   * This will call all registered onChange callbacks that match the given path.\n   */\n  triggerChange(changedPaths: string[]): void {\n    if (this._isDisposed) {\n      throw new Error('MockWatcher has been disposed');\n    }\n\n    // Call all watch callbacks (in real scenario, filtering would happen in underlying watcher)\n    for (const callback of this._watches.values()) {\n      callback(changedPaths);\n    }\n  }\n\n  /**\n   * Get the number of active watches (for testing)\n   */\n  get watchCount(): number {\n    return this._watches.size;\n  }\n\n  /**\n   * Check if a specific path is being watched (for testing)\n   */\n  isWatching(id: string): boolean {\n    return this._watches.has(id);\n  }\n}\n"]}

package/lib/SharedRootWatcher.d.ts

@@ -0,0 +1,32 @@
+import type { UnwatchCallback, WatchChangeCallback, Watcher, WatchOptionsWithId } from './types/Watcher.js';
+import { BaseWatcher } from './BaseWatcher.js';
+/**
+ * Orchestrator that wraps an existing watcher to efficiently handle many watch paths (100+).
+ *
+ * Instead of creating N watchers for N packages, this creates a single watch at the root
+ * and routes events to subscribers based on path matching.
+ *
+ * This is a decorator pattern - it takes any Watcher implementation and multiplexes it.
+ */
+export declare class SharedRootWatcher extends BaseWatcher {
+    private _watcher;
+    private _rootUnwatch?;
+    private _subscribers;
+    private _pathIndex;
+    private _rootPath;
+    private _isInitialized;
+    /**
+     * @param watcher - The underlying watcher to orchestrate (can be DefaultWatcher, ParcelWatcher, or ForkWatcher)
+     * @param rootPath - The root path to watch (typically the monorepo root)
+     */
+    constructor(watcher: Watcher, rootPath: string);
+    protected _watch(options: WatchOptionsWithId, onChange: WatchChangeCallback): Promise<UnwatchCallback>;
+    protected _dispose(): Promise<void>;
+    private _initializeRootWatcher;
+    private _findRelevantSubscribers;
+    private _handleFileChanges;
+    private _shouldNotifySubscriber;
+    /** Get number of subscribers (for testing/debugging) */
+    get subscriberCount(): number;
+}
+//# sourceMappingURL=SharedRootWatcher.d.ts.map

package/lib/SharedRootWatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SharedRootWatcher.d.ts","sourceRoot":"","sources":["../src/SharedRootWatcher.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,mBAAmB,EAAE,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAC5G,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAqB/C;;;;;;;GAOG;AACH,qBAAa,iBAAkB,SAAQ,WAAW;IAChD,OAAO,CAAC,QAAQ,CAAU;IAC1B,OAAO,CAAC,YAAY,CAAC,CAAkB;IACvC,OAAO,CAAC,YAAY,CAAiC;IACrD,OAAO,CAAC,UAAU,CAAkC;IACpD,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,cAAc,CAAS;IAE/B;;;OAGG;gBACS,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM;cAM9B,MAAM,CAAC,OAAO,EAAE,kBAAkB,EAAE,QAAQ,EAAE,mBAAmB,GAAG,OAAO,CAAC,eAAe,CAAC;cAqE5F,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;YAS3B,sBAAsB;IAYpC,OAAO,CAAC,wBAAwB;IA4BhC,OAAO,CAAC,kBAAkB;IAiB1B,OAAO,CAAC,uBAAuB;IAuB/B,wDAAwD;IACxD,IAAW,eAAe,IAAI,MAAM,CAEnC;CACF"}

package/lib/SharedRootWatcher.js

@@ -0,0 +1,166 @@
+import path from 'path';
+import picomatch from 'picomatch';
+import { BaseWatcher } from './BaseWatcher.js';
+import { sourceFilesGlobs } from '@ms-cloudpack/path-utilities';
+import { slash } from '@ms-cloudpack/path-string-parsing';
+import { separateGlobs } from './separateGlobs.js';
+/**
+ * Orchestrator that wraps an existing watcher to efficiently handle many watch paths (100+).
+ *
+ * Instead of creating N watchers for N packages, this creates a single watch at the root
+ * and routes events to subscribers based on path matching.
+ *
+ * This is a decorator pattern - it takes any Watcher implementation and multiplexes it.
+ */
+export class SharedRootWatcher extends BaseWatcher {
+    _watcher;
+    _rootUnwatch;
+    _subscribers = new Map();
+    _pathIndex = new Map(); // path → subscriber IDs for fast lookup
+    _rootPath;
+    _isInitialized = false;
+    /**
+     * @param watcher - The underlying watcher to orchestrate (can be DefaultWatcher, ParcelWatcher, or ForkWatcher)
+     * @param rootPath - The root path to watch (typically the monorepo root)
+     */
+    constructor(watcher, rootPath) {
+        super();
+        this._watcher = watcher;
+        this._rootPath = path.resolve(rootPath);
+    }
+    async _watch(options, onChange) {
+        const { path: watchPath, id, watchPaths = sourceFilesGlobs } = options;
+        const absolutePath = path.resolve(watchPath);
+        // Validate that the watch path is under the root
+        // Normalize for cross-platform comparison
+        if (!slash(absolutePath).startsWith(slash(this._rootPath))) {
+            throw new Error(`Cannot watch path "${absolutePath}" because it's not under the root "${this._rootPath}". ` +
+                `SharedRootWatcher requires all watched paths to be under the configured root.`);
+        }
+        // Initialize the root watcher lazily on first subscription
+        if (!this._isInitialized) {
+            await this._initializeRootWatcher();
+            this._isInitialized = true;
+        }
+        const { positiveGlobs, negativeGlobs } = separateGlobs(watchPaths);
+        // Create matchers for this subscriber
+        // Using picomatch for 10-50x better performance than minimatch
+        const matchers = {
+            positive: positiveGlobs.map((glob) => {
+                const absoluteGlob = slash(path.resolve(absolutePath, glob));
+                return picomatch(absoluteGlob, { dot: true, windows: true });
+            }),
+            negative: negativeGlobs.map((glob) => {
+                const absoluteGlob = slash(path.resolve(absolutePath, glob));
+                return picomatch(absoluteGlob, { dot: true, windows: true });
+            }),
+        };
+        // Add subscriber
+        this._subscribers.set(id, {
+            rootPath: absolutePath,
+            watchPaths,
+            callback: onChange,
+            matchers,
+        });
+        // Add to path index for fast lookup
+        const subscribersAtPath = this._pathIndex.get(absolutePath) || new Set();
+        subscribersAtPath.add(id);
+        this._pathIndex.set(absolutePath, subscribersAtPath);
+        return async () => {
+            this._subscribers.delete(id);
+            // Remove from path index
+            const indexedSubscribers = this._pathIndex.get(absolutePath);
+            if (indexedSubscribers) {
+                indexedSubscribers.delete(id);
+                // Clean up empty sets
+                if (indexedSubscribers.size === 0) {
+                    this._pathIndex.delete(absolutePath);
+                }
+            }
+            // If no more subscribers, unwatch the root
+            if (this._subscribers.size === 0) {
+                await this._rootUnwatch?.();
+                this._rootUnwatch = undefined;
+                this._isInitialized = false;
+            }
+        };
+    }
+    async _dispose() {
+        await this._rootUnwatch?.();
+        this._rootUnwatch = undefined;
+        await this._watcher.dispose();
+        this._subscribers.clear();
+        this._pathIndex.clear();
+        this._isInitialized = false;
+    }
+    async _initializeRootWatcher() {
+        // Watch the entire root with the underlying watcher
+        // No filtering at this level - subscribers control their own filtering via watchPaths
+        this._rootUnwatch = await this._watcher.watch({
+            path: this._rootPath,
+            id: '__shared_root__',
+        }, (changedPaths) => this._handleFileChanges(changedPaths));
+    }
+    _findRelevantSubscribers(filePath) {
+        const relevantIds = new Set();
+        // Start from the file and walk up to the root, checking each parent directory
+        let currentPath = filePath;
+        const normalizedRoot = slash(this._rootPath);
+        while (slash(currentPath).startsWith(normalizedRoot)) {
+            const subscribersAtLevel = this._pathIndex.get(currentPath);
+            if (subscribersAtLevel) {
+                subscribersAtLevel.forEach((id) => relevantIds.add(id));
+            }
+            const parentPath = path.dirname(currentPath);
+            if (parentPath === currentPath)
+                break; // Reached filesystem root
+            currentPath = parentPath;
+        }
+        // Convert IDs to actual subscribers
+        const subscribers = [];
+        for (const id of relevantIds) {
+            const subscriber = this._subscribers.get(id);
+            if (subscriber) {
+                subscribers.push(subscriber);
+            }
+        }
+        return subscribers;
+    }
+    _handleFileChanges(changedPaths) {
+        for (const filePath of changedPaths) {
+            const absolutePath = path.resolve(filePath);
+            const normalizedPath = slash(absolutePath);
+            // Use path index to find only relevant subscribers (O(depth) instead of O(n))
+            const relevantSubscribers = this._findRelevantSubscribers(absolutePath);
+            for (const subscriber of relevantSubscribers) {
+                if (this._shouldNotifySubscriber(normalizedPath, subscriber)) {
+                    // Call callback immediately - no batching at this level
+                    subscriber.callback([absolutePath]);
+                }
+            }
+        }
+    }
+    _shouldNotifySubscriber(normalizedFilePath, subscriber) {
+        // Note: normalizedFilePath is already normalized to forward slashes
+        const normalizedRootPath = slash(subscriber.rootPath);
+        // 1. Check if file is under subscriber's root path
+        if (!normalizedFilePath.startsWith(normalizedRootPath)) {
+            return false;
+        }
+        // 2. Check negative globs (ignores) first - if any match, exclude
+        if (subscriber.matchers.negative.some((matcher) => matcher(normalizedFilePath))) {
+            return false;
+        }
+        // 3. If no positive globs specified, include everything (that's not ignored)
+        if (subscriber.matchers.positive.length === 0) {
+            return true;
+        }
+        // 4. Check if file matches any positive glob
+        return subscriber.matchers.positive.some((matcher) => matcher(normalizedFilePath));
+    }
+    /** Get number of subscribers (for testing/debugging) */
+    get subscriberCount() {
+        return this._subscribers.size;
+    }
+}
+//# sourceMappingURL=SharedRootWatcher.js.map

package/lib/SharedRootWatcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SharedRootWatcher.js","sourceRoot":"","sources":["../src/SharedRootWatcher.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,SAAS,MAAM,WAAW,CAAC;AAElC,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,EAAE,KAAK,EAAE,MAAM,mCAAmC,CAAC;AAC1D,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAkBnD;;;;;;;GAOG;AACH,MAAM,OAAO,iBAAkB,SAAQ,WAAW;IACxC,QAAQ,CAAU;IAClB,YAAY,CAAmB;IAC/B,YAAY,GAAG,IAAI,GAAG,EAAsB,CAAC;IAC7C,UAAU,GAAG,IAAI,GAAG,EAAuB,CAAC,CAAC,wCAAwC;IACrF,SAAS,CAAS;IAClB,cAAc,GAAG,KAAK,CAAC;IAE/B;;;OAGG;IACH,YAAY,OAAgB,EAAE,QAAgB;QAC5C,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;QACxB,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC1C,CAAC;IAES,KAAK,CAAC,MAAM,CAAC,OAA2B,EAAE,QAA6B;QAC/E,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,UAAU,GAAG,gBAAgB,EAAE,GAAG,OAAO,CAAC;QACvE,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QAE7C,iDAAiD;QACjD,0CAA0C;QAC1C,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC;YAC3D,MAAM,IAAI,KAAK,CACb,sBAAsB,YAAY,sCAAsC,IAAI,CAAC,SAAS,KAAK;gBACzF,+EAA+E,CAClF,CAAC;QACJ,CAAC;QAED,2DAA2D;QAC3D,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,CAAC;YACzB,MAAM,IAAI,CAAC,sBAAsB,EAAE,CAAC;YACpC,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC;QAC7B,CAAC;QAED,MAAM,EAAE,aAAa,EAAE,aAAa,EAAE,GAAG,aAAa,CAAC,UAAU,CAAC,CAAC;QAEnE,sCAAsC;QACtC,+DAA+D;QAC/D,MAAM,QAAQ,GAAG;YACf,QAAQ,EAAE,aAAa,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;gBACnC,MAAM,YAAY,GAAG,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC,CAAC;gBAC7D,OAAO,SAAS,CAAC,YAAY,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;YAC/D,CAAC,CAAC;YACF,QAAQ,EAAE,aAAa,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;gBACnC,MAAM,YAAY,GAAG,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC,CAAC;gBAC7D,OAAO,SAAS,CAAC,YAAY,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;YAC/D,CAAC,CAAC;SACH,CAAC;QAEF,iBAAiB;QACjB,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,EAAE,EAAE;YACxB,QAAQ,EAAE,YAAY;YACtB,UAAU;YACV,QAAQ,EAAE,QAAQ;YAClB,QAAQ;SACT,CAAC,CAAC;QAEH,oCAAoC;QACpC,MAAM,iBAAiB,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,YAAY,CAAC,IAAI,IAAI,GAAG,EAAU,CAAC;QACjF,iBAAiB,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC1B,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,YAAY,EAAE,iBAAiB,CAAC,CAAC;QAErD,OAAO,KAAK,IAAI,EAAE;YAChB,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;YAE7B,yBAAyB;YACzB,MAAM,kBAAkB,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;YAC7D,IAAI,kBAAkB,EAAE,CAAC;gBACvB,kBAAkB,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;gBAC9B,sBAAsB;gBACtB,IAAI,kBAAkB,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;oBAClC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;gBACvC,CAAC;YACH,CAAC;YAED,2CAA2C;YAC3C,IAAI,IAAI,CAAC,YAAY,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;gBACjC,MAAM,IAAI,CAAC,YAAY,EAAE,EAAE,CAAC;gBAC5B,IAAI,CAAC,YAAY,GAAG,SAAS,CAAC;gBAC9B,IAAI,CAAC,cAAc,GAAG,KAAK,CAAC;YAC9B,CAAC;QACH,CAAC,CAAC;IACJ,CAAC;IAES,KAAK,CAAC,QAAQ;QACtB,MAAM,IAAI,CAAC,YAAY,EAAE,EAAE,CAAC;QAC5B,IAAI,CAAC,YAAY,GAAG,SAAS,CAAC;QAC9B,MAAM,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC;QAC9B,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,CAAC;QAC1B,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;QACxB,IAAI,CAAC,cAAc,GAAG,KAAK,CAAC;IAC9B,CAAC;IAEO,KAAK,CAAC,sBAAsB;QAClC,oDAAoD;QACpD,sFAAsF;QACtF,IAAI,CAAC,YAAY,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,KAAK,CAC3C;YACE,IAAI,EAAE,IAAI,CAAC,SAAS;YACpB,EAAE,EAAE,iBAAiB;SACtB,EACD,CAAC,YAAY,EAAE,EAAE,CAAC,IAAI,CAAC,kBAAkB,CAAC,YAAY,CAAC,CACxD,CAAC;IACJ,CAAC;IAEO,wBAAwB,CAAC,QAAgB;QAC/C,MAAM,WAAW,GAAG,IAAI,GAAG,EAAU,CAAC;QAEtC,8EAA8E;QAC9E,IAAI,WAAW,GAAG,QAAQ,CAAC;QAC3B,MAAM,cAAc,GAAG,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAC7C,OAAO,KAAK,CAAC,WAAW,CAAC,CAAC,UAAU,CAAC,cAAc,CAAC,EAAE,CAAC;YACrD,MAAM,kBAAkB,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;YAC5D,IAAI,kBAAkB,EAAE,CAAC;gBACvB,kBAAkB,CAAC,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;YAC1D,CAAC;YAED,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;YAC7C,IAAI,UAAU,KAAK,WAAW;gBAAE,MAAM,CAAC,0BAA0B;YACjE,WAAW,GAAG,UAAU,CAAC;QAC3B,CAAC;QAED,oCAAoC;QACpC,MAAM,WAAW,GAAiB,EAAE,CAAC;QACrC,KAAK,MAAM,EAAE,IAAI,WAAW,EAAE,CAAC;YAC7B,MAAM,UAAU,GAAG,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAC7C,IAAI,UAAU,EAAE,CAAC;gBACf,WAAW,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;YAC/B,CAAC;QACH,CAAC;QACD,OAAO,WAAW,CAAC;IACrB,CAAC;IAEO,kBAAkB,CAAC,YAAsB;QAC/C,KAAK,MAAM,QAAQ,IAAI,YAAY,EAAE,CAAC;YACpC,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;YAC5C,MAAM,cAAc,GAAG,KAAK,CAAC,YAAY,CAAC,CAAC;YAE3C,8EAA8E;YAC9E,MAAM,mBAAmB,GAAG,IAAI,CAAC,wBAAwB,CAAC,YAAY,CAAC,CAAC;YAExE,KAAK,MAAM,UAAU,IAAI,mBAAmB,EAAE,CAAC;gBAC7C,IAAI,IAAI,CAAC,uBAAuB,CAAC,cAAc,EAAE,UAAU,CAAC,EAAE,CAAC;oBAC7D,wDAAwD;oBACxD,UAAU,CAAC,QAAQ,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC;gBACtC,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAEO,uBAAuB,CAAC,kBAA0B,EAAE,UAAsB;QAChF,oEAAoE;QACpE,MAAM,kBAAkB,GAAG,KAAK,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;QAEtD,mDAAmD;QACnD,IAAI,CAAC,kBAAkB,CAAC,UAAU,CAAC,kBAAkB,CAAC,EAAE,CAAC;YACvD,OAAO,KAAK,CAAC;QACf,CAAC;QAED,kEAAkE;QAClE,IAAI,UAAU,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,kBAAkB,CAAC,CAAC,EAAE,CAAC;YAChF,OAAO,KAAK,CAAC;QACf,CAAC;QAED,6EAA6E;QAC7E,IAAI,UAAU,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC9C,OAAO,IAAI,CAAC;QACd,CAAC;QAED,6CAA6C;QAC7C,OAAO,UAAU,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC;IACrF,CAAC;IAED,wDAAwD;IACxD,IAAW,eAAe;QACxB,OAAO,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC;IAChC,CAAC;CACF","sourcesContent":["import path from 'path';\nimport picomatch from 'picomatch';\nimport type { UnwatchCallback, WatchChangeCallback, Watcher, WatchOptionsWithId } from './types/Watcher.js';\nimport { BaseWatcher } from './BaseWatcher.js';\nimport { sourceFilesGlobs } from '@ms-cloudpack/path-utilities';\nimport { slash } from '@ms-cloudpack/path-string-parsing';\nimport { separateGlobs } from './separateGlobs.js';\n\ntype PathMatcher = (filePath: string) => boolean;\n\ninterface Subscriber {\n  /** Absolute path being watched */\n  rootPath: string;\n  /** Globs to match (positive and negative) */\n  watchPaths: string[];\n  /** Callback to invoke on changes */\n  callback: WatchChangeCallback;\n  /** Compiled matchers for performance */\n  matchers: {\n    positive: PathMatcher[];\n    negative: PathMatcher[];\n  };\n}\n\n/**\n * Orchestrator that wraps an existing watcher to efficiently handle many watch paths (100+).\n *\n * Instead of creating N watchers for N packages, this creates a single watch at the root\n * and routes events to subscribers based on path matching.\n *\n * This is a decorator pattern - it takes any Watcher implementation and multiplexes it.\n */\nexport class SharedRootWatcher extends BaseWatcher {\n  private _watcher: Watcher;\n  private _rootUnwatch?: UnwatchCallback;\n  private _subscribers = new Map<string, Subscriber>();\n  private _pathIndex = new Map<string, Set<string>>(); // path → subscriber IDs for fast lookup\n  private _rootPath: string;\n  private _isInitialized = false;\n\n  /**\n   * @param watcher - The underlying watcher to orchestrate (can be DefaultWatcher, ParcelWatcher, or ForkWatcher)\n   * @param rootPath - The root path to watch (typically the monorepo root)\n   */\n  constructor(watcher: Watcher, rootPath: string) {\n    super();\n    this._watcher = watcher;\n    this._rootPath = path.resolve(rootPath);\n  }\n\n  protected async _watch(options: WatchOptionsWithId, onChange: WatchChangeCallback): Promise<UnwatchCallback> {\n    const { path: watchPath, id, watchPaths = sourceFilesGlobs } = options;\n    const absolutePath = path.resolve(watchPath);\n\n    // Validate that the watch path is under the root\n    // Normalize for cross-platform comparison\n    if (!slash(absolutePath).startsWith(slash(this._rootPath))) {\n      throw new Error(\n        `Cannot watch path \"${absolutePath}\" because it's not under the root \"${this._rootPath}\". ` +\n          `SharedRootWatcher requires all watched paths to be under the configured root.`,\n      );\n    }\n\n    // Initialize the root watcher lazily on first subscription\n    if (!this._isInitialized) {\n      await this._initializeRootWatcher();\n      this._isInitialized = true;\n    }\n\n    const { positiveGlobs, negativeGlobs } = separateGlobs(watchPaths);\n\n    // Create matchers for this subscriber\n    // Using picomatch for 10-50x better performance than minimatch\n    const matchers = {\n      positive: positiveGlobs.map((glob) => {\n        const absoluteGlob = slash(path.resolve(absolutePath, glob));\n        return picomatch(absoluteGlob, { dot: true, windows: true });\n      }),\n      negative: negativeGlobs.map((glob) => {\n        const absoluteGlob = slash(path.resolve(absolutePath, glob));\n        return picomatch(absoluteGlob, { dot: true, windows: true });\n      }),\n    };\n\n    // Add subscriber\n    this._subscribers.set(id, {\n      rootPath: absolutePath,\n      watchPaths,\n      callback: onChange,\n      matchers,\n    });\n\n    // Add to path index for fast lookup\n    const subscribersAtPath = this._pathIndex.get(absolutePath) || new Set<string>();\n    subscribersAtPath.add(id);\n    this._pathIndex.set(absolutePath, subscribersAtPath);\n\n    return async () => {\n      this._subscribers.delete(id);\n\n      // Remove from path index\n      const indexedSubscribers = this._pathIndex.get(absolutePath);\n      if (indexedSubscribers) {\n        indexedSubscribers.delete(id);\n        // Clean up empty sets\n        if (indexedSubscribers.size === 0) {\n          this._pathIndex.delete(absolutePath);\n        }\n      }\n\n      // If no more subscribers, unwatch the root\n      if (this._subscribers.size === 0) {\n        await this._rootUnwatch?.();\n        this._rootUnwatch = undefined;\n        this._isInitialized = false;\n      }\n    };\n  }\n\n  protected async _dispose(): Promise<void> {\n    await this._rootUnwatch?.();\n    this._rootUnwatch = undefined;\n    await this._watcher.dispose();\n    this._subscribers.clear();\n    this._pathIndex.clear();\n    this._isInitialized = false;\n  }\n\n  private async _initializeRootWatcher(): Promise<void> {\n    // Watch the entire root with the underlying watcher\n    // No filtering at this level - subscribers control their own filtering via watchPaths\n    this._rootUnwatch = await this._watcher.watch(\n      {\n        path: this._rootPath,\n        id: '__shared_root__',\n      },\n      (changedPaths) => this._handleFileChanges(changedPaths),\n    );\n  }\n\n  private _findRelevantSubscribers(filePath: string): Subscriber[] {\n    const relevantIds = new Set<string>();\n\n    // Start from the file and walk up to the root, checking each parent directory\n    let currentPath = filePath;\n    const normalizedRoot = slash(this._rootPath);\n    while (slash(currentPath).startsWith(normalizedRoot)) {\n      const subscribersAtLevel = this._pathIndex.get(currentPath);\n      if (subscribersAtLevel) {\n        subscribersAtLevel.forEach((id) => relevantIds.add(id));\n      }\n\n      const parentPath = path.dirname(currentPath);\n      if (parentPath === currentPath) break; // Reached filesystem root\n      currentPath = parentPath;\n    }\n\n    // Convert IDs to actual subscribers\n    const subscribers: Subscriber[] = [];\n    for (const id of relevantIds) {\n      const subscriber = this._subscribers.get(id);\n      if (subscriber) {\n        subscribers.push(subscriber);\n      }\n    }\n    return subscribers;\n  }\n\n  private _handleFileChanges(changedPaths: string[]): void {\n    for (const filePath of changedPaths) {\n      const absolutePath = path.resolve(filePath);\n      const normalizedPath = slash(absolutePath);\n\n      // Use path index to find only relevant subscribers (O(depth) instead of O(n))\n      const relevantSubscribers = this._findRelevantSubscribers(absolutePath);\n\n      for (const subscriber of relevantSubscribers) {\n        if (this._shouldNotifySubscriber(normalizedPath, subscriber)) {\n          // Call callback immediately - no batching at this level\n          subscriber.callback([absolutePath]);\n        }\n      }\n    }\n  }\n\n  private _shouldNotifySubscriber(normalizedFilePath: string, subscriber: Subscriber): boolean {\n    // Note: normalizedFilePath is already normalized to forward slashes\n    const normalizedRootPath = slash(subscriber.rootPath);\n\n    // 1. Check if file is under subscriber's root path\n    if (!normalizedFilePath.startsWith(normalizedRootPath)) {\n      return false;\n    }\n\n    // 2. Check negative globs (ignores) first - if any match, exclude\n    if (subscriber.matchers.negative.some((matcher) => matcher(normalizedFilePath))) {\n      return false;\n    }\n\n    // 3. If no positive globs specified, include everything (that's not ignored)\n    if (subscriber.matchers.positive.length === 0) {\n      return true;\n    }\n\n    // 4. Check if file matches any positive glob\n    return subscriber.matchers.positive.some((matcher) => matcher(normalizedFilePath));\n  }\n\n  /** Get number of subscribers (for testing/debugging) */\n  public get subscriberCount(): number {\n    return this._subscribers.size;\n  }\n}\n"]}

package/lib/applyPolicies.d.ts

@@ -0,0 +1,15 @@
+import type { Watcher } from './types/Watcher.js';
+import type { WatcherPolicies } from './types/WatcherPolicy.js';
+/**
+ * Apply watcher policies in the defined order.
+ *
+ * Policy application order:
+ * 1. shared-root - Multiplexes N watches into 1 root watch
+ * 2. debounce - Batches file change notifications
+ *
+ * @param watcher - Base watcher to wrap with policies
+ * @param policies - Policies to apply
+ * @returns Watcher wrapped with the specified policies
+ */
+export declare function applyPolicies(watcher: Watcher, policies?: WatcherPolicies): Watcher;
+//# sourceMappingURL=applyPolicies.d.ts.map

package/lib/applyPolicies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"applyPolicies.d.ts","sourceRoot":"","sources":["../src/applyPolicies.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAIhE;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,eAAe,GAAG,OAAO,CAkBnF"}

package/lib/applyPolicies.js

@@ -0,0 +1,29 @@
+import { SharedRootWatcher } from './SharedRootWatcher.js';
+import { DebouncedWatcher } from './DebouncedWatcher.js';
+/**
+ * Apply watcher policies in the defined order.
+ *
+ * Policy application order:
+ * 1. shared-root - Multiplexes N watches into 1 root watch
+ * 2. debounce - Batches file change notifications
+ *
+ * @param watcher - Base watcher to wrap with policies
+ * @param policies - Policies to apply
+ * @returns Watcher wrapped with the specified policies
+ */
+export function applyPolicies(watcher, policies) {
+    if (!policies) {
+        return watcher;
+    }
+    let result = watcher;
+    // Apply shared-root first (multiplexes N watches → 1)
+    if (policies['shared-root']) {
+        result = new SharedRootWatcher(result, policies['shared-root'].rootPath);
+    }
+    // Apply debounce second (batches events)
+    if (policies.debounce) {
+        result = new DebouncedWatcher(result, { debounceMs: policies.debounce.debounceMs });
+    }
+    return result;
+}
+//# sourceMappingURL=applyPolicies.js.map

package/lib/applyPolicies.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"applyPolicies.js","sourceRoot":"","sources":["../src/applyPolicies.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAEzD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,aAAa,CAAC,OAAgB,EAAE,QAA0B;IACxE,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,IAAI,MAAM,GAAG,OAAO,CAAC;IAErB,sDAAsD;IACtD,IAAI,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC;QAC5B,MAAM,GAAG,IAAI,iBAAiB,CAAC,MAAM,EAAE,QAAQ,CAAC,aAAa,CAAC,CAAC,QAAQ,CAAC,CAAC;IAC3E,CAAC;IAED,yCAAyC;IACzC,IAAI,QAAQ,CAAC,QAAQ,EAAE,CAAC;QACtB,MAAM,GAAG,IAAI,gBAAgB,CAAC,MAAM,EAAE,EAAE,UAAU,EAAE,QAAQ,CAAC,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC;IACtF,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC","sourcesContent":["import type { Watcher } from './types/Watcher.js';\nimport type { WatcherPolicies } from './types/WatcherPolicy.js';\nimport { SharedRootWatcher } from './SharedRootWatcher.js';\nimport { DebouncedWatcher } from './DebouncedWatcher.js';\n\n/**\n * Apply watcher policies in the defined order.\n *\n * Policy application order:\n * 1. shared-root - Multiplexes N watches into 1 root watch\n * 2. debounce - Batches file change notifications\n *\n * @param watcher - Base watcher to wrap with policies\n * @param policies - Policies to apply\n * @returns Watcher wrapped with the specified policies\n */\nexport function applyPolicies(watcher: Watcher, policies?: WatcherPolicies): Watcher {\n  if (!policies) {\n    return watcher;\n  }\n\n  let result = watcher;\n\n  // Apply shared-root first (multiplexes N watches → 1)\n  if (policies['shared-root']) {\n    result = new SharedRootWatcher(result, policies['shared-root'].rootPath);\n  }\n\n  // Apply debounce second (batches events)\n  if (policies.debounce) {\n    result = new DebouncedWatcher(result, { debounceMs: policies.debounce.debounceMs });\n  }\n\n  return result;\n}\n"]}

package/lib/createWatcher.d.ts

@@ -1,12 +1,37 @@
 import type { Backend, Watcher } from './types/Watcher.js';
+import type { WatcherPolicies } from './types/WatcherPolicy.js';
 /**
- * Create a file watcher. By default, the watcher will run in the main thread.
- * Use `{ type: 'fork' }` to run the watcher in a forked process.
+ * Create a file watcher with optional policies.
+ *
+ * Policies are applied in a fixed order:
+ * 1. Base watcher (DefaultWatcher, ParcelWatcher, or ForkWatcher)
+ * 2. shared-root - Multiplexes many watches into one root watch
+ * 3. debounce - Batches file change notifications
+ *
+ * @example
+ * ```typescript
+ * // Simple watcher
+ * const watcher = createWatcher();
+ *
+ * // Monorepo with shared root and debouncing
+ * const watcher = createWatcher({
+ *   type: 'fork',
+ *   backend: 'parcel',
+ *   policies: {
+ *     'shared-root': { rootPath: '/monorepo' },
+ *     'debounce': { debounceMs: 10 }
+ *   }
+ * });
+ * ```
  */
 export declare function createWatcher(options?: {
     /**
      * By default, the watcher will run in the main thread.
      * Specify `'fork'` to run the watcher in a forked process.
+     *
+     * When using 'fork', policies are applied inside the child process
+     * for better performance and reduced IPC overhead.
+     *
      * @default 'default'
      */
     type?: 'default' | 'fork';
@@ -16,5 +41,13 @@ export declare function createWatcher(options?: {
      * @default 'default'
      */
     backend?: Backend;
+    /**
+     * Optional policies to enhance the watcher.
+     * Policies are applied in order: shared-root → debounce
+     *
+     * For 'fork' type: policies are applied in the child process.
+     * For 'default' type: policies are applied in the parent process.
+     */
+    policies?: WatcherPolicies;
 }): Watcher;
 //# sourceMappingURL=createWatcher.d.ts.map

package/lib/createWatcher.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"createWatcher.d.ts","sourceRoot":"","sources":["../src/createWatcher.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAE3D;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,CAAC,EAAE;IACtC;;;;OAIG;IACH,IAAI,CAAC,EAAE,SAAS,GAAG,MAAM,CAAC;IAC1B;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,GAAG,OAAO,CAYV"}
+{"version":3,"file":"createWatcher.d.ts","sourceRoot":"","sources":["../src/createWatcher.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAEhE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,aAAa,CAAC,OAAO,CAAC,EAAE;IACtC;;;;;;;;OAQG;IACH,IAAI,CAAC,EAAE,SAAS,GAAG,MAAM,CAAC;IAC1B;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,eAAe,CAAC;CAC5B,GAAG,OAAO,CAaV"}

package/lib/createWatcher.js

@@ -1,18 +1,39 @@
-import { DefaultWatcher } from './DefaultWatcher.js';
 import { ForkWatcher } from './ForkWatcher.js';
-import { ParcelWatcher } from './ParcelWatcher.js';
+import { applyPolicies } from './applyPolicies.js';
+import { createWatcherInternal } from './createWatcherInternal.js';
 /**
- * Create a file watcher. By default, the watcher will run in the main thread.
- * Use `{ type: 'fork' }` to run the watcher in a forked process.
+ * Create a file watcher with optional policies.
+ *
+ * Policies are applied in a fixed order:
+ * 1. Base watcher (DefaultWatcher, ParcelWatcher, or ForkWatcher)
+ * 2. shared-root - Multiplexes many watches into one root watch
+ * 3. debounce - Batches file change notifications
+ *
+ * @example
+ * ```typescript
+ * // Simple watcher
+ * const watcher = createWatcher();
+ *
+ * // Monorepo with shared root and debouncing
+ * const watcher = createWatcher({
+ *   type: 'fork',
+ *   backend: 'parcel',
+ *   policies: {
+ *     'shared-root': { rootPath: '/monorepo' },
+ *     'debounce': { debounceMs: 10 }
+ *   }
+ * });
+ * ```
  */
 export function createWatcher(options) {
-    const { type = 'default', backend = 'default' } = options ?? {};
+    const { type = 'default', backend = 'default', policies } = options ?? {};
+    // Fork type: policies applied in child process
     if (type === 'fork') {
-        return new ForkWatcher(backend);
+        return new ForkWatcher(backend, policies);
     }
-    if (backend === 'parcel') {
-        return new ParcelWatcher();
-    }
-    return new DefaultWatcher();
+    // Non-fork: create base watcher and apply policies in parent
+    const watcher = createWatcherInternal(backend);
+    // Apply policies in order
+    return applyPolicies(watcher, policies);
 }
 //# sourceMappingURL=createWatcher.js.map

package/lib/createWatcher.js.map

@@ -1 +1 @@
-{"version":3,"file":"createWatcher.js","sourceRoot":"","sources":["../src/createWatcher.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAGnD;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,OAa7B;IACC,MAAM,EAAE,IAAI,GAAG,SAAS,EAAE,OAAO,GAAG,SAAS,EAAE,GAAG,OAAO,IAAI,EAAE,CAAC;IAEhE,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;QACpB,OAAO,IAAI,WAAW,CAAC,OAAO,CAAC,CAAC;IAClC,CAAC;IAED,IAAI,OAAO,KAAK,QAAQ,EAAE,CAAC;QACzB,OAAO,IAAI,aAAa,EAAE,CAAC;IAC7B,CAAC;IAED,OAAO,IAAI,cAAc,EAAE,CAAC;AAC9B,CAAC","sourcesContent":["import { DefaultWatcher } from './DefaultWatcher.js';\nimport { ForkWatcher } from './ForkWatcher.js';\nimport { ParcelWatcher } from './ParcelWatcher.js';\nimport type { Backend, Watcher } from './types/Watcher.js';\n\n/**\n * Create a file watcher. By default, the watcher will run in the main thread.\n * Use `{ type: 'fork' }` to run the watcher in a forked process.\n */\nexport function createWatcher(options?: {\n  /**\n   * By default, the watcher will run in the main thread.\n   * Specify `'fork'` to run the watcher in a forked process.\n   * @default 'default'\n   */\n  type?: 'default' | 'fork';\n  /**\n   * By default, the watcher will use chokidar.\n   * Specify `'parcel'` to use parcel as the file watching backend.\n   * @default 'default'\n   */\n  backend?: Backend;\n}): Watcher {\n  const { type = 'default', backend = 'default' } = options ?? {};\n\n  if (type === 'fork') {\n    return new ForkWatcher(backend);\n  }\n\n  if (backend === 'parcel') {\n    return new ParcelWatcher();\n  }\n\n  return new DefaultWatcher();\n}\n"]}
+{"version":3,"file":"createWatcher.js","sourceRoot":"","sources":["../src/createWatcher.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAInE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,aAAa,CAAC,OAyB7B;IACC,MAAM,EAAE,IAAI,GAAG,SAAS,EAAE,OAAO,GAAG,SAAS,EAAE,QAAQ,EAAE,GAAG,OAAO,IAAI,EAAE,CAAC;IAE1E,+CAA+C;IAC/C,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;QACpB,OAAO,IAAI,WAAW,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IAC5C,CAAC;IAED,6DAA6D;IAC7D,MAAM,OAAO,GAAG,qBAAqB,CAAC,OAAO,CAAC,CAAC;IAE/C,0BAA0B;IAC1B,OAAO,aAAa,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;AAC1C,CAAC","sourcesContent":["import { ForkWatcher } from './ForkWatcher.js';\nimport { applyPolicies } from './applyPolicies.js';\nimport { createWatcherInternal } from './createWatcherInternal.js';\nimport type { Backend, Watcher } from './types/Watcher.js';\nimport type { WatcherPolicies } from './types/WatcherPolicy.js';\n\n/**\n * Create a file watcher with optional policies.\n *\n * Policies are applied in a fixed order:\n * 1. Base watcher (DefaultWatcher, ParcelWatcher, or ForkWatcher)\n * 2. shared-root - Multiplexes many watches into one root watch\n * 3. debounce - Batches file change notifications\n *\n * @example\n * ```typescript\n * // Simple watcher\n * const watcher = createWatcher();\n *\n * // Monorepo with shared root and debouncing\n * const watcher = createWatcher({\n *   type: 'fork',\n *   backend: 'parcel',\n *   policies: {\n *     'shared-root': { rootPath: '/monorepo' },\n *     'debounce': { debounceMs: 10 }\n *   }\n * });\n * ```\n */\nexport function createWatcher(options?: {\n  /**\n   * By default, the watcher will run in the main thread.\n   * Specify `'fork'` to run the watcher in a forked process.\n   *\n   * When using 'fork', policies are applied inside the child process\n   * for better performance and reduced IPC overhead.\n   *\n   * @default 'default'\n   */\n  type?: 'default' | 'fork';\n  /**\n   * By default, the watcher will use chokidar.\n   * Specify `'parcel'` to use parcel as the file watching backend.\n   * @default 'default'\n   */\n  backend?: Backend;\n  /**\n   * Optional policies to enhance the watcher.\n   * Policies are applied in order: shared-root → debounce\n   *\n   * For 'fork' type: policies are applied in the child process.\n   * For 'default' type: policies are applied in the parent process.\n   */\n  policies?: WatcherPolicies;\n}): Watcher {\n  const { type = 'default', backend = 'default', policies } = options ?? {};\n\n  // Fork type: policies applied in child process\n  if (type === 'fork') {\n    return new ForkWatcher(backend, policies);\n  }\n\n  // Non-fork: create base watcher and apply policies in parent\n  const watcher = createWatcherInternal(backend);\n\n  // Apply policies in order\n  return applyPolicies(watcher, policies);\n}\n"]}

package/lib/createWatcherInternal.d.ts

@@ -0,0 +1,3 @@
+import type { Backend, Watcher } from './types/Watcher.js';
+export declare function createWatcherInternal(backend?: Backend): Watcher;
+//# sourceMappingURL=createWatcherInternal.d.ts.map

package/lib/createWatcherInternal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createWatcherInternal.d.ts","sourceRoot":"","sources":["../src/createWatcherInternal.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAE3D,wBAAgB,qBAAqB,CAAC,OAAO,GAAE,OAAmB,GAAG,OAAO,CAE3E"}

package/lib/createWatcherInternal.js

@@ -0,0 +1,6 @@
+import { DefaultWatcher } from './DefaultWatcher.js';
+import { ParcelWatcher } from './ParcelWatcher.js';
+export function createWatcherInternal(backend = 'default') {
+    return backend === 'parcel' ? new ParcelWatcher() : new DefaultWatcher();
+}
+//# sourceMappingURL=createWatcherInternal.js.map

package/lib/createWatcherInternal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createWatcherInternal.js","sourceRoot":"","sources":["../src/createWatcherInternal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAGnD,MAAM,UAAU,qBAAqB,CAAC,UAAmB,SAAS;IAChE,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,aAAa,EAAE,CAAC,CAAC,CAAC,IAAI,cAAc,EAAE,CAAC;AAC3E,CAAC","sourcesContent":["import { DefaultWatcher } from './DefaultWatcher.js';\nimport { ParcelWatcher } from './ParcelWatcher.js';\nimport type { Backend, Watcher } from './types/Watcher.js';\n\nexport function createWatcherInternal(backend: Backend = 'default'): Watcher {\n  return backend === 'parcel' ? new ParcelWatcher() : new DefaultWatcher();\n}\n"]}

package/lib/index.d.ts

@@ -1,3 +1,4 @@
-export type { Watcher, WatchOptions } from './types/Watcher.js';
+export type { Watcher, WatchOptions, Backend } from './types/Watcher.js';
+export type { WatcherPolicies } from './types/WatcherPolicy.js';
 export { createWatcher } from './createWatcher.js';
 //# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AACzE,YAAY,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC"}

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC","sourcesContent":["export type { Watcher, WatchOptions } from './types/Watcher.js';\nexport { createWatcher } from './createWatcher.js';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC","sourcesContent":["export type { Watcher, WatchOptions, Backend } from './types/Watcher.js';\nexport type { WatcherPolicies } from './types/WatcherPolicy.js';\nexport { createWatcher } from './createWatcher.js';\n"]}

package/lib/types/WatcherPolicy.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Policies that can be applied to a watcher to add functionality.
+ * Each policy is optional and can only be specified once.
+ */
+export interface WatcherPolicies {
+    /**
+     * Wraps the watcher with SharedRootWatcher to multiplex many watch paths
+     * into a single root watch. Recommended for monorepos with 100+ packages.
+     */
+    'shared-root'?: {
+        /** Root path to watch (typically the monorepo root) */
+        rootPath: string;
+    };
+    /**
+     * Wraps the watcher with DebouncedWatcher to batch file change notifications.
+     * First change is immediate (0ms latency), subsequent rapid changes are batched.
+     */
+    debounce?: {
+        /** Debounce delay in milliseconds (default: 10ms) */
+        debounceMs?: number;
+    };
+}
+//# sourceMappingURL=WatcherPolicy.d.ts.map

package/lib/types/WatcherPolicy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WatcherPolicy.d.ts","sourceRoot":"","sources":["../../src/types/WatcherPolicy.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,aAAa,CAAC,EAAE;QACd,uDAAuD;QACvD,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;IAEF;;;OAGG;IACH,QAAQ,CAAC,EAAE;QACT,qDAAqD;QACrD,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC;CACH"}

package/lib/types/WatcherPolicy.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=WatcherPolicy.js.map

package/lib/types/WatcherPolicy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WatcherPolicy.js","sourceRoot":"","sources":["../../src/types/WatcherPolicy.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * Policies that can be applied to a watcher to add functionality.\n * Each policy is optional and can only be specified once.\n */\nexport interface WatcherPolicies {\n  /**\n   * Wraps the watcher with SharedRootWatcher to multiplex many watch paths\n   * into a single root watch. Recommended for monorepos with 100+ packages.\n   */\n  'shared-root'?: {\n    /** Root path to watch (typically the monorepo root) */\n    rootPath: string;\n  };\n\n  /**\n   * Wraps the watcher with DebouncedWatcher to batch file change notifications.\n   * First change is immediate (0ms latency), subsequent rapid changes are batched.\n   */\n  debounce?: {\n    /** Debounce delay in milliseconds (default: 10ms) */\n    debounceMs?: number;\n  };\n}\n"]}

package/lib/watcherForkWrapper.js

@@ -1,12 +1,27 @@
-import { DefaultWatcher } from './DefaultWatcher.js';
-import { ParcelWatcher } from './ParcelWatcher.js';
+import { applyPolicies } from './applyPolicies.js';
+import { createWatcherInternal } from './createWatcherInternal.js';
 /**
  * `ForkWatcher` runs this file to initialize the watcher in a child process.
+ *
+ * Policies (shared-root, debounce) are applied here in the child process to reduce
+ * IPC overhead and improve performance.
  */
 function initializeWatcher() {
-    // Get backend from command line arguments
+    // Get backend and policies from command line arguments
     const backend = process.argv[2];
-    const watcher = backend === 'parcel' ? new ParcelWatcher() : new DefaultWatcher();
+    const policiesJson = process.argv[3] || '{}';
+    let policies;
+    try {
+        policies = JSON.parse(policiesJson);
+    }
+    catch (error) {
+        console.error('Failed to parse policies in fork:', error);
+        policies = {};
+    }
+    // 1. Create base watcher
+    let watcher = createWatcherInternal(backend);
+    // 2. Apply policies in order (same as createWatcher)
+    watcher = applyPolicies(watcher, policies);
     process.on('message', (message) => {
         (async () => {
             switch (message.type) {

package/lib/watcherForkWrapper.js.map

@@ -1 +1 @@
-{"version":3,"file":"watcherForkWrapper.js","sourceRoot":"","sources":["../src/watcherForkWrapper.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAInD;;GAEG;AACH,SAAS,iBAAiB;IACxB,0CAA0C;IAC1C,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAwB,CAAC;IAEvD,MAAM,OAAO,GAAG,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,aAAa,EAAE,CAAC,CAAC,CAAC,IAAI,cAAc,EAAE,CAAC;IAElF,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC,OAAsB,EAAE,EAAE;QAC/C,CAAC,KAAK,IAAI,EAAE;YACV,QAAQ,OAAO,CAAC,IAAI,EAAE,CAAC;gBACrB,KAAK,OAAO;oBACV,MAAM,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,YAAY,EAAE,EAAE;wBACpD,WAAW,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,OAAO,CAAC,OAAO,CAAC,EAAE,EAAE,YAAY,EAAE,CAAC,CAAC;oBACxE,CAAC,CAAC,CAAC;oBACH,MAAM;gBAER,KAAK,SAAS;oBACZ,MAAM,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;oBAClC,MAAM;gBAER,KAAK,UAAU;oBACb,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC;oBACxB,uGAAuG;oBACvG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YACpB,CAAC;QACH,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;YACnB,IAAI,CAAC;gBACH,MAAM,YAAY,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;gBAC5E,WAAW,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,CAAC,CAAC;YACtD,CAAC;YAAC,OAAO,SAAS,EAAE,CAAC;gBACnB,OAAO,CAAC,KAAK,CAAC,+BAA+B,EAAE,SAAS,CAAC,CAAC;gBAC1D,OAAO,CAAC,KAAK,CAAC,iBAAiB,EAAE,KAAK,CAAC,CAAC;YAC1C,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED,yCAAyC;AACzC,SAAS,WAAW,CAAC,OAAqB;IACxC,OAAO,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,CAAC;AAC1B,CAAC;AAED,gDAAgD;AAChD,2EAA2E;AAC3E,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;AAE/B,iBAAiB,EAAE,CAAC","sourcesContent":["import { DefaultWatcher } from './DefaultWatcher.js';\nimport { ParcelWatcher } from './ParcelWatcher.js';\nimport type { Backend } from './types/Watcher.js';\nimport type { ChildMessage, ParentMessage } from './types/WatchMessages.js';\n\n/**\n * `ForkWatcher` runs this file to initialize the watcher in a child process.\n */\nfunction initializeWatcher() {\n  // Get backend from command line arguments\n  const backend = process.argv[2] as Backend | undefined;\n\n  const watcher = backend === 'parcel' ? new ParcelWatcher() : new DefaultWatcher();\n\n  process.on('message', (message: ParentMessage) => {\n    (async () => {\n      switch (message.type) {\n        case 'watch':\n          await watcher.watch(message.options, (changedPaths) => {\n            sendMessage({ type: 'change', id: message.options.id, changedPaths });\n          });\n          break;\n\n        case 'unwatch':\n          await watcher.unwatch(message.id);\n          break;\n\n        case 'shutdown':\n          await watcher.dispose();\n          // eslint-disable-next-line no-restricted-properties -- rule isn't relevant for exiting a child process\n          process.exit(0);\n      }\n    })().catch((error) => {\n      try {\n        const errorMessage = error instanceof Error ? error.message : String(error);\n        sendMessage({ type: 'error', error: errorMessage });\n      } catch (sendError) {\n        console.error('Failed to send error message:', sendError);\n        console.error('Original error:', error);\n      }\n    });\n  });\n}\n\n/** Typed wrapper for `process.send()` */\nfunction sendMessage(message: ChildMessage) {\n  process.send?.(message);\n}\n\n// Prevent the process from exiting immediately.\n// This is handled by the parent process instead with the shutdown message.\nprocess.on('SIGINT', () => {});\n\ninitializeWatcher();\n"]}
+{"version":3,"file":"watcherForkWrapper.js","sourceRoot":"","sources":["../src/watcherForkWrapper.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAKnE;;;;;GAKG;AACH,SAAS,iBAAiB;IACxB,uDAAuD;IACvD,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAwB,CAAC;IACvD,MAAM,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;IAE7C,IAAI,QAAyB,CAAC;IAC9B,IAAI,CAAC;QACH,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAoB,CAAC;IACzD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,KAAK,CAAC,mCAAmC,EAAE,KAAK,CAAC,CAAC;QAC1D,QAAQ,GAAG,EAAE,CAAC;IAChB,CAAC;IAED,yBAAyB;IACzB,IAAI,OAAO,GAAY,qBAAqB,CAAC,OAAO,CAAC,CAAC;IAEtD,qDAAqD;IACrD,OAAO,GAAG,aAAa,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IAE3C,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC,OAAsB,EAAE,EAAE;QAC/C,CAAC,KAAK,IAAI,EAAE;YACV,QAAQ,OAAO,CAAC,IAAI,EAAE,CAAC;gBACrB,KAAK,OAAO;oBACV,MAAM,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,YAAY,EAAE,EAAE;wBACpD,WAAW,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,OAAO,CAAC,OAAO,CAAC,EAAE,EAAE,YAAY,EAAE,CAAC,CAAC;oBACxE,CAAC,CAAC,CAAC;oBACH,MAAM;gBAER,KAAK,SAAS;oBACZ,MAAM,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;oBAClC,MAAM;gBAER,KAAK,UAAU;oBACb,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC;oBACxB,uGAAuG;oBACvG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YACpB,CAAC;QACH,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;YACnB,IAAI,CAAC;gBACH,MAAM,YAAY,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;gBAC5E,WAAW,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,CAAC,CAAC;YACtD,CAAC;YAAC,OAAO,SAAS,EAAE,CAAC;gBACnB,OAAO,CAAC,KAAK,CAAC,+BAA+B,EAAE,SAAS,CAAC,CAAC;gBAC1D,OAAO,CAAC,KAAK,CAAC,iBAAiB,EAAE,KAAK,CAAC,CAAC;YAC1C,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED,yCAAyC;AACzC,SAAS,WAAW,CAAC,OAAqB;IACxC,OAAO,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,CAAC;AAC1B,CAAC;AAED,gDAAgD;AAChD,2EAA2E;AAC3E,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;AAE/B,iBAAiB,EAAE,CAAC","sourcesContent":["import { applyPolicies } from './applyPolicies.js';\nimport { createWatcherInternal } from './createWatcherInternal.js';\nimport type { Backend, Watcher } from './types/Watcher.js';\nimport type { WatcherPolicies } from './types/WatcherPolicy.js';\nimport type { ChildMessage, ParentMessage } from './types/WatchMessages.js';\n\n/**\n * `ForkWatcher` runs this file to initialize the watcher in a child process.\n *\n * Policies (shared-root, debounce) are applied here in the child process to reduce\n * IPC overhead and improve performance.\n */\nfunction initializeWatcher() {\n  // Get backend and policies from command line arguments\n  const backend = process.argv[2] as Backend | undefined;\n  const policiesJson = process.argv[3] || '{}';\n\n  let policies: WatcherPolicies;\n  try {\n    policies = JSON.parse(policiesJson) as WatcherPolicies;\n  } catch (error) {\n    console.error('Failed to parse policies in fork:', error);\n    policies = {};\n  }\n\n  // 1. Create base watcher\n  let watcher: Watcher = createWatcherInternal(backend);\n\n  // 2. Apply policies in order (same as createWatcher)\n  watcher = applyPolicies(watcher, policies);\n\n  process.on('message', (message: ParentMessage) => {\n    (async () => {\n      switch (message.type) {\n        case 'watch':\n          await watcher.watch(message.options, (changedPaths) => {\n            sendMessage({ type: 'change', id: message.options.id, changedPaths });\n          });\n          break;\n\n        case 'unwatch':\n          await watcher.unwatch(message.id);\n          break;\n\n        case 'shutdown':\n          await watcher.dispose();\n          // eslint-disable-next-line no-restricted-properties -- rule isn't relevant for exiting a child process\n          process.exit(0);\n      }\n    })().catch((error) => {\n      try {\n        const errorMessage = error instanceof Error ? error.message : String(error);\n        sendMessage({ type: 'error', error: errorMessage });\n      } catch (sendError) {\n        console.error('Failed to send error message:', sendError);\n        console.error('Original error:', error);\n      }\n    });\n  });\n}\n\n/** Typed wrapper for `process.send()` */\nfunction sendMessage(message: ChildMessage) {\n  process.send?.(message);\n}\n\n// Prevent the process from exiting immediately.\n// This is handled by the parent process instead with the shutdown message.\nprocess.on('SIGINT', () => {});\n\ninitializeWatcher();\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ms-cloudpack/file-watcher",
-  "version": "0.4.19",
+  "version": "0.4.20",
   "description": "A file watcher abstraction for use with Cloudpack.",
   "license": "MIT",
   "type": "module",
@@ -15,15 +15,18 @@
     }
   },
   "dependencies": {
-    "@ms-cloudpack/path-utilities": "^3.1.32",
+    "@ms-cloudpack/path-string-parsing": "^1.2.7",
+    "@ms-cloudpack/path-utilities": "^3.1.33",
     "@parcel/watcher": "^2.5.1",
-    "chokidar": "^3.5.3"
+    "chokidar": "^3.5.3",
+    "picomatch": "^4.0.3"
   },
   "devDependencies": {
     "@ms-cloudpack/environment": "*",
     "@ms-cloudpack/eslint-plugin-internal": "^0.0.1",
     "@ms-cloudpack/scripts": "^0.0.1",
-    "@ms-cloudpack/test-utilities": "^0.5.0"
+    "@ms-cloudpack/test-utilities": "^0.5.0",
+    "@types/picomatch": "^4"
   },
   "scripts": {
     "api": "cloudpack-scripts api",