v5.1.0

changelog.md

@@ -1,5 +1,23 @@
 # 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.
+
+- Package name changed from @push.rocks/smartchok to @push.rocks/smartwatch in package.json
+- Repository, homepage and issue URLs updated to point to the new smartwatch repository
+- Author changed to Task Venture Capital GmbH in package metadata
+- README updated: install commands, import examples and references now use @push.rocks/smartwatch
+- Documentation text and branding updated throughout README (project name, internal references)
+
 ## 2025-11-30 - 4.0.1 - fix(readme)
 Update README: refine description and clarify trademark/legal information
 

package.json

@@ -1,6 +1,6 @@
 {
-  "name": "@push.rocks/smartchok",
-  "version": "4.0.1",
+  "name": "@push.rocks/smartwatch",
+  "version": "5.1.0",
   "private": false,
   "description": "A cross-runtime file watcher with glob pattern support for Node.js, Deno, and Bun.",
   "main": "dist_ts/index.js",
@@ -13,14 +13,14 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://code.foss.global/push.rocks/smartchok.git"
+    "url": "https://code.foss.global/push.rocks/smartwatch.git"
   },
-  "author": "Lossless GmbH",
+  "author": "Task Venture Capital GmbH",
   "license": "MIT",
   "bugs": {
-    "url": "https://gitlab.com/push.rocks/smartchok/issues"
+    "url": "https://gitlab.com/push.rocks/smartwatch/issues"
   },
-  "homepage": "https://code.foss.global/push.rocks/smartchok",
+  "homepage": "https://code.foss.global/push.rocks/smartwatch",
   "engines": {
     "node": ">=20.0.0"
   },

readme.md

@@ -1,4 +1,4 @@
-# @push.rocks/smartchok
+# @push.rocks/smartwatch
 
 A lightweight, cross-runtime file watcher with glob pattern support for **Node.js**, **Deno**, and **Bun**. Zero heavyweight dependencies — just native file watching APIs for maximum performance. 🚀
 
@@ -9,9 +9,9 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community
 ## Install
 
 ```sh
-npm install @push.rocks/smartchok
+npm install @push.rocks/smartwatch
 # or
-pnpm add @push.rocks/smartchok
+pnpm add @push.rocks/smartwatch
 ```
 
 ## Features
@@ -30,7 +30,7 @@ pnpm add @push.rocks/smartchok
 ### Basic Setup
 
 ```typescript
-import { Smartwatch } from '@push.rocks/smartchok';
+import { Smartwatch } from '@push.rocks/smartwatch';
 
 // Create a watcher with glob patterns
 const watcher = new Smartwatch([
@@ -110,7 +110,7 @@ await watcher.stop();
 ### Complete Example
 
 ```typescript
-import { Smartwatch } from '@push.rocks/smartchok';
+import { Smartwatch } from '@push.rocks/smartwatch';
 
 async function watchProject() {
   // Initialize with patterns
@@ -155,7 +155,7 @@ watchProject();
 
 ## How It Works
 
-smartchok uses native file watching APIs for each runtime:
+smartwatch uses native file watching APIs for each runtime:
 
 | Runtime         | API Used                         |
 |-----------------|----------------------------------|
@@ -165,7 +165,7 @@ smartchok uses native file watching APIs for each runtime:
 
 ### Under the Hood
 
-Native file watching APIs don't support glob patterns directly, so smartchok handles pattern matching internally:
+Native file watching APIs don't support glob patterns directly, so smartwatch handles pattern matching internally:
 
 1. **Base path extraction** — Extracts the static portion from each glob pattern (e.g., `./src/` from `./src/**/*.ts`)
 2. **Efficient watching** — Native watchers monitor only the base directories
@@ -174,7 +174,7 @@ Native file watching APIs don't support glob patterns directly, so smartchok han
 
 ### Write Stabilization
 
-smartchok includes built-in write stabilization (similar to chokidar's `awaitWriteFinish`). When a file is being written, events are held until the file size stabilizes, preventing multiple events for a single write operation.
+smartwatch includes built-in write stabilization (similar to chokidar's `awaitWriteFinish`). When a file is being written, events are held until the file size stabilizes, preventing multiple events for a single write operation.
 
 Default settings:
 - **Stability threshold**: 300ms
@@ -226,9 +226,9 @@ type TFsEvent = 'add' | 'addDir' | 'change' | 'error' | 'unlink' | 'unlinkDir' |
 type TSmartwatchStatus = 'idle' | 'starting' | 'watching';
 ```
 
-## Why smartchok?
+## Why smartwatch?
 
-| Feature                 | smartchok            | chokidar           |
+| Feature                 | smartwatch            | chokidar           |
 |-------------------------|----------------------|--------------------|
 | Native API              | ✅ Direct `fs.watch`  | ❌ FSEvents bindings |
 | Cross-runtime           | ✅ Node, Deno, Bun    | ❌ Node only        |
@@ -237,7 +237,7 @@ type TSmartwatchStatus = 'idle' | 'starting' | 'watching';
 | Glob support            | ✅ picomatch          | ✅ anymatch         |
 | Bundle size             | ~15KB                | ~200KB+            |
 
-If you need a lightweight file watcher without native compilation headaches, smartchok has you covered.
+If you need a lightweight file watcher without native compilation headaches, smartwatch has you covered.
 
 ## License and Legal Information
 

ts/00_commitinfo_data.ts

@@ -2,7 +2,7 @@
  * autocreated commitinfo by @push.rocks/commitinfo
  */
 export const commitinfo = {
-  name: '@push.rocks/smartchok',
-  version: '4.0.1',
+  name: '@push.rocks/smartwatch',
+  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,
-      pollInterval: 100
+      stabilityThreshold: 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 pollInterval: number = 100
+    private stabilityThreshold: 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,
-  pollInterval: 100
+  stabilityThreshold: 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';
-            this.events$.next({ type: eventType, path: filePath, stats: finalStats });
-          }
+          this.watchedFiles.add(filePath);
+          const eventType: TWatchEventType = stats.isDirectory() ? 'addDir' : 'add';
+          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
-            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
-              });
-            } catch {
-              // File was deleted during stabilization
-              if (this.watchedFiles.has(fullPath)) {
-                this.watchedFiles.delete(fullPath);
-                this.events$.next({ type: 'unlink', path: fullPath });
-              }
-            }
+            // 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({
+              type: wasWatched ? 'change' : 'add',
+              path: fullPath,
+              stats
+            });
           }
         } 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);