diff --git a/changelog.md b/changelog.md index 42862ab..9e2e6c2 100644 --- a/changelog.md +++ b/changelog.md @@ -1,5 +1,14 @@ # Changelog +## 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. diff --git a/ts/00_commitinfo_data.ts b/ts/00_commitinfo_data.ts index 150003b..baf6412 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: '5.0.0', + version: '5.1.0', description: 'A cross-runtime file watcher with glob pattern support for Node.js, Deno, and Bun.' } diff --git a/ts/smartwatch.classes.smartwatch.ts b/ts/smartwatch.classes.smartwatch.ts index 8218738..0bfddd2 100644 --- a/ts/smartwatch.classes.smartwatch.ts +++ b/ts/smartwatch.classes.smartwatch.ts @@ -132,8 +132,9 @@ export class Smartwatch { basePaths: watchPaths, depth: 4, followSymlinks: false, - stabilityThreshold: 300, - pollInterval: 100 + stabilityThreshold: 100, + pollInterval: 100, + maxWaitTime: 1000 }); // Subscribe to watcher events and dispatch to appropriate subjects diff --git a/ts/utils/write-stabilizer.ts b/ts/utils/write-stabilizer.ts index a5fa3e3..2aef7cd 100644 --- a/ts/utils/write-stabilizer.ts +++ b/ts/utils/write-stabilizer.ts @@ -3,6 +3,7 @@ import * as fs from 'fs'; interface IPendingWrite { lastSize: number; lastChange: number; + startTime: number; timeoutId: ReturnType; resolve: (stats: fs.Stats) => void; reject: (error: Error) => void; @@ -16,8 +17,9 @@ export class WriteStabilizer { private pendingWrites = new Map(); constructor( - private stabilityThreshold: number = 300, - private pollInterval: number = 100 + private stabilityThreshold: number = 100, + private pollInterval: number = 100, + private maxWaitTime: number = 1000 ) {} /** @@ -28,6 +30,8 @@ export class WriteStabilizer { this.cancel(filePath); return new Promise((resolve, reject) => { + const startTime = Date.now(); + const poll = async () => { try { const stats = await fs.promises.stat(filePath); @@ -40,6 +44,13 @@ export class WriteStabilizer { const now = Date.now(); + // Check if we've exceeded max wait time - emit with current stats + if (now - pending.startTime >= this.maxWaitTime) { + this.pendingWrites.delete(filePath); + resolve(stats); + return; + } + if (stats.size !== pending.lastSize) { // Size changed - file is still being written, reset timer pending.lastSize = stats.size; @@ -66,7 +77,8 @@ export class WriteStabilizer { this.pendingWrites.set(filePath, { lastSize: -1, - lastChange: Date.now(), + lastChange: startTime, + startTime: startTime, timeoutId: setTimeout(poll, this.pollInterval), resolve, reject diff --git a/ts/watchers/index.ts b/ts/watchers/index.ts index b5a3f33..7e737cd 100644 --- a/ts/watchers/index.ts +++ b/ts/watchers/index.ts @@ -28,6 +28,7 @@ export const defaultWatcherOptions: IWatcherOptions = { basePaths: [], depth: 4, followSymlinks: false, - stabilityThreshold: 300, - pollInterval: 100 + stabilityThreshold: 100, + pollInterval: 100, + maxWaitTime: 1000 }; diff --git a/ts/watchers/interfaces.ts b/ts/watchers/interfaces.ts index 875b222..6c29d9d 100644 --- a/ts/watchers/interfaces.ts +++ b/ts/watchers/interfaces.ts @@ -30,6 +30,8 @@ export interface IWatcherOptions { stabilityThreshold: number; /** Poll interval for write detection (ms) */ pollInterval: number; + /** Maximum time to wait for write stabilization (ms) */ + maxWaitTime: number; } /** diff --git a/ts/watchers/watcher.deno.ts b/ts/watchers/watcher.deno.ts index e6c489f..363044d 100644 --- a/ts/watchers/watcher.deno.ts +++ b/ts/watchers/watcher.deno.ts @@ -74,6 +74,19 @@ export class DenoWatcher implements IWatcher { 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; } @@ -162,6 +175,11 @@ export class DenoWatcher implements IWatcher { return; } + // Skip temporary files created by editors (atomic saves) + if (this.isTemporaryFile(filePath)) { + return; + } + // Throttle duplicate events if (!this.shouldEmit(filePath, kind)) { return; @@ -169,19 +187,15 @@ export class DenoWatcher implements IWatcher { try { if (kind === 'create') { + // Create events (atomic saves) don't need stabilization - file is already complete const stats = await this.statSafe(filePath); if (stats) { - // Wait for write to stabilize - await this.waitForWriteFinish(filePath); - const finalStats = await this.statSafe(filePath); - - if (finalStats) { - this.watchedFiles.add(filePath); - const eventType: TWatchEventType = finalStats.isDirectory() ? 'addDir' : 'add'; - this.events$.next({ type: eventType, path: filePath, stats: finalStats }); - } + this.watchedFiles.add(filePath); + const eventType: TWatchEventType = stats.isDirectory() ? 'addDir' : 'add'; + this.events$.next({ type: eventType, path: filePath, stats }); } } else if (kind === 'modify') { + // Modify events are in-place writes - use stabilization const stats = await this.statSafe(filePath); if (stats && !stats.isDirectory()) { // Wait for write to stabilize @@ -212,6 +226,7 @@ export class DenoWatcher implements IWatcher { return new Promise((resolve) => { let lastSize = -1; let lastChange = Date.now(); + const startTime = Date.now(); const poll = async () => { try { @@ -222,6 +237,14 @@ export class DenoWatcher implements IWatcher { } const now = Date.now(); + + // Check if we've exceeded max wait time - resolve immediately + if (now - startTime >= this.options.maxWaitTime) { + this.pendingWrites.delete(filePath); + resolve(); + return; + } + if (stats.size !== lastSize) { lastSize = stats.size; lastChange = now; diff --git a/ts/watchers/watcher.node.ts b/ts/watchers/watcher.node.ts index 376a7ee..8076e51 100644 --- a/ts/watchers/watcher.node.ts +++ b/ts/watchers/watcher.node.ts @@ -20,10 +20,24 @@ export class NodeWatcher implements IWatcher { constructor(private options: IWatcherOptions) { this.writeStabilizer = new WriteStabilizer( options.stabilityThreshold, - options.pollInterval + options.pollInterval, + options.maxWaitTime ); } + /** + * Check if a file is a temporary file created by editors + */ + private isTemporaryFile(filePath: string): boolean { + const basename = path.basename(filePath); + // 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; } @@ -114,6 +128,11 @@ export class NodeWatcher implements IWatcher { ): Promise { const fullPath = path.join(basePath, filename); + // Skip temporary files created by editors (atomic saves) + if (this.isTemporaryFile(fullPath)) { + return; + } + // Throttle duplicate events if (!this.shouldEmit(fullPath, eventType)) { return; @@ -132,23 +151,14 @@ export class NodeWatcher implements IWatcher { this.events$.next({ type: 'addDir', path: fullPath, stats }); } } else { - // Wait for write to stabilize before emitting - try { - const stableStats = await this.writeStabilizer.waitForWriteFinish(fullPath); - const wasWatched = this.watchedFiles.has(fullPath); - this.watchedFiles.add(fullPath); - this.events$.next({ - type: wasWatched ? 'change' : 'add', - path: fullPath, - stats: stableStats - }); - } catch { - // File was deleted during stabilization - if (this.watchedFiles.has(fullPath)) { - this.watchedFiles.delete(fullPath); - this.events$.next({ type: 'unlink', path: fullPath }); - } - } + // Rename events (atomic saves) don't need stabilization - file is already complete + const wasWatched = this.watchedFiles.has(fullPath); + this.watchedFiles.add(fullPath); + this.events$.next({ + type: wasWatched ? 'change' : 'add', + path: fullPath, + stats + }); } } else { // File doesn't exist - it was deleted @@ -162,7 +172,7 @@ export class NodeWatcher implements IWatcher { } } } else if (eventType === 'change') { - // File was modified + // File was modified in-place - use stabilization for streaming writes if (stats && !stats.isDirectory()) { try { const stableStats = await this.writeStabilizer.waitForWriteFinish(fullPath);