Skip to content

Commit 1d32615

Browse files
committed
fix: do not emit spurious initial-scan change events for items created within FS_ACCURACY of startTime (#295)
DirectoryWatcher previously compared an entry's `safeTime` (`Math.min(now, mtime) + FS_ACCURACY`) against the watcher's `startTime`. Because `safeTime` is intentionally inflated by `FS_ACCURACY` to give callers an upper bound on possible modification time, every file or directory whose actual mtime/birthtime was up to `FS_ACCURACY` (initially 2000ms, typically 10ms after a single mtime is observed) before `startTime` was being flagged as changed during the initial scan. The `startTime` filter now compares against the raw mtime/birthtime instead, so only entries actually modified at or after `startTime` trigger a change event during initial scan. The change event payload still carries `safeTime` as before, and an additional optional `rawTimestamp` argument is forwarded so nested directory watchers can re-filter against the same raw timestamp. The "outdated on attach" path in `watch()` continues to use `safeTime` because its semantics are different: it represents "the last time the file was known to be in a stable state", which is the right value to compare against a newly attached watcher's startTime. https://claude.ai/code/session_01CfqWhrftEvFkN5GiG82P67
1 parent d9af8b1 commit 1d32615

4 files changed

Lines changed: 70 additions & 11 deletions

File tree

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
---
2+
"watchpack": patch
3+
---
4+
5+
fix: do not emit spurious initial-scan `change` events for files and
6+
directories created within `FS_ACCURACY` (up to two seconds) of
7+
`startTime` (fixes #295).
8+
9+
`DirectoryWatcher` previously compared an entry's `safeTime`
10+
(`Math.min(now, mtime) + FS_ACCURACY`) against the watcher's
11+
`startTime`. Because `safeTime` is intentionally inflated by
12+
`FS_ACCURACY` to account for filesystem timestamp granularity, every
13+
file or directory whose actual `mtime`/`birthtime` was up to
14+
`FS_ACCURACY` _before_ `startTime` was being flagged as changed during
15+
the initial scan.
16+
17+
The `startTime` filter now compares against the raw `mtime`/`birthtime`
18+
instead, so only entries actually modified at or after `startTime`
19+
trigger a change event. The `change` event payload (and the existing
20+
`safeTime` semantics for consumers) are unchanged.

‎lib/DirectoryWatcher.js‎

Lines changed: 16 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -135,7 +135,7 @@ function lstatWithRetry(target, watcher, callback, remaining = BUSY_RETRIES) {
135135
/**
136136
* @typedef {object} DirectoryWatcherEvents
137137
* @property {(type: EventType) => void} initial-missing initial missing event
138-
* @property {((file: string, mtime: number, type: EventType, initial: boolean) => void)} change change event
138+
* @property {((file: string, mtime: number, type: EventType, initial: boolean, rawTimestamp?: number) => void)} change change event
139139
* @property {(type: EventType) => void} remove remove event
140140
* @property {() => void} closed closed event
141141
*/
@@ -390,16 +390,16 @@ class DirectoryWatcher extends EventEmitter {
390390
}
391391

392392
this.forEachWatcher(target, (w) => {
393-
if (!initial || w.checkStartTime(safeTime, initial)) {
393+
if (!initial || w.checkStartTime(mtime, initial)) {
394394
w.emit("change", mtime, type);
395395
}
396396
});
397397
} else if (!initial) {
398398
this.forEachWatcher(target, (w) => w.emit("change", mtime, type));
399399
}
400400
this.forEachWatcher(this.path, (w) => {
401-
if (!initial || w.checkStartTime(safeTime, initial)) {
402-
w.emit("change", target, safeTime, type, initial);
401+
if (!initial || w.checkStartTime(mtime, initial)) {
402+
w.emit("change", target, safeTime, type, initial, mtime);
403403
}
404404
});
405405
}
@@ -432,13 +432,13 @@ class DirectoryWatcher extends EventEmitter {
432432
const safeTime = initial ? Math.min(now, birthtime) + FS_ACCURACY : now;
433433

434434
this.forEachWatcher(directoryPath, (w) => {
435-
if (!initial || w.checkStartTime(safeTime, false)) {
435+
if (!initial || w.checkStartTime(birthtime, false)) {
436436
w.emit("change", birthtime, type);
437437
}
438438
});
439439
this.forEachWatcher(this.path, (w) => {
440-
if (!initial || w.checkStartTime(safeTime, initial)) {
441-
w.emit("change", directoryPath, safeTime, type, initial);
440+
if (!initial || w.checkStartTime(birthtime, initial)) {
441+
w.emit("change", directoryPath, safeTime, type, initial, birthtime);
442442
}
443443
});
444444
}
@@ -450,10 +450,16 @@ class DirectoryWatcher extends EventEmitter {
450450
*/
451451
createNestedWatcher(directoryPath) {
452452
const watcher = this.watcherManager.watchDirectory(directoryPath, 1);
453-
watcher.on("change", (target, mtime, type, initial) => {
453+
watcher.on("change", (target, mtime, type, initial, rawTimestamp) => {
454454
this.forEachWatcher(this.path, (w) => {
455-
if (!initial || w.checkStartTime(mtime, initial)) {
456-
w.emit("change", target, mtime, type, initial);
455+
if (
456+
!initial ||
457+
w.checkStartTime(
458+
rawTimestamp !== undefined ? rawTimestamp : mtime,
459+
initial,
460+
)
461+
) {
462+
w.emit("change", target, mtime, type, initial, rawTimestamp);
457463
}
458464
});
459465
});

‎test/Watchpack.test.js‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1154,6 +1154,38 @@ describe("Watchpack", () => {
11541154
});
11551155
});
11561156

1157+
it("should not report changes in initial scan when start time is provided and items were created shortly before (#295)", (done) => {
1158+
const w = new WatchpackTest({
1159+
aggregateTimeout: 100,
1160+
});
1161+
w.on("aggregated", () => {
1162+
done(new Error("should not fire"));
1163+
});
1164+
testHelper.dir("dir");
1165+
testHelper.dir("dir/sub");
1166+
testHelper.file("dir/sub/nested");
1167+
testHelper.file("dir/file");
1168+
// Use a short tick (~100 ms) to mimic the real-world scenario where
1169+
// callers create files and then `await` something before calling
1170+
// `watch({ startTime: Date.now() })`. The previous behaviour added
1171+
// `FS_ACCURACY` (up to 2000 ms) to each entry's `safeTime` and
1172+
// compared the inflated value against `startTime`, which incorrectly
1173+
// flagged everything that was created within `FS_ACCURACY` before
1174+
// `startTime`.
1175+
testHelper.tick(() => {
1176+
w.watch({
1177+
directories: [path.join(fixtures, "dir")],
1178+
startTime: Date.now(),
1179+
});
1180+
testHelper.tick(2000, () => {
1181+
expect(true).toBe(true);
1182+
// no event fired
1183+
w.close();
1184+
done();
1185+
});
1186+
});
1187+
});
1188+
11571189
it("should not report changes to a folder watched as file when items are added", (done) => {
11581190
const w = new WatchpackTest({
11591191
aggregateTimeout: 100,

‎types/DirectoryWatcher.d.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -209,7 +209,7 @@ import { EventEmitter } from "events";
209209
/**
210210
* @typedef {object} DirectoryWatcherEvents
211211
* @property {(type: EventType) => void} initial-missing initial missing event
212-
* @property {((file: string, mtime: number, type: EventType, initial: boolean) => void)} change change event
212+
* @property {((file: string, mtime: number, type: EventType, initial: boolean, rawTimestamp?: number) => void)} change change event
213213
* @property {(type: EventType) => void} remove remove event
214214
* @property {() => void} closed closed event
215215
*/
@@ -293,6 +293,7 @@ type DirectoryWatcherEvents = {
293293
mtime: number,
294294
type: EventType,
295295
initial: boolean,
296+
rawTimestamp?: number,
296297
) => void;
297298
/**
298299
* remove event

0 commit comments

Comments
 (0)