diff --git a/changelog.md b/changelog.md index c5f5a47..be4f786 100644 --- a/changelog.md +++ b/changelog.md @@ -1,5 +1,16 @@ # Changelog +## 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 diff --git a/readme.hints.md b/readme.hints.md index 2de2fbf..45908e9 100644 --- a/readme.hints.md +++ b/readme.hints.md @@ -107,8 +107,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 +137,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] fs.watch watches inode, not path - restarting watcher +[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 diff --git a/test/test.inode.ts b/test/test.inode.ts index 7fb6943..c329d9b 100644 --- a/test/test.inode.ts +++ b/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'); - const eventPromise = waitForEvent(changeObservable, 3000); + // 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); @@ -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 - const [filePath] = await eventPromise; - expect(filePath).toInclude('inode-test.txt'); + // 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); diff --git a/ts/00_commitinfo_data.ts b/ts/00_commitinfo_data.ts index 46f05e3..dd88051 100644 --- a/ts/00_commitinfo_data.ts +++ b/ts/00_commitinfo_data.ts @@ -3,6 +3,6 @@ */ export const commitinfo = { name: '@push.rocks/smartwatch', - version: '6.2.1', + version: '6.2.2', description: 'A cross-runtime file watcher with glob pattern support for Node.js, Deno, and Bun.' } diff --git a/ts/watchers/watcher.node.ts b/ts/watchers/watcher.node.ts index 8ee4e56..fe92e52 100644 --- a/ts/watchers/watcher.node.ts +++ b/ts/watchers/watcher.node.ts @@ -12,7 +12,12 @@ export class NodeWatcher implements IWatcher { private _isWatching = false; // Debounce: pending emits per file path - private pendingEmits: Map = new Map(); + // Fix 2: Track event sequence instead of just last event type + // This prevents losing intermediate events (add→change→delete should not lose add) + private pendingEmits: Map; + }> = new Map(); // Restart tracking private restartDelays: Map = new Map(); @@ -34,6 +39,11 @@ export class NodeWatcher implements IWatcher { // Prevent concurrent restarts for the same path (health check + error can race) private restartingPaths: Set = new Set(); + // Initial scan state - events are deferred until scan completes to avoid race conditions + // Without this, events can arrive before watchedFiles is populated, causing inconsistent state + private initialScanComplete: boolean = false; + private deferredEvents: Array<{basePath: string; filename: string; eventType: string}> = []; + // Configuration constants private static readonly MAX_RETRIES = 3; private static readonly INITIAL_RESTART_DELAY = 1000; @@ -229,7 +239,12 @@ export class NodeWatcher implements IWatcher { console.log(`[smartwatch] Starting watcher for ${this.options.basePaths.length} base path(s)...`); try { + // Reset initial scan state + this.initialScanComplete = false; + this.deferredEvents = []; + // Start watching each base path + // NOTE: Events may arrive immediately but will be deferred until scan completes for (const basePath of this.options.basePaths) { await this.watchPath(basePath, 0); } @@ -240,10 +255,21 @@ export class NodeWatcher implements IWatcher { this.startHealthCheck(); // Perform initial scan to emit 'add' events for existing files + // This populates watchedFiles and fileInodes BEFORE we process events for (const basePath of this.options.basePaths) { await this.scanDirectory(basePath, 0); } + // Mark scan complete and process any events that arrived during scan + this.initialScanComplete = true; + if (this.deferredEvents.length > 0) { + console.log(`[smartwatch] Processing ${this.deferredEvents.length} deferred events from initial scan window`); + for (const event of this.deferredEvents) { + this.handleFsEvent(event.basePath, event.filename, event.eventType); + } + this.deferredEvents = []; + } + // Emit ready event this.safeEmit({ type: 'ready', path: '' }); console.log(`[smartwatch] Watcher started with ${this.watchers.size} active watcher(s)`); @@ -256,6 +282,15 @@ export class NodeWatcher implements IWatcher { async stop(): Promise { console.log('[smartwatch] Stopping watcher...'); + + // Fix 4: Cancel pending debounced emits FIRST (before flag changes) + // This prevents handleFsEvent from creating new pendingEmits during shutdown + for (const pending of this.pendingEmits.values()) { + clearTimeout(pending.timeout); + } + this.pendingEmits.clear(); + + // NOW set the flag - handleFsEvent will return early after this this._isWatching = false; // Stop health check monitoring @@ -268,12 +303,6 @@ export class NodeWatcher implements IWatcher { } this.restartAbortControllers.clear(); - // Cancel all pending debounced emits - for (const timeout of this.pendingEmits.values()) { - clearTimeout(timeout); - } - this.pendingEmits.clear(); - // Close all watchers for (const [watchPath, watcher] of this.watchers) { console.log(`[smartwatch] Closing watcher for: ${watchPath}`); @@ -289,6 +318,10 @@ export class NodeWatcher implements IWatcher { this.fileInodes.clear(); this.restartingPaths.clear(); + // Fix 5: Reset initial scan state + this.initialScanComplete = false; + this.deferredEvents = []; + console.log('[smartwatch] Watcher stopped'); } @@ -363,6 +396,18 @@ export class NodeWatcher implements IWatcher { filename: string, eventType: 'rename' | 'change' | string ): void { + // Fix 3: Guard against post-stop events (events queued before watcher closed) + if (!this._isWatching) { + return; + } + + // Fix 1: Defer events until initial scan completes + // This prevents race conditions where events arrive before watchedFiles is populated + if (!this.initialScanComplete) { + this.deferredEvents.push({ basePath, filename, eventType }); + return; + } + const fullPath = path.join(basePath, filename); // Skip temporary files - but ONLY pure temp files, not the target of atomic writes @@ -376,25 +421,48 @@ export class NodeWatcher implements IWatcher { return; } - // Debounce: cancel any pending emit for this file + // Fix 2: Track event sequence in debounce instead of collapsing to last event + // This ensures we don't lose intermediate events (e.g., add→change→delete) const existing = this.pendingEmits.get(fullPath); if (existing) { - clearTimeout(existing); + // Cancel existing timeout but KEEP the event sequence + clearTimeout(existing.timeout); + // Add this event to the sequence + existing.events.push(eventType as 'rename' | 'change'); + // Reschedule the emit with the accumulated events + existing.timeout = setTimeout(() => { + const pending = this.pendingEmits.get(fullPath); + if (pending) { + this.pendingEmits.delete(fullPath); + this.emitFileEvent(fullPath, pending.events); + } + }, this.options.debounceMs); + } else { + // First event for this file - create new sequence + const timeout = setTimeout(() => { + const pending = this.pendingEmits.get(fullPath); + if (pending) { + this.pendingEmits.delete(fullPath); + this.emitFileEvent(fullPath, pending.events); + } + }, this.options.debounceMs); + + this.pendingEmits.set(fullPath, { + timeout, + events: [eventType as 'rename' | 'change'] + }); } - - // Schedule debounced emit - const timeout = setTimeout(() => { - this.pendingEmits.delete(fullPath); - this.emitFileEvent(fullPath, eventType); - }, this.options.debounceMs); - - this.pendingEmits.set(fullPath, timeout); } /** * Emit the actual file event after debounce * - * Handles file inode tracking to detect delete+recreate scenarios: + * Fix 2: Now receives event sequence instead of single event type + * This allows intelligent processing of rapid event sequences: + * - add→change→delete: File was created and deleted rapidly + * - rename→rename: File was deleted and recreated (or vice versa) + * + * Also handles file inode tracking to detect delete+recreate scenarios: * - fs.watch watches the inode, not the path * - When editors delete+recreate files, the inode changes * - Without inode tracking, events for the new file would be missed @@ -402,92 +470,98 @@ export class NodeWatcher implements IWatcher { */ private async emitFileEvent( fullPath: string, - eventType: 'rename' | 'change' | string + eventSequence: Array<'rename' | 'change'> ): Promise { try { const stats = await this.statSafe(fullPath); + const wasWatched = this.watchedFiles.has(fullPath); + const previousInode = this.fileInodes.get(fullPath); - if (eventType === 'rename') { - // 'rename' can mean add or unlink - check if file exists - if (stats) { - // File exists - it's either a new file or was renamed to this location - if (stats.isDirectory()) { - if (!this.watchedFiles.has(fullPath)) { - this.watchedFiles.add(fullPath); - this.safeEmit({ type: 'addDir', path: fullPath, stats }); - } - } else { - const wasWatched = this.watchedFiles.has(fullPath); - const currentInode = BigInt(stats.ino); - const previousInode = this.fileInodes.get(fullPath); + // Analyze event sequence to understand what happened + const hasRename = eventSequence.includes('rename'); + const hasChange = eventSequence.includes('change'); + const renameCount = eventSequence.filter(e => e === 'rename').length; - // Track file inode for delete+recreate detection - this.fileInodes.set(fullPath, currentInode); + // Log sequence for debugging complex scenarios + if (eventSequence.length > 1) { + console.log(`[smartwatch] Processing event sequence for ${fullPath}: [${eventSequence.join(', ')}]`); + } + + if (stats) { + // File EXISTS now + const currentInode = BigInt(stats.ino); + const inodeChanged = previousInode !== undefined && previousInode !== currentInode; + + if (stats.isDirectory()) { + if (!wasWatched) { this.watchedFiles.add(fullPath); - - // Check if file was recreated with different inode (delete+recreate scenario) - if (wasWatched && previousInode !== undefined && previousInode !== currentInode) { - console.log(`[smartwatch] File inode changed (delete+recreate): ${fullPath}`); - console.log(`[smartwatch] Previous inode: ${previousInode}, current: ${currentInode}`); - // Emit as 'change' since the file content likely changed - this.safeEmit({ type: 'change', path: fullPath, stats }); - } else { - this.safeEmit({ - type: wasWatched ? 'change' : 'add', - path: fullPath, - stats - }); - } + this.safeEmit({ type: 'addDir', path: fullPath, stats }); } + // Directories don't track inodes at file level } else { - // File doesn't exist - it was deleted - if (this.watchedFiles.has(fullPath)) { - const wasDir = this.isKnownDirectory(fullPath); - this.watchedFiles.delete(fullPath); - this.fileInodes.delete(fullPath); // Clean up inode tracking + // Update tracking + this.fileInodes.set(fullPath, currentInode); + this.watchedFiles.add(fullPath); + + if (!wasWatched) { + // File wasn't tracked before - this is an add + // Even if there were multiple events, the end result is a new file + this.safeEmit({ type: 'add', path: fullPath, stats }); + } else if (inodeChanged) { + // File was recreated with different inode (delete+recreate) + console.log(`[smartwatch] File inode changed (delete+recreate): ${fullPath}`); + console.log(`[smartwatch] Previous inode: ${previousInode}, current: ${currentInode}`); + // Multiple rename events with inode change = delete+recreate pattern + // Emit unlink for the old file, then add for the new one + if (renameCount >= 2) { + this.safeEmit({ type: 'unlink', path: fullPath }); + this.safeEmit({ type: 'add', path: fullPath, stats }); + } else { + // Single rename with inode change = atomic save (emit as change) + this.safeEmit({ type: 'change', path: fullPath, stats }); + } + } else if (hasChange || hasRename) { + // File exists, was tracked, inode same - content changed + this.safeEmit({ type: 'change', path: fullPath, stats }); + } + } + } else { + // File does NOT exist now - it was deleted + const wasDir = this.isKnownDirectory(fullPath); + + if (wasWatched) { + // File was tracked and is now gone + this.watchedFiles.delete(fullPath); + this.fileInodes.delete(fullPath); + + // If there were multiple events, file may have been created then deleted + if (renameCount >= 2 && !wasDir) { + // add→delete sequence - emit both events + console.log(`[smartwatch] File created and deleted rapidly: ${fullPath}`); + this.safeEmit({ type: 'add', path: fullPath }); + this.safeEmit({ type: 'unlink', path: fullPath }); + } else { this.safeEmit({ type: wasDir ? 'unlinkDir' : 'unlink', path: fullPath }); - } else { - // Fix #4: File wasn't tracked but was deleted - still emit event - // This handles files created after initial scan that we may have missed + } + } else { + // File wasn't tracked - but events occurred for it + this.fileInodes.delete(fullPath); + + if (renameCount >= 2) { + // Multiple rename events for untracked file that doesn't exist + // Likely: created → deleted rapidly + console.log(`[smartwatch] Untracked file created and deleted: ${fullPath}`); + this.safeEmit({ type: 'add', path: fullPath }); + this.safeEmit({ type: 'unlink', path: fullPath }); + } else if (hasRename) { + // Single event for file that doesn't exist and wasn't tracked console.log(`[smartwatch] Untracked file deleted: ${fullPath}`); - this.fileInodes.delete(fullPath); this.safeEmit({ type: 'unlink', path: fullPath }); } - } - } else if (eventType === 'change') { - // File was modified - if (stats && !stats.isDirectory()) { - const wasWatched = this.watchedFiles.has(fullPath); - const currentInode = BigInt(stats.ino); - const previousInode = this.fileInodes.get(fullPath); - - // Track file inode - this.fileInodes.set(fullPath, currentInode); - - if (!wasWatched) { - // This is actually an 'add' - file wasn't being watched before - this.watchedFiles.add(fullPath); - this.safeEmit({ type: 'add', path: fullPath, stats }); - } else if (previousInode !== undefined && previousInode !== currentInode) { - // Inode changed during 'change' event - file was replaced - console.log(`[smartwatch] File replaced (inode change on modify): ${fullPath}`); - this.safeEmit({ type: 'change', path: fullPath, stats }); - } else { - this.safeEmit({ type: 'change', path: fullPath, stats }); - } - } else if (!stats && this.watchedFiles.has(fullPath)) { - // File was deleted - this.watchedFiles.delete(fullPath); - this.fileInodes.delete(fullPath); - this.safeEmit({ type: 'unlink', path: fullPath }); - } else if (!stats && !this.watchedFiles.has(fullPath)) { - // Fix #4: Untracked file deleted during 'change' event - console.log(`[smartwatch] Untracked file deleted (change event): ${fullPath}`); - this.fileInodes.delete(fullPath); - this.safeEmit({ type: 'unlink', path: fullPath }); + // If only 'change' events for non-existent untracked file, ignore } } } catch (error: any) {