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

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

252
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);
// 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<void> {
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) {