push.rocks/smartwatch
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix(watcher.node): Defer events during initial scan, track full event sequences, and harden watcher shutdown

Browse Source
This commit is contained in:
Jürgen Kunz
2025-12-11 02:39:38 +00:00
parent ea57de06dd
commit 6f6868f2ad
5 changed files with 207 additions and 97 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
changelog.md
View File

@@ -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

23
readme.hints.md
View File

@@ -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

16
test/test.inode.ts
View File

@@ -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);

2
ts/00_commitinfo_data.ts
View File

@@ -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.'
}

220
ts/watchers/watcher.node.ts
View File

@@ -12,7 +12,12 @@ export class NodeWatcher implements IWatcher {
private _isWatching = false;
// Debounce: pending emits per file path
private pendingEmits: Map<string, NodeJS.Timeout> = 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<string, {
timeout: NodeJS.Timeout;
events: Array<'rename' | 'change'>;
}> = new Map();
// Restart tracking
private restartDelays: Map<string, number> = 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<string> = 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<void> {
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);
}
// Schedule debounced emit
const timeout = setTimeout(() => {
// 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, eventType);
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);
this.pendingEmits.set(fullPath, {
timeout,
events: [eventType as 'rename' | 'change']
});
}
}
/**
* 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<void> {
try {
const stats = await this.statSafe(fullPath);
const wasWatched = this.watchedFiles.has(fullPath);
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;
// Log sequence for debugging complex scenarios
if (eventSequence.length > 1) {
console.log(`[smartwatch] Processing event sequence for ${fullPath}: [${eventSequence.join(', ')}]`);
}
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
// File EXISTS now
const currentInode = BigInt(stats.ino);
const inodeChanged = previousInode !== undefined && previousInode !== currentInode;
if (stats.isDirectory()) {
if (!this.watchedFiles.has(fullPath)) {
if (!wasWatched) {
this.watchedFiles.add(fullPath);
this.safeEmit({ type: 'addDir', path: fullPath, stats });
}
// Directories don't track inodes at file level
} else {
const wasWatched = this.watchedFiles.has(fullPath);
const currentInode = BigInt(stats.ino);
const previousInode = this.fileInodes.get(fullPath);
// Track file inode for delete+recreate detection
// Update tracking
this.fileInodes.set(fullPath, currentInode);
this.watchedFiles.add(fullPath);
// Check if file was recreated with different inode (delete+recreate scenario)
if (wasWatched && previousInode !== undefined && previousInode !== currentInode) {
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}`);
// Emit as 'change' since the file content likely changed
// 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 {
this.safeEmit({
type: wasWatched ? 'change' : 'add',
path: fullPath,
stats
});
}
}
} else {
// File doesn't exist - it was deleted
if (this.watchedFiles.has(fullPath)) {
// 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); // Clean up inode tracking
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
// 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) {