v6.2.4

changelog.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 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
+
+- Defer fs.watch events that arrive during the initial directory scan and process them after the scan completes to avoid race conditions where watchedFiles isn't populated.
+- Debounce now tracks the full sequence of events per file (rename/change) instead of collapsing to the last event, preventing intermediate events from being lost.
+- Detect delete+recreate via inode changes and emit unlink then add when appropriate; handle rapid create+delete sequences by emitting both events.
+- During stop(), cancel pending debounced emits before flipping _isWatching and make handleFsEvent return early when watcher is stopped to prevent orphaned timeouts and post-stop emits.
+- Add verbose logging of event sequences to aid debugging of complex fs event scenarios.
+- Update tests to expect unlink + add for inode replacement scenarios.
+- Version bump from 6.2.1 → 6.2.2
+
 ## 2025-12-10 - 6.2.1 - fix(watcher.node)
 Handle fs.watch close without spurious restarts; add tests and improve test runner
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/smartwatch",
-  "version": "6.2.1",
+  "version": "6.2.4",
   "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,57 @@ 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
+
+**Throttler Pattern:**
+- More sophisticated than simple debounce
+- Tracks count of suppressed events
+- Returns `false` if already throttled, `Throttler` object otherwise
+- Used for change events to prevent duplicate emissions
+
+**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):
@@ -107,8 +158,27 @@ The Node.js watcher includes automatic recovery mechanisms based on learnings fr
 - Files created after initial scan are properly detected
 - Untracked file deletions emit `unlink` events instead of being silently dropped
 
+**Event Deferral During Initial Scan (v6.2.2+):**
+- Events are queued until initial scan completes
+- Prevents race conditions where events arrive before `watchedFiles` is populated
+- Deferred events are processed after scan completes
+
+**Event Sequence Tracking (v6.2.2+):**
+- Debounce now tracks ALL events in sequence, not just the last one
+- Prevents losing intermediate events (e.g., add→change→delete no longer loses add)
+- Intelligent processing of event sequences:
+  - Delete+recreate with inode change → emits `unlink` then `add`
+  - Rapid create+delete → emits both events
+  - Multiple changes → single `change` event (debouncing)
+
+**Post-Stop Event Guards (v6.2.2+):**
+- `handleFsEvent()` returns early if watcher is stopped
+- Pending emits are cleared BEFORE setting `_isWatching = false`
+- Prevents orphaned timeouts and events after `stop()`
+
 **Verbose logging:**
 - All lifecycle events logged with `[smartwatch]` prefix
+- Event sequences logged for debugging complex scenarios
 - Helps debug watcher issues in production
 
 Example log output:
@@ -118,9 +188,9 @@ Example log output:
 [smartwatch] Starting health check (every 30s)
 [smartwatch] Watcher started with 1 active watcher(s)
 [smartwatch] Health check: 1 watchers active
-[smartwatch] Inode changed for ./src: 12345 -> 67890
+[smartwatch] Processing event sequence for ./src/file.ts: [rename, rename, change]
-[smartwatch] fs.watch watches inode, not path - restarting watcher
 [smartwatch] File inode changed (delete+recreate): ./src/file.ts
+[smartwatch]   Previous inode: 12345, current: 67890
 ```
 
 ### Known fs.watch Limitations
@@ -136,10 +206,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);

test/test.inode.ts

@@ -60,8 +60,12 @@ tap.test('should detect delete+recreate (inode change scenario)', async () => {
   const initialInode = initialStats.ino;
   console.log(`[test] Initial inode: ${initialInode}`);
 
-  const changeObservable = await testSmartwatch.getObservableFor('change');
+  // With event sequence tracking, delete+recreate emits: unlink, then add
-  const eventPromise = waitForEvent(changeObservable, 3000);
+  // This is more accurate than just emitting 'change'
+  const unlinkObservable = await testSmartwatch.getObservableFor('unlink');
+  const addObservable = await testSmartwatch.getObservableFor('add');
+  const unlinkPromise = waitForEvent(unlinkObservable, 3000);
+  const addPromise = waitForEvent(addObservable, 3000);
 
   // Delete and recreate (this creates a new inode)
   await fs.promises.unlink(testFile);
@@ -73,9 +77,11 @@ tap.test('should detect delete+recreate (inode change scenario)', async () => {
   console.log(`[test] New inode: ${newInode}`);
   expect(newInode).not.toEqual(initialInode);
 
-  // Should still detect the change
+  // Should detect both unlink and add events for delete+recreate
-  const [filePath] = await eventPromise;
+  const [[unlinkPath], [addPath]] = await Promise.all([unlinkPromise, addPromise]);
-  expect(filePath).toInclude('inode-test.txt');
+  expect(unlinkPath).toInclude('inode-test.txt');
+  expect(addPath).toInclude('inode-test.txt');
+  console.log(`[test] Detected unlink + add events for delete+recreate`);
 
   // Cleanup
   await fs.promises.unlink(testFile);

ts/00_commitinfo_data.ts

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