v6.2.4

changelog.md

@@ -1,5 +1,92 @@
 # 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
+
+- Prevent spurious restarts and noisy warnings on fs.watch 'close' by checking the internal isWatching flag before logging and restarting (ts/watchers/watcher.node.ts).
+- Add comprehensive test suites covering basic operations, inode-change detection, atomic writes and stress scenarios (test/test.basic.ts, test/test.inode.ts, test/test.stress.ts).
+- Remove outdated test (test/test.ts) and delete the test asset test/assets/hi.txt.
+- Update test script in package.json to enable verbose logging, write a logfile and increase timeout to 120s to reduce flakiness in test runs.
+
+## 2025-12-10 - 6.2.0 - feat(watchers)
+Improve Node watcher robustness: file-level inode tracking, abortable restarts, restart race guards, and untracked-file handling
+
+- Add file-level inode tracking to detect delete+recreate (editor atomic saves) and emit correct 'change'/'add' events
+- Make restart delays abortable via AbortController so stop() cancels pending restarts and prevents orphan watchers
+- Guard against concurrent/dual restarts with restartingPaths to avoid race conditions between health checks and error handlers
+- Emit 'unlink' for deletions of previously untracked files (files created after initial scan) and clean up inode state
+- Track file inodes during initial scan and update/cleanup inode state on events
+- Improve logging for restart/inode/delete+recreate scenarios and update documentation/readme hints to v6.2.0+
+
+## 2025-12-08 - 6.1.1 - fix(watchers/watcher.node)
+Improve Node watcher robustness: inode tracking, ENOSPC detection, enhanced health checks and temp-file handling
+
+- Track directory inodes (watchedInodes) and restart watchers if inode changes are detected (addresses stale watchers when directories are replaced).
+- Health check now validates inode stability and explicitly detects ENOSPC (inotify max_user_watches) errors, emitting errors and logging a recommended fix command.
+- Detect ENOSPC in FSWatcher error events and log guidance to increase inotify limits.
+- Clear inode tracking state on watcher stop to avoid stale state across restarts.
+- Improve temporary file handling and logging to avoid dropping events for atomic writes (only skip pure temp files and log skipped temp events).
+- Documentation (readme.hints.md) updated with robustness notes, known fs.watch limitations, and example logs.
+
+## 2025-12-08 - 6.1.0 - feat(watcher.node)
+Add automatic restart, periodic health checks, and safe event emission to Node watcher; improve logging and stat handling
+
+- NodeWatcher: introduced safeEmit() to isolate subscriber errors and prevent watcher crashes
+- Auto-restart on failure with exponential backoff (1s → 30s) and up to 3 retry attempts per watched base path
+- Periodic health checks (every 30s) to detect missing watched paths and trigger automatic restarts
+- Handle unexpected FSWatcher 'close' events and restart watchers when they close silently
+- Verbose lifecycle logging with `[smartwatch]` prefix for start/stop/health/restart events
+- Clear restart tracking and stop health checks on watcher.stop() to ensure clean shutdown
+- Improved statSafe() to normalize followSymlinks logic and log non-ENO errors as warnings
+- Updated readme.hints.md documenting the new robustness features (v6.1.0+)
+
+## 2025-12-08 - 6.0.0 - BREAKING CHANGE(watchers)
+Replace polling-based write stabilization with debounce-based event coalescing and simplify watcher options
+
+- Remove polling-based WriteStabilizer (ts/utils/write-stabilizer.ts) and related waitForWriteFinish logic
+- Introduce debounce-based coalescing (debounceMs) for Node and Deno watchers (ts/watchers/watcher.node.ts, ts/watchers/watcher.deno.ts)
+- Change IWatcherOptions: remove stabilityThreshold/pollInterval/maxWaitTime and add debounceMs
+- Default watcher options updated to use debounceMs = 100
+- Node/Deno watchers now skip editor temp files earlier, debounce duplicate events, and emit events directly (no size polling)
+- Updated default watcher creation in Smartwatch to pass debounceMs
+- Update package.json build script to run 'tsbuild tsfolders'
+
+## 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.json

@@ -1,14 +1,14 @@
 {
   "name": "@push.rocks/smartwatch",
-  "version": "5.0.0",
+  "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",
   "typings": "dist_ts/index.d.ts",
   "scripts": {
-    "test": "(npm run prepareTest && tstest test/)",
+    "test": "(npm run prepareTest && tstest test/ --verbose --logfile --timeout 120)",
     "prepareTest": "(rm -f ./test/assets/hi.txt)",
-    "build": "tsbuild",
+    "build": "tsbuild tsfolders",
     "buildDocs": "tsdoc"
   },
   "repository": {

readme.hints.md

@@ -71,16 +71,155 @@ 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):
+
+**Auto-restart on failure:**
+- Watchers automatically restart when errors occur
+- Exponential backoff (1s → 30s max)
+- Maximum 3 retry attempts before giving up
+- **v6.2.0+**: Race condition guards prevent orphan watchers when `stop()` is called during restart
+
+**Inode tracking (critical for long-running watchers):**
+- `fs.watch()` watches the **inode**, not the path!
+- When directories are replaced (git checkout, atomic saves), the inode changes
+- Health check detects inode changes and restarts the watcher
+- **v6.2.0+**: File-level inode tracking detects delete+recreate (common editor save pattern)
+- This is the most common cause of "watcher stops working after some time"
+
+**Health check monitoring:**
+- 30-second periodic health checks
+- Detects when watched paths disappear
+- Detects inode changes (directory replacement)
+- Detects ENOSPC errors (inotify limit exceeded)
+- **v6.2.0+**: Protected against dual-restart race conditions (health check + error handler)
+
+**ENOSPC detection (Linux inotify limit):**
+- Detects when `/proc/sys/fs/inotify/max_user_watches` is exceeded
+- Logs fix command: `echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p`
+
+**Error isolation:**
+- Subscriber errors don't crash the watcher
+- All events emitted via `safeEmit()` with try-catch
+
+**Untracked file handling (v6.2.0+):**
+- 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:
+```
+[smartwatch] Starting watcher for 1 base path(s)...
+[smartwatch] Started watching: ./test/assets/
+[smartwatch] Starting health check (every 30s)
+[smartwatch] Watcher started with 1 active watcher(s)
+[smartwatch] Health check: 1 watchers active
+[smartwatch] Processing event sequence for ./src/file.ts: [rename, rename, change]
+[smartwatch] File inode changed (delete+recreate): ./src/file.ts
+[smartwatch]   Previous inode: 12345, current: 67890
+```
+
+### Known fs.watch Limitations
+
+1. **Watches inode, not path** - If a directory is replaced, watcher goes stale
+2. **inotify limits on Linux** - Default `max_user_watches` (8192) may be too low
+3. **No events for some atomic writes** - Some editors' save patterns may not trigger events
+4. **Platform differences** - Linux uses inotify, macOS uses FSEvents/kqueue
+
 ### Testing
 
 ```bash
 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/assets/hi.txt

@@ -1 +0,0 @@
-HI

test/test.basic.ts

@@ -0,0 +1,155 @@
+import { tap, expect } from '@git.zone/tstest/tapbundle';
+import * as smartwatch from '../ts/index.js';
+import * as smartfile from '@push.rocks/smartfile';
+import * as smartrx from '@push.rocks/smartrx';
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+// Skip in CI
+if (process.env.CI) {
+  process.exit(0);
+}
+
+const TEST_DIR = './test/assets';
+
+// Helper to delay
+const delay = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
+
+// Helper to wait for an event with timeout
+async function waitForEvent<T>(
+  observable: smartrx.rxjs.Observable<T>,
+  timeoutMs: number = 5000
+): Promise<T> {
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      subscription.unsubscribe();
+      reject(new Error(`Timeout waiting for event after ${timeoutMs}ms`));
+    }, timeoutMs);
+
+    const subscription = observable.subscribe((value) => {
+      clearTimeout(timeout);
+      subscription.unsubscribe();
+      resolve(value);
+    });
+  });
+}
+
+// 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;
+
+// ===========================================
+// BASIC TESTS
+// ===========================================
+
+tap.test('should create a new instance', async () => {
+  testSmartwatch = new smartwatch.Smartwatch([]);
+  expect(testSmartwatch).toBeInstanceOf(smartwatch.Smartwatch);
+});
+
+tap.test('should add paths and start watching', async () => {
+  testSmartwatch.add([`${TEST_DIR}/**/*.txt`]);
+  await testSmartwatch.start();
+  expect(testSmartwatch.status).toEqual('watching');
+});
+
+tap.test('should detect ADD event for new files', async () => {
+  const addObservable = await testSmartwatch.getObservableFor('add');
+  const eventPromise = waitForEvent(addObservable);
+
+  // Create a new file
+  const testFile = path.join(TEST_DIR, 'add-test.txt');
+  await smartfile.memory.toFs('test content', testFile);
+
+  const [filePath] = await eventPromise;
+  expect(filePath).toInclude('add-test.txt');
+
+  // 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 () => {
+  // First create the file
+  const testFile = path.join(TEST_DIR, 'change-test.txt');
+  await smartfile.memory.toFs('initial content', testFile);
+
+  // Wait for add event to complete
+  await delay(200);
+
+  const changeObservable = await testSmartwatch.getObservableFor('change');
+  const eventPromise = waitForEvent(changeObservable);
+
+  // Modify the file
+  await smartfile.memory.toFs('modified content', testFile);
+
+  const [filePath] = await eventPromise;
+  expect(filePath).toInclude('change-test.txt');
+
+  // 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 () => {
+  // First create the file
+  const testFile = path.join(TEST_DIR, 'unlink-test.txt');
+  await smartfile.memory.toFs('to be deleted', testFile);
+
+  // Wait for add event to complete
+  await delay(200);
+
+  const unlinkObservable = await testSmartwatch.getObservableFor('unlink');
+
+  // 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);
+
+  const [filePath] = await eventPromise;
+  expect(filePath).toInclude('unlink-test.txt');
+});
+
+tap.test('should stop the watch process', async () => {
+  await testSmartwatch.stop();
+  expect(testSmartwatch.status).toEqual('idle');
+});
+
+tap.test('cleanup: remove any remaining test files', async () => {
+  const files = await fs.promises.readdir(TEST_DIR);
+  for (const file of files) {
+    if (file.startsWith('add-') || file.startsWith('change-') || file.startsWith('unlink-')) {
+      try {
+        await fs.promises.unlink(path.join(TEST_DIR, file));
+      } catch {
+        // Ignore
+      }
+    }
+  }
+});
+
+export default tap.start();

test/test.inode.ts

@@ -0,0 +1,135 @@
+import { tap, expect } from '@git.zone/tstest/tapbundle';
+import * as smartwatch from '../ts/index.js';
+import * as smartfile from '@push.rocks/smartfile';
+import * as smartrx from '@push.rocks/smartrx';
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+// Skip in CI
+if (process.env.CI) {
+  process.exit(0);
+}
+
+const TEST_DIR = './test/assets';
+
+// Helper to delay
+const delay = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
+
+// Helper to wait for an event with timeout
+async function waitForEvent<T>(
+  observable: smartrx.rxjs.Observable<T>,
+  timeoutMs: number = 5000
+): Promise<T> {
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      subscription.unsubscribe();
+      reject(new Error(`Timeout waiting for event after ${timeoutMs}ms`));
+    }, timeoutMs);
+
+    const subscription = observable.subscribe((value) => {
+      clearTimeout(timeout);
+      subscription.unsubscribe();
+      resolve(value);
+    });
+  });
+}
+
+let testSmartwatch: smartwatch.Smartwatch;
+
+// ===========================================
+// INODE CHANGE DETECTION TESTS
+// ===========================================
+
+tap.test('setup: start watcher', async () => {
+  testSmartwatch = new smartwatch.Smartwatch([`${TEST_DIR}/**/*.txt`]);
+  await testSmartwatch.start();
+  expect(testSmartwatch.status).toEqual('watching');
+});
+
+tap.test('should detect delete+recreate (inode change scenario)', async () => {
+  // This simulates what many editors do: delete file, create new file
+  const testFile = path.join(TEST_DIR, 'inode-test.txt');
+
+  // Create initial file
+  await smartfile.memory.toFs('initial content', testFile);
+  await delay(200);
+
+  // Get the initial inode
+  const initialStats = await fs.promises.stat(testFile);
+  const initialInode = initialStats.ino;
+  console.log(`[test] Initial inode: ${initialInode}`);
+
+  // With event sequence tracking, delete+recreate emits: unlink, then add
+  // 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);
+  await smartfile.memory.toFs('recreated content', testFile);
+
+  // Check inode changed
+  const newStats = await fs.promises.stat(testFile);
+  const newInode = newStats.ino;
+  console.log(`[test] New inode: ${newInode}`);
+  expect(newInode).not.toEqual(initialInode);
+
+  // Should detect both unlink and add events for delete+recreate
+  const [[unlinkPath], [addPath]] = await Promise.all([unlinkPromise, addPromise]);
+  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);
+});
+
+tap.test('should detect atomic write pattern (temp file + rename)', async () => {
+  // This simulates what Claude Code and many editors do:
+  // 1. Write to temp file (file.txt.tmp.12345)
+  // 2. Rename temp file to target file
+  const testFile = path.join(TEST_DIR, 'atomic-test.txt');
+  const tempFile = path.join(TEST_DIR, 'atomic-test.txt.tmp.12345');
+
+  // Create initial file
+  await smartfile.memory.toFs('initial content', testFile);
+  await delay(200);
+
+  const changeObservable = await testSmartwatch.getObservableFor('change');
+  const eventPromise = waitForEvent(changeObservable, 3000);
+
+  // Atomic write: create temp file then rename
+  await smartfile.memory.toFs('atomic content', tempFile);
+  await fs.promises.rename(tempFile, testFile);
+
+  // Should detect the change to the target file
+  const [filePath] = await eventPromise;
+  expect(filePath).toInclude('atomic-test.txt');
+  expect(filePath).not.toInclude('.tmp.');
+
+  // Cleanup
+  await fs.promises.unlink(testFile);
+});
+
+tap.test('teardown: stop watcher', async () => {
+  await testSmartwatch.stop();
+  expect(testSmartwatch.status).toEqual('idle');
+});
+
+tap.test('cleanup: remove test files', async () => {
+  const files = await fs.promises.readdir(TEST_DIR);
+  for (const file of files) {
+    if (file.startsWith('inode-') || file.startsWith('atomic-')) {
+      try {
+        await fs.promises.unlink(path.join(TEST_DIR, file));
+      } catch {
+        // Ignore
+      }
+    }
+  }
+});
+
+export default tap.start();

test/test.stress.ts

@@ -0,0 +1,174 @@
+import { tap, expect } from '@git.zone/tstest/tapbundle';
+import * as smartwatch from '../ts/index.js';
+import * as smartfile from '@push.rocks/smartfile';
+import * as smartrx from '@push.rocks/smartrx';
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+// Skip in CI
+if (process.env.CI) {
+  process.exit(0);
+}
+
+const TEST_DIR = './test/assets';
+
+// Helper to delay
+const delay = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
+
+// Helper to collect events
+function collectEvents<T>(
+  observable: smartrx.rxjs.Observable<T>,
+  durationMs: number
+): Promise<T[]> {
+  return new Promise((resolve) => {
+    const events: T[] = [];
+    const subscription = observable.subscribe((value) => {
+      events.push(value);
+    });
+
+    setTimeout(() => {
+      subscription.unsubscribe();
+      resolve(events);
+    }, durationMs);
+  });
+}
+
+let testSmartwatch: smartwatch.Smartwatch;
+
+// ===========================================
+// STRESS TESTS
+// ===========================================
+
+tap.test('setup: start watcher', async () => {
+  testSmartwatch = new smartwatch.Smartwatch([`${TEST_DIR}/**/*.txt`]);
+  await testSmartwatch.start();
+  expect(testSmartwatch.status).toEqual('watching');
+});
+
+tap.test('STRESS: rapid file modifications', async () => {
+  const testFile = path.join(TEST_DIR, 'stress-rapid.txt');
+
+  // Create initial file
+  await smartfile.memory.toFs('initial', testFile);
+  await delay(200);
+
+  const changeObservable = await testSmartwatch.getObservableFor('change');
+
+  // Rapidly modify the file 20 times
+  const RAPID_CHANGES = 20;
+  const eventCollector = collectEvents(changeObservable, 3000);
+
+  for (let i = 0; i < RAPID_CHANGES; i++) {
+    await smartfile.memory.toFs(`content ${i}`, testFile);
+    await delay(10); // 10ms between writes
+  }
+
+  const events = await eventCollector;
+  console.log(`[test] Rapid changes: sent ${RAPID_CHANGES}, received ${events.length} events`);
+
+  // Due to debouncing, we won't get all events, but we should get at least some
+  expect(events.length).toBeGreaterThan(0);
+
+  // Cleanup
+  await fs.promises.unlink(testFile);
+});
+
+tap.test('STRESS: many files created rapidly', async () => {
+  const FILE_COUNT = 20;
+  const files: string[] = [];
+
+  const addObservable = await testSmartwatch.getObservableFor('add');
+  const eventCollector = collectEvents(addObservable, 5000);
+
+  // Create many files rapidly
+  for (let i = 0; i < FILE_COUNT; i++) {
+    const file = path.join(TEST_DIR, `stress-many-${i}.txt`);
+    files.push(file);
+    await smartfile.memory.toFs(`content ${i}`, file);
+    await delay(20); // 20ms between creates
+  }
+
+  const events = await eventCollector;
+  console.log(`[test] Many files: created ${FILE_COUNT}, detected ${events.length} events`);
+
+  // Should detect most or all files
+  expect(events.length).toBeGreaterThanOrEqual(FILE_COUNT * 0.8); // Allow 20% tolerance
+
+  // Cleanup all files
+  for (const file of files) {
+    try {
+      await fs.promises.unlink(file);
+    } catch {
+      // Ignore if already deleted
+    }
+  }
+});
+
+tap.test('STRESS: interleaved add/change/delete operations', async () => {
+  const testFiles = [
+    path.join(TEST_DIR, 'stress-interleave-1.txt'),
+    path.join(TEST_DIR, 'stress-interleave-2.txt'),
+    path.join(TEST_DIR, 'stress-interleave-3.txt'),
+  ];
+
+  // Create initial files
+  for (const file of testFiles) {
+    await smartfile.memory.toFs('initial', file);
+  }
+  await delay(300);
+
+  const addObservable = await testSmartwatch.getObservableFor('add');
+  const changeObservable = await testSmartwatch.getObservableFor('change');
+  const unlinkObservable = await testSmartwatch.getObservableFor('unlink');
+
+  const addEvents = collectEvents(addObservable, 3000);
+  const changeEvents = collectEvents(changeObservable, 3000);
+  const unlinkEvents = collectEvents(unlinkObservable, 3000);
+
+  // Interleaved operations
+  await smartfile.memory.toFs('changed 1', testFiles[0]); // change
+  await delay(50);
+  await fs.promises.unlink(testFiles[1]); // delete
+  await delay(50);
+  await smartfile.memory.toFs('recreated 1', testFiles[1]); // add (recreate)
+  await delay(50);
+  await smartfile.memory.toFs('changed 2', testFiles[2]); // change
+  await delay(50);
+
+  const [adds, changes, unlinks] = await Promise.all([addEvents, changeEvents, unlinkEvents]);
+
+  console.log(`[test] Interleaved: adds=${adds.length}, changes=${changes.length}, unlinks=${unlinks.length}`);
+
+  // Should have detected some events of each type
+  expect(changes.length).toBeGreaterThan(0);
+
+  // Cleanup
+  for (const file of testFiles) {
+    try {
+      await fs.promises.unlink(file);
+    } catch {
+      // Ignore
+    }
+  }
+});
+
+tap.test('teardown: stop watcher', async () => {
+  await testSmartwatch.stop();
+  expect(testSmartwatch.status).toEqual('idle');
+});
+
+tap.test('cleanup: remove stress test files', async () => {
+  const files = await fs.promises.readdir(TEST_DIR);
+  for (const file of files) {
+    if (file.startsWith('stress-')) {
+      try {
+        await fs.promises.unlink(path.join(TEST_DIR, file));
+      } catch {
+        // Ignore
+      }
+    }
+  }
+});
+
+export default tap.start();

test/test.ts

@@ -1,50 +0,0 @@
-import { tap, expect } from '@git.zone/tstest/tapbundle';
-import * as smartwatch from '../ts/index.js';
-import * as smartfile from '@push.rocks/smartfile';
-import * as smartpromise from '@push.rocks/smartpromise';
-import * as smartrx from '@push.rocks/smartrx';
-
-import * as fs from 'fs';
-
-// the module to test
-if (process.env.CI) {
-  process.exit(0);
-}
-
-let testSmartwatch: smartwatch.Smartwatch;
-let testAddObservable: smartrx.rxjs.Observable<[string, fs.Stats]>;
-let testSubscription: smartrx.rxjs.Subscription;
-tap.test('should create a new instance', async () => {
-  testSmartwatch = new smartwatch.Smartwatch([]);
-  expect(testSmartwatch).toBeInstanceOf(smartwatch.Smartwatch);
-});
-
-tap.test('should add some files to watch and start', async () => {
-  testSmartwatch.add(['./test/**/*.txt']);
-  await testSmartwatch.start()
-  testSmartwatch.add(['./test/**/*.md']);
-});
-
-tap.test('should get an observable for a certain event', async () => {
-  await testSmartwatch.getObservableFor('add').then(async (observableArg) => {
-    testAddObservable = observableArg;
-  });
-});
-
-tap.test('should register an add operation', async () => {
-  let testDeferred = smartpromise.defer();
-  testSubscription = testAddObservable.subscribe(pathArg => {
-    const pathResult = pathArg[0];
-    console.log(pathResult);
-    testDeferred.resolve();
-  });
-  smartfile.memory.toFs('HI', './test/assets/hi.txt');
-  await testDeferred.promise;
-});
-
-tap.test('should stop the watch process', async (tools) => {
-  await tools.delayFor(10000);
-  testSmartwatch.stop();
-});
-
-export default tap.start();

ts/00_commitinfo_data.ts

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

ts/smartwatch.classes.smartwatch.ts

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

ts/utils/write-stabilizer.ts

@@ -1,97 +0,0 @@
-import * as fs from 'fs';
-
-interface IPendingWrite {
-  lastSize: number;
-  lastChange: number;
-  timeoutId: ReturnType<typeof setTimeout>;
-  resolve: (stats: fs.Stats) => void;
-  reject: (error: Error) => void;
-}
-
-/**
- * Implements awaitWriteFinish functionality by polling file size until stable.
- * This replaces chokidar's built-in write stabilization.
- */
-export class WriteStabilizer {
-  private pendingWrites = new Map<string, IPendingWrite>();
-
-  constructor(
-    private stabilityThreshold: number = 300,
-    private pollInterval: number = 100
-  ) {}
-
-  /**
-   * Wait for a file write to complete by polling until size is stable
-   */
-  async waitForWriteFinish(filePath: string): Promise<fs.Stats> {
-    // Cancel any existing pending check for this file
-    this.cancel(filePath);
-
-    return new Promise((resolve, reject) => {
-      const poll = async () => {
-        try {
-          const stats = await fs.promises.stat(filePath);
-          const pending = this.pendingWrites.get(filePath);
-
-          if (!pending) {
-            // Was cancelled
-            return;
-          }
-
-          const now = Date.now();
-
-          if (stats.size !== pending.lastSize) {
-            // Size changed - file is still being written, reset timer
-            pending.lastSize = stats.size;
-            pending.lastChange = now;
-            pending.timeoutId = setTimeout(poll, this.pollInterval);
-          } else if (now - pending.lastChange >= this.stabilityThreshold) {
-            // Size has been stable for the threshold duration
-            this.pendingWrites.delete(filePath);
-            resolve(stats);
-          } else {
-            // Size is the same but not yet past threshold
-            pending.timeoutId = setTimeout(poll, this.pollInterval);
-          }
-        } catch (error: any) {
-          this.pendingWrites.delete(filePath);
-          if (error.code === 'ENOENT') {
-            // File was deleted during polling
-            reject(new Error(`File was deleted: ${filePath}`));
-          } else {
-            reject(error);
-          }
-        }
-      };
-
-      this.pendingWrites.set(filePath, {
-        lastSize: -1,
-        lastChange: Date.now(),
-        timeoutId: setTimeout(poll, this.pollInterval),
-        resolve,
-        reject
-      });
-    });
-  }
-
-  /**
-   * Cancel any pending write stabilization for a file
-   */
-  cancel(filePath: string): void {
-    const pending = this.pendingWrites.get(filePath);
-    if (pending) {
-      clearTimeout(pending.timeoutId);
-      this.pendingWrites.delete(filePath);
-    }
-  }
-
-  /**
-   * Cancel all pending write stabilizations
-   */
-  cancelAll(): void {
-    for (const [filePath, pending] of this.pendingWrites) {
-      clearTimeout(pending.timeoutId);
-    }
-    this.pendingWrites.clear();
-  }
-}

ts/watchers/index.ts

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

ts/watchers/interfaces.ts

@@ -26,10 +26,8 @@ export interface IWatcherOptions {
   depth: number;
   /** Whether to follow symbolic links */
   followSymlinks: boolean;
-  /** Stability threshold for write detection (ms) */
+  /** Debounce time in ms - events for the same file within this window are coalesced */
-  stabilityThreshold: number;
+  debounceMs: number;
-  /** Poll interval for write detection (ms) */
-  pollInterval: number;
 }
 
 /**

ts/watchers/watcher.deno.ts

@@ -65,15 +65,27 @@ export class DenoWatcher implements IWatcher {
   private watcher: ReturnType<typeof Deno.watchFs> | null = null;
   private watchedFiles: Set<string> = new Set();
   private _isWatching = false;
-  private abortController: AbortController | null = null;
+
-  private recentEvents: Map<string, number> = new Map();
+  // Debounce: pending emits per file path
-  private throttleMs = 50;
+  private pendingEmits: Map<string, ReturnType<typeof setTimeout>> = new Map();
-  private pendingWrites: Map<string, ReturnType<typeof setTimeout>> = new Map();
 
   public readonly events$ = new smartrx.rxjs.Subject<IWatchEvent>();
 
   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;
   }
@@ -84,8 +96,6 @@ export class DenoWatcher implements IWatcher {
     }
 
     try {
-      this.abortController = new AbortController();
-
       // Start watching all base paths
       this.watcher = Deno.watchFs(this.options.basePaths, { recursive: true });
       this._isWatching = true;
@@ -109,11 +119,11 @@ export class DenoWatcher implements IWatcher {
   async stop(): Promise<void> {
     this._isWatching = false;
 
-    // Cancel all pending write stabilizations
+    // Cancel all pending debounced emits
-    for (const timeout of this.pendingWrites.values()) {
+    for (const timeout of this.pendingEmits.values()) {
       clearTimeout(timeout);
     }
-    this.pendingWrites.clear();
+    this.pendingEmits.clear();
 
     // Close the watcher
     if (this.watcher) {
@@ -122,7 +132,6 @@ export class DenoWatcher implements IWatcher {
     }
 
     this.watchedFiles.clear();
-    this.recentEvents.clear();
   }
 
   /**
@@ -140,7 +149,7 @@ export class DenoWatcher implements IWatcher {
         }
 
         for (const filePath of event.paths) {
-          await this.handleDenoEvent(event.kind, filePath);
+          this.handleDenoEvent(event.kind, filePath);
         }
       }
     } catch (error: any) {
@@ -151,46 +160,56 @@ export class DenoWatcher implements IWatcher {
   }
 
   /**
-   * Handle a Deno file system event
+   * Handle a Deno file system event - debounce and normalize
    */
-  private async handleDenoEvent(
+  private handleDenoEvent(
     kind: 'create' | 'modify' | 'remove' | 'access' | 'any' | 'other',
     filePath: string
-  ): Promise<void> {
+  ): void {
     // Ignore 'access' events (just reading the file)
     if (kind === 'access') {
       return;
     }
 
-    // Throttle duplicate events
+    // Skip temporary files created by editors (atomic saves)
-    if (!this.shouldEmit(filePath, kind)) {
+    if (this.isTemporaryFile(filePath)) {
       return;
     }
 
+    // Debounce: cancel any pending emit for this file
+    const existing = this.pendingEmits.get(filePath);
+    if (existing) {
+      clearTimeout(existing);
+    }
+
+    // Schedule debounced emit
+    const timeout = setTimeout(() => {
+      this.pendingEmits.delete(filePath);
+      this.emitFileEvent(filePath, kind);
+    }, this.options.debounceMs);
+
+    this.pendingEmits.set(filePath, timeout);
+  }
+
+  /**
+   * Emit the actual file event after debounce
+   */
+  private async emitFileEvent(
+    filePath: string,
+    kind: 'create' | 'modify' | 'remove' | 'access' | 'any' | 'other'
+  ): Promise<void> {
     try {
       if (kind === 'create') {
         const stats = await this.statSafe(filePath);
         if (stats) {
-          // Wait for write to stabilize
+          this.watchedFiles.add(filePath);
-          await this.waitForWriteFinish(filePath);
+          const eventType: TWatchEventType = stats.isDirectory() ? 'addDir' : 'add';
-          const finalStats = await this.statSafe(filePath);
+          this.events$.next({ type: eventType, path: filePath, stats });
-
-          if (finalStats) {
-            this.watchedFiles.add(filePath);
-            const eventType: TWatchEventType = finalStats.isDirectory() ? 'addDir' : 'add';
-            this.events$.next({ type: eventType, path: filePath, stats: finalStats });
-          }
         }
       } else if (kind === 'modify') {
         const stats = await this.statSafe(filePath);
         if (stats && !stats.isDirectory()) {
-          // Wait for write to stabilize
+          this.events$.next({ type: 'change', path: filePath, stats });
-          await this.waitForWriteFinish(filePath);
-          const finalStats = await this.statSafe(filePath);
-
-          if (finalStats) {
-            this.events$.next({ type: 'change', path: filePath, stats: finalStats });
-          }
         }
       } else if (kind === 'remove') {
         const wasDirectory = this.isKnownDirectory(filePath);
@@ -205,43 +224,6 @@ export class DenoWatcher implements IWatcher {
     }
   }
 
-  /**
-   * Wait for file write to complete (polling-based)
-   */
-  private async waitForWriteFinish(filePath: string): Promise<void> {
-    return new Promise((resolve) => {
-      let lastSize = -1;
-      let lastChange = Date.now();
-
-      const poll = async () => {
-        try {
-          const stats = await this.statSafe(filePath);
-          if (!stats) {
-            resolve();
-            return;
-          }
-
-          const now = Date.now();
-          if (stats.size !== lastSize) {
-            lastSize = stats.size;
-            lastChange = now;
-            this.pendingWrites.set(filePath, setTimeout(poll, this.options.pollInterval));
-          } else if (now - lastChange >= this.options.stabilityThreshold) {
-            this.pendingWrites.delete(filePath);
-            resolve();
-          } else {
-            this.pendingWrites.set(filePath, setTimeout(poll, this.options.pollInterval));
-          }
-        } catch {
-          this.pendingWrites.delete(filePath);
-          resolve();
-        }
-      };
-
-      this.pendingWrites.set(filePath, setTimeout(poll, this.options.pollInterval));
-    });
-  }
-
   /**
    * Scan directory and emit 'add' events for existing files
    */
@@ -253,6 +235,12 @@ export class DenoWatcher implements IWatcher {
     try {
       for await (const entry of Deno.readDir(dirPath)) {
         const fullPath = `${dirPath}/${entry.name}`;
+
+        // Skip temp files during initial scan too
+        if (this.isTemporaryFile(fullPath)) {
+          continue;
+        }
+
         const stats = await this.statSafe(fullPath);
 
         if (!stats) {
@@ -299,31 +287,4 @@ export class DenoWatcher 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;
-  }
 }