v6.2.5

changelog.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 2025-12-11 - 6.2.5 - fix(watcher.node)
+Normalize paths and improve Node watcher robustness: restart/rescan on errors (including ENOSPC), clear stale state, and remove legacy throttler
+
+- Normalize all paths to absolute at watcher entry points (watchPath, handleFsEvent, scanDirectory) to avoid relative/absolute mismatch bugs
+- On watcher restart: clear pending unlink timeouts, dispose stale DirEntry data, and perform a rescan to catch files created during the restart window
+- Trigger watcher restart on ENOSPC (inotify limit) errors instead of only logging the error
+- Remove the previous Throttler implementation and rely on the existing debounce + event-sequence tracking to handle rapid events
+- Atomic write handling and queued unlink behavior preserved; pending unlinks are cleared for restarted base paths to avoid stale events
+
+## 2025-12-11 - 6.2.4 - fix(tests)
+Stabilize tests and document chokidar-inspired Node watcher architecture
+
+- test: add waitForFileEvent helper to wait for events for a specific file (reduces test flakiness)
+- test: add small delays after unlink cleanup to account for atomic/temp-file debounce windows
+- docs: expand readme.hints.md with a detailed Node watcher architecture section (DirEntry, Throttler, atomic write handling, closer registry, constants and config)
+- docs: list updated test files and coverage scenarios (inode detection, atomic writes, stress tests)
+
+## 2025-12-11 - 6.2.3 - fix(watcher.node)
+Improve handling of temporary files from atomic editor writes in Node watcher
+
+- Detect temporary files produced by atomic editor saves and attempt to map them to the real target file instead of silently skipping the event
+- Add getTempFileTarget() to extract the real file path from temp filenames (supports patterns like file.ts.tmp.PID.TIMESTAMP and generic .tmp.*)
+- When a temp-file event is seen, queue a corresponding event for the resolved real file after a short delay (50ms) to allow rename/replace to complete
+- Add logging around temp file detection and real-file checks to aid debugging
+
 ## 2025-12-11 - 6.2.2 - fix(watcher.node)
 Defer events during initial scan, track full event sequences, and harden watcher shutdown
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/smartwatch",
-  "version": "6.2.2",
+  "version": "6.2.5",
   "private": false,
   "description": "A cross-runtime file watcher with glob pattern support for Node.js, Deno, and Bun.",
   "main": "dist_ts/index.js",

readme.hints.md

@@ -71,6 +71,66 @@ The `WriteStabilizer` class replaces chokidar's built-in write stabilization:
 - **Deno**: Works on all versions with `Deno.watchFs()`
 - **Bun**: Uses Node.js compatibility layer
 
+### Architecture (v6.3.0+) - Chokidar-Inspired
+
+The Node.js watcher has been refactored with elegant patterns inspired by [chokidar](https://github.com/paulmillr/chokidar):
+
+**DirEntry Class:**
+- Tracks directory contents with proper disposal
+- Encapsulates file tracking and inode management
+- `dispose()` method freezes object to catch use-after-cleanup bugs
+
+**Path Normalization (v6.3.1+):**
+- ALL paths are normalized to absolute at entry points
+- Prevents relative/absolute path mismatch bugs
+- `watchPath()`, `handleFsEvent()`, `scanDirectory()` all resolve paths
+
+**Restart Rescan (v6.3.1+):**
+- When watcher restarts, it rescans the directory
+- Catches files created during the restart window
+- Clears stale DirEntry data before rescan
+- Clears pending unlink timeouts to prevent stale events
+
+**ENOSPC Handling (v6.3.1+):**
+- inotify limit errors now trigger watcher restart
+- Previously only logged error without recovery
+
+**Atomic Write Handling:**
+- Unlink events are queued with 100ms delay
+- If add event arrives for same path within delay, unlink is cancelled
+- Emits single `change` event instead of `unlink` + `add`
+- Handles editor atomic saves elegantly
+
+**Closer Registry:**
+- Maps watch paths to cleanup functions
+- Ensures proper resource cleanup on stop
+- `addCloser()` / `runClosers()` pattern
+
+**Event Constants Object:**
+```typescript
+const EV = {
+  ADD: 'add',
+  CHANGE: 'change',
+  UNLINK: 'unlink',
+  ADD_DIR: 'addDir',
+  UNLINK_DIR: 'unlinkDir',
+  READY: 'ready',
+  ERROR: 'error',
+} as const;
+```
+
+**Configuration Constants:**
+```typescript
+const CONFIG = {
+  MAX_RETRIES: 3,
+  INITIAL_RESTART_DELAY: 1000,
+  MAX_RESTART_DELAY: 30000,
+  HEALTH_CHECK_INTERVAL: 30000,
+  ATOMIC_DELAY: 100,
+  TEMP_FILE_DELAY: 50,
+} as const;
+```
+
 ### Robustness Features (v6.1.0+)
 
 The Node.js watcher includes automatic recovery mechanisms based on learnings from [chokidar](https://github.com/paulmillr/chokidar) and known [fs.watch issues](https://github.com/nodejs/node/issues/47058):
@@ -155,10 +215,20 @@ Example log output:
 pnpm test
 ```
 
+Test files:
+- **test.basic.ts** - Core functionality (add, change, unlink events)
+- **test.inode.ts** - Inode change detection, atomic writes
+- **test.stress.ts** - Rapid modifications, many files, interleaved operations
+
 Tests verify:
 - Creating Smartwatch instance
 - Adding glob patterns
-- Receiving 'add' events for new files
+- Receiving 'add', 'change', 'unlink' events
+- Inode change detection (delete+recreate pattern)
+- Atomic write pattern (temp file + rename)
+- Rapid file modifications (debouncing)
+- Many files created rapidly
+- Interleaved add/change/delete operations
 - Graceful shutdown
 
 ## Dev Dependencies

test/test.basic.ts

@@ -35,6 +35,30 @@ async function waitForEvent<T>(
   });
 }
 
+// Helper to wait for a specific file's event (filters by filename)
+async function waitForFileEvent<T extends [string, ...any[]]>(
+  observable: smartrx.rxjs.Observable<T>,
+  expectedFile: string,
+  timeoutMs: number = 5000
+): Promise<T> {
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      subscription.unsubscribe();
+      reject(new Error(`Timeout waiting for event on ${expectedFile} after ${timeoutMs}ms`));
+    }, timeoutMs);
+
+    const subscription = observable.subscribe((value) => {
+      const [filePath] = value;
+      if (filePath.includes(expectedFile)) {
+        clearTimeout(timeout);
+        subscription.unsubscribe();
+        resolve(value);
+      }
+      // Otherwise keep waiting for the right file
+    });
+  });
+}
+
 let testSmartwatch: smartwatch.Smartwatch;
 
 // ===========================================
@@ -63,8 +87,9 @@ tap.test('should detect ADD event for new files', async () => {
   const [filePath] = await eventPromise;
   expect(filePath).toInclude('add-test.txt');
 
-  // Cleanup
+  // Cleanup - wait for atomic delay to complete (100ms debounce + 100ms atomic)
   await fs.promises.unlink(testFile);
+  await delay(250);
 });
 
 tap.test('should detect CHANGE event for modified files', async () => {
@@ -84,8 +109,9 @@ tap.test('should detect CHANGE event for modified files', async () => {
   const [filePath] = await eventPromise;
   expect(filePath).toInclude('change-test.txt');
 
-  // Cleanup
+  // Cleanup - wait for atomic delay to complete
   await fs.promises.unlink(testFile);
+  await delay(250);
 });
 
 tap.test('should detect UNLINK event for deleted files', async () => {
@@ -97,7 +123,9 @@ tap.test('should detect UNLINK event for deleted files', async () => {
   await delay(200);
 
   const unlinkObservable = await testSmartwatch.getObservableFor('unlink');
-  const eventPromise = waitForEvent(unlinkObservable);
+
+  // Use file-specific wait to handle any pending unlinks from other tests
+  const eventPromise = waitForFileEvent(unlinkObservable, 'unlink-test.txt');
 
   // Delete the file
   await fs.promises.unlink(testFile);

ts/00_commitinfo_data.ts

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