BREAKING CHANGE(watchers): Replace polling-based write stabilization with debounce-based event coalescing and simplify watcher options

ts/watchers/watcher.node.ts

@@ -2,7 +2,6 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as smartrx from '@push.rocks/smartrx';
 import type { IWatcher, IWatcherOptions, IWatchEvent, TWatchEventType } from './interfaces.js';
-import { WriteStabilizer } from '../utils/write-stabilizer.js';
 
 /**
  * Node.js/Bun file watcher using native fs.watch API
@@ -11,19 +10,13 @@ export class NodeWatcher implements IWatcher {
   private watchers: Map<string, fs.FSWatcher> = new Map();
   private watchedFiles: Set<string> = new Set();
   private _isWatching = false;
-  private writeStabilizer: WriteStabilizer;
-  private recentEvents: Map<string, number> = new Map();
-  private throttleMs = 50;
+
+  // Debounce: pending emits per file path
+  private pendingEmits: Map<string, NodeJS.Timeout> = new Map();
 
   public readonly events$ = new smartrx.rxjs.Subject<IWatchEvent>();
 
-  constructor(private options: IWatcherOptions) {
-    this.writeStabilizer = new WriteStabilizer(
-      options.stabilityThreshold,
-      options.pollInterval,
-      options.maxWaitTime
-    );
-  }
+  constructor(private options: IWatcherOptions) {}
 
   /**
    * Check if a file is a temporary file created by editors
@@ -70,15 +63,19 @@ export class NodeWatcher implements IWatcher {
 
   async stop(): Promise<void> {
     this._isWatching = false;
-    this.writeStabilizer.cancelAll();
+
+    // Cancel all pending debounced emits
+    for (const timeout of this.pendingEmits.values()) {
+      clearTimeout(timeout);
+    }
+    this.pendingEmits.clear();
 
     // Close all watchers
-    for (const [watchPath, watcher] of this.watchers) {
+    for (const [, watcher] of this.watchers) {
       watcher.close();
     }
     this.watchers.clear();
     this.watchedFiles.clear();
-    this.recentEvents.clear();
   }
 
   /**
@@ -119,13 +116,13 @@ export class NodeWatcher implements IWatcher {
   }
 
   /**
-   * Handle raw fs.watch events and normalize them
+   * Handle raw fs.watch events - debounce and normalize them
    */
-  private async handleFsEvent(
+  private handleFsEvent(
     basePath: string,
     filename: string,
     eventType: 'rename' | 'change' | string
-  ): Promise<void> {
+  ): void {
     const fullPath = path.join(basePath, filename);
 
     // Skip temporary files created by editors (atomic saves)
@@ -133,11 +130,28 @@ export class NodeWatcher implements IWatcher {
       return;
     }
 
-    // Throttle duplicate events
-    if (!this.shouldEmit(fullPath, eventType)) {
-      return;
+    // Debounce: cancel any pending emit for this file
+    const existing = this.pendingEmits.get(fullPath);
+    if (existing) {
+      clearTimeout(existing);
     }
 
+    // Schedule debounced emit
+    const timeout = setTimeout(() => {
+      this.pendingEmits.delete(fullPath);
+      this.emitFileEvent(fullPath, eventType);
+    }, this.options.debounceMs);
+
+    this.pendingEmits.set(fullPath, timeout);
+  }
+
+  /**
+   * Emit the actual file event after debounce
+   */
+  private async emitFileEvent(
+    fullPath: string,
+    eventType: 'rename' | 'change' | string
+  ): Promise<void> {
     try {
       const stats = await this.statSafe(fullPath);
 
@@ -151,7 +165,6 @@ export class NodeWatcher implements IWatcher {
               this.events$.next({ type: 'addDir', path: fullPath, stats });
             }
           } else {
-            // Rename events (atomic saves) don't need stabilization - file is already complete
             const wasWatched = this.watchedFiles.has(fullPath);
             this.watchedFiles.add(fullPath);
             this.events$.next({
@@ -172,26 +185,20 @@ export class NodeWatcher implements IWatcher {
           }
         }
       } else if (eventType === 'change') {
-        // File was modified in-place - use stabilization for streaming writes
+        // File was modified
         if (stats && !stats.isDirectory()) {
-          try {
-            const stableStats = await this.writeStabilizer.waitForWriteFinish(fullPath);
-            // Check if this is a new file (not yet in watchedFiles)
-            const wasWatched = this.watchedFiles.has(fullPath);
-            if (!wasWatched) {
-              // This is actually an 'add' - file wasn't being watched before
-              this.watchedFiles.add(fullPath);
-              this.events$.next({ type: 'add', path: fullPath, stats: stableStats });
-            } else {
-              this.events$.next({ type: 'change', path: fullPath, stats: stableStats });
-            }
-          } catch {
-            // File was deleted during write
-            if (this.watchedFiles.has(fullPath)) {
-              this.watchedFiles.delete(fullPath);
-              this.events$.next({ type: 'unlink', path: fullPath });
-            }
+          const wasWatched = this.watchedFiles.has(fullPath);
+          if (!wasWatched) {
+            // This is actually an 'add' - file wasn't being watched before
+            this.watchedFiles.add(fullPath);
+            this.events$.next({ type: 'add', path: fullPath, stats });
+          } else {
+            this.events$.next({ type: 'change', path: fullPath, stats });
           }
+        } else if (!stats && this.watchedFiles.has(fullPath)) {
+          // File was deleted
+          this.watchedFiles.delete(fullPath);
+          this.events$.next({ type: 'unlink', path: fullPath });
         }
       }
     } catch (error: any) {
@@ -212,6 +219,12 @@ export class NodeWatcher implements IWatcher {
 
       for (const entry of entries) {
         const fullPath = path.join(dirPath, entry.name);
+
+        // Skip temp files during initial scan too
+        if (this.isTemporaryFile(fullPath)) {
+          continue;
+        }
+
         const stats = await this.statSafe(fullPath);
 
         if (!stats) {
@@ -261,31 +274,4 @@ export class NodeWatcher implements IWatcher {
     }
     return false;
   }
-
-  /**
-   * Throttle duplicate events
-   */
-  private shouldEmit(filePath: string, eventType: string): boolean {
-    const key = `${filePath}:${eventType}`;
-    const now = Date.now();
-    const lastEmit = this.recentEvents.get(key);
-
-    if (lastEmit && now - lastEmit < this.throttleMs) {
-      return false;
-    }
-
-    this.recentEvents.set(key, now);
-
-    // Clean up old entries periodically
-    if (this.recentEvents.size > 1000) {
-      const cutoff = now - this.throttleMs * 2;
-      for (const [k, time] of this.recentEvents) {
-        if (time < cutoff) {
-          this.recentEvents.delete(k);
-        }
-      }
-    }
-
-    return true;
-  }
 }