feat(watchers): Improve write stabilization and ignore temporary editor files

changelog.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 2025-12-08 - 5.1.0 - feat(watchers)
+Improve write stabilization and ignore temporary editor files
+
+- Add maxWaitTime option (ms) to IWatcherOptions and WriteStabilizer to cap how long stabilization will wait (default: 1000ms).
+- WriteStabilizer: reduce default stabilityThreshold from 300ms to 100ms and track write start time to enforce maxWaitTime and avoid indefinite polling.
+- Node and Deno watchers: detect and ignore common temporary/editor files (e.g. *.tmp.*, *.swp, *.swx, trailing ~, .#*) to prevent spurious events from atomic saves.
+- Node watcher: treat rename (atomic-save) events as already-complete files and emit add/change immediately without stabilization.
+- Deno watcher: use the configured maxWaitTime and polling-based stabilization for modify events to ensure consistent behavior across runtimes.
+
 ## 2025-11-30 - 5.0.0 - BREAKING CHANGE(@push.rocks/smartwatch)
 Rename package and update branding/docs: switch from @push.rocks/smartchok to @push.rocks/smartwatch, update repository/homepage/bugs URLs and author, and refresh README examples and install instructions.
 

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartwatch',
-  version: '5.0.0',
+  version: '5.1.0',
   description: 'A cross-runtime file watcher with glob pattern support for Node.js, Deno, and Bun.'
 }

ts/smartwatch.classes.smartwatch.ts

@@ -132,8 +132,9 @@ export class Smartwatch {
       basePaths: watchPaths,
       depth: 4,
       followSymlinks: false,
-      stabilityThreshold: 300,
+      stabilityThreshold: 100,
-      pollInterval: 100
+      pollInterval: 100,
+      maxWaitTime: 1000
     });
 
     // Subscribe to watcher events and dispatch to appropriate subjects

ts/utils/write-stabilizer.ts

@@ -3,6 +3,7 @@ import * as fs from 'fs';
 interface IPendingWrite {
   lastSize: number;
   lastChange: number;
+  startTime: number;
   timeoutId: ReturnType<typeof setTimeout>;
   resolve: (stats: fs.Stats) => void;
   reject: (error: Error) => void;
@@ -16,8 +17,9 @@ export class WriteStabilizer {
   private pendingWrites = new Map<string, IPendingWrite>();
 
   constructor(
-    private stabilityThreshold: number = 300,
+    private stabilityThreshold: number = 100,
-    private pollInterval: number = 100
+    private pollInterval: number = 100,
+    private maxWaitTime: number = 1000
   ) {}
 
   /**
@@ -28,6 +30,8 @@ export class WriteStabilizer {
     this.cancel(filePath);
 
     return new Promise((resolve, reject) => {
+      const startTime = Date.now();
+
       const poll = async () => {
         try {
           const stats = await fs.promises.stat(filePath);
@@ -40,6 +44,13 @@ export class WriteStabilizer {
 
           const now = Date.now();
 
+          // Check if we've exceeded max wait time - emit with current stats
+          if (now - pending.startTime >= this.maxWaitTime) {
+            this.pendingWrites.delete(filePath);
+            resolve(stats);
+            return;
+          }
+
           if (stats.size !== pending.lastSize) {
             // Size changed - file is still being written, reset timer
             pending.lastSize = stats.size;
@@ -66,7 +77,8 @@ export class WriteStabilizer {
 
       this.pendingWrites.set(filePath, {
         lastSize: -1,
-        lastChange: Date.now(),
+        lastChange: startTime,
+        startTime: startTime,
         timeoutId: setTimeout(poll, this.pollInterval),
         resolve,
         reject

ts/watchers/index.ts

@@ -28,6 +28,7 @@ export const defaultWatcherOptions: IWatcherOptions = {
   basePaths: [],
   depth: 4,
   followSymlinks: false,
-  stabilityThreshold: 300,
+  stabilityThreshold: 100,
-  pollInterval: 100
+  pollInterval: 100,
+  maxWaitTime: 1000
 };

ts/watchers/interfaces.ts

@@ -30,6 +30,8 @@ export interface IWatcherOptions {
   stabilityThreshold: number;
   /** Poll interval for write detection (ms) */
   pollInterval: number;
+  /** Maximum time to wait for write stabilization (ms) */
+  maxWaitTime: number;
 }
 
 /**

ts/watchers/watcher.deno.ts

@@ -74,6 +74,19 @@ export class DenoWatcher implements IWatcher {
 
   constructor(private options: IWatcherOptions) {}
 
+  /**
+   * Check if a file is a temporary file created by editors
+   */
+  private isTemporaryFile(filePath: string): boolean {
+    const basename = filePath.split('/').pop() || '';
+    // Editor temp files: *.tmp.*, *.swp, *.swx, *~, .#*
+    if (basename.includes('.tmp.')) return true;
+    if (basename.endsWith('.swp') || basename.endsWith('.swx')) return true;
+    if (basename.endsWith('~')) return true;
+    if (basename.startsWith('.#')) return true;
+    return false;
+  }
+
   get isWatching(): boolean {
     return this._isWatching;
   }
@@ -162,6 +175,11 @@ export class DenoWatcher implements IWatcher {
       return;
     }
 
+    // Skip temporary files created by editors (atomic saves)
+    if (this.isTemporaryFile(filePath)) {
+      return;
+    }
+
     // Throttle duplicate events
     if (!this.shouldEmit(filePath, kind)) {
       return;
@@ -169,19 +187,15 @@ export class DenoWatcher implements IWatcher {
 
     try {
       if (kind === 'create') {
+        // Create events (atomic saves) don't need stabilization - file is already complete
         const stats = await this.statSafe(filePath);
         if (stats) {
-          // Wait for write to stabilize
-          await this.waitForWriteFinish(filePath);
-          const finalStats = await this.statSafe(filePath);
-
-          if (finalStats) {
           this.watchedFiles.add(filePath);
-            const eventType: TWatchEventType = finalStats.isDirectory() ? 'addDir' : 'add';
+          const eventType: TWatchEventType = stats.isDirectory() ? 'addDir' : 'add';
-            this.events$.next({ type: eventType, path: filePath, stats: finalStats });
+          this.events$.next({ type: eventType, path: filePath, stats });
-          }
         }
       } else if (kind === 'modify') {
+        // Modify events are in-place writes - use stabilization
         const stats = await this.statSafe(filePath);
         if (stats && !stats.isDirectory()) {
           // Wait for write to stabilize
@@ -212,6 +226,7 @@ export class DenoWatcher implements IWatcher {
     return new Promise((resolve) => {
       let lastSize = -1;
       let lastChange = Date.now();
+      const startTime = Date.now();
 
       const poll = async () => {
         try {
@@ -222,6 +237,14 @@ export class DenoWatcher implements IWatcher {
           }
 
           const now = Date.now();
+
+          // Check if we've exceeded max wait time - resolve immediately
+          if (now - startTime >= this.options.maxWaitTime) {
+            this.pendingWrites.delete(filePath);
+            resolve();
+            return;
+          }
+
           if (stats.size !== lastSize) {
             lastSize = stats.size;
             lastChange = now;

ts/watchers/watcher.node.ts

@@ -20,10 +20,24 @@ export class NodeWatcher implements IWatcher {
   constructor(private options: IWatcherOptions) {
     this.writeStabilizer = new WriteStabilizer(
       options.stabilityThreshold,
-      options.pollInterval
+      options.pollInterval,
+      options.maxWaitTime
     );
   }
 
+  /**
+   * Check if a file is a temporary file created by editors
+   */
+  private isTemporaryFile(filePath: string): boolean {
+    const basename = path.basename(filePath);
+    // Editor temp files: *.tmp.*, *.swp, *.swx, *~, .#*
+    if (basename.includes('.tmp.')) return true;
+    if (basename.endsWith('.swp') || basename.endsWith('.swx')) return true;
+    if (basename.endsWith('~')) return true;
+    if (basename.startsWith('.#')) return true;
+    return false;
+  }
+
   get isWatching(): boolean {
     return this._isWatching;
   }
@@ -114,6 +128,11 @@ export class NodeWatcher implements IWatcher {
   ): Promise<void> {
     const fullPath = path.join(basePath, filename);
 
+    // Skip temporary files created by editors (atomic saves)
+    if (this.isTemporaryFile(fullPath)) {
+      return;
+    }
+
     // Throttle duplicate events
     if (!this.shouldEmit(fullPath, eventType)) {
       return;
@@ -132,23 +151,14 @@ export class NodeWatcher implements IWatcher {
               this.events$.next({ type: 'addDir', path: fullPath, stats });
             }
           } else {
-            // Wait for write to stabilize before emitting
+            // Rename events (atomic saves) don't need stabilization - file is already complete
-            try {
-              const stableStats = await this.writeStabilizer.waitForWriteFinish(fullPath);
             const wasWatched = this.watchedFiles.has(fullPath);
             this.watchedFiles.add(fullPath);
             this.events$.next({
               type: wasWatched ? 'change' : 'add',
               path: fullPath,
-                stats: stableStats
+              stats
             });
-            } catch {
-              // File was deleted during stabilization
-              if (this.watchedFiles.has(fullPath)) {
-                this.watchedFiles.delete(fullPath);
-                this.events$.next({ type: 'unlink', path: fullPath });
-              }
-            }
           }
         } else {
           // File doesn't exist - it was deleted
@@ -162,7 +172,7 @@ export class NodeWatcher implements IWatcher {
           }
         }
       } else if (eventType === 'change') {
-        // File was modified
+        // File was modified in-place - use stabilization for streaming writes
         if (stats && !stats.isDirectory()) {
           try {
             const stableStats = await this.writeStabilizer.waitForWriteFinish(fullPath);