feat: watch-suspend (#2430)

Author: bvanjoi

.changeset/small-pets-eat.md

@@ -0,0 +1,5 @@
+---
+"@rspack/core": patch
+---
+
+Support `suspend` and `resume` in Watching

.gitignore

@@ -163,6 +163,7 @@ dist
 
 !packages/rspack/tests/configCases/target
 packages/rspack/tests/js
+packages/rspack/tests/fixtures/temp-*
 packages/rspack-dev-server/.test-temp
 
 # Ignore local integrate debug file

packages/rspack/jest.config.js

@@ -6,7 +6,8 @@ module.exports = {
 		"<rootDir>/tests/*.basictest.ts",
 		"<rootDir>/tests/*.longtest.ts",
 		"<rootDir>/tests/*.unittest.ts",
-		"<rootDir>/tests/copyPlugin/*.test.js"
+		"<rootDir>/tests/copyPlugin/*.test.js",
+		"<rootDir>/tests/WatchSuspend.test.js"
 	],
 	testTimeout: 120000,
 	cache: false,

packages/rspack/src/compiler.ts

@@ -456,14 +456,10 @@ class Compiler {
 
 	watch(
 		watchOptions: WatchOptions,
-		handler: (error: Error, stats: Stats) => void
+		handler: (error: Error, stats?: Stats) => Watching
 	): Watching {
 		if (this.running) {
-			return handler(
-				new ConcurrentCompilationError(),
-				// @ts-expect-error
-				null
-			) as unknown as Watching;
+			return handler(new ConcurrentCompilationError());
 		}
 		this.running = true;
 		this.watchMode = true;

packages/rspack/src/multiWatching.ts

@@ -70,6 +70,18 @@ class MultiWatching {
 			}
 		);
 	}
+
+	suspend() {
+		for (const watching of this.watchings) {
+			watching.suspend();
+		}
+	}
+
+	resume() {
+		for (const watching of this.watchings) {
+			watching.resume();
+		}
+	}
 }
 
 export default MultiWatching;

packages/rspack/src/util/fs.ts

@@ -7,7 +7,7 @@ export interface Watcher {
 	getAggregatedRemovals?(): Set<string>; // get current aggregated removals that have not yet send to callback
 	getFileTimeInfoEntries?(): Map<string, FileSystemInfoEntry | "ignore">; // get info about files
 	getContextTimeInfoEntries?(): Map<string, FileSystemInfoEntry | "ignore">; // get info about directories
-	getInfo?(): WatcherInfo; // get info about timestamps and changes
+	getInfo(): WatcherInfo; // get info about timestamps and changes
 }
 
 export interface WatcherInfo {

packages/rspack/src/watching.ts

@@ -8,7 +8,7 @@
  * https://github.com/webpack/webpack/blob/main/LICENSE
  */
 import { Callback } from "tapable";
-import type { Compilation, Compiler } from ".";
+import type { Compiler } from ".";
 import { Stats } from ".";
 import { WatchOptions } from "./config";
 import { FileSystemInfoEntry, Watcher } from "./util/fs";
@@ -35,6 +35,7 @@ class Watching {
 	#closed: boolean;
 	#collectedChangedFiles?: Set<string>;
 	#collectedRemovedFiles?: Set<string>;
+	suspended: boolean;
 
 	constructor(
 		compiler: Compiler,
@@ -54,6 +55,7 @@ class Watching {
 		this.#closed = false;
 		this.watchOptions = watchOptions;
 		this.handler = handler;
+		this.suspended = false;
 
 		process.nextTick(() => {
 			if (this.#initial) this.#invalidate();
@@ -195,7 +197,7 @@ class Watching {
 		// @ts-expect-error
 		this.#mergeWithCollected(changedFiles, removedFiles);
 		// @ts-expect-error
-		if (this.isBlocked() && (this.blocked = true)) {
+		if (this.suspended || (this.isBlocked() && (this.blocked = true))) {
 			return;
 		}
 
@@ -218,6 +220,14 @@ class Watching {
 		} else if (!this.lastWatcherStartTime) {
 			this.lastWatcherStartTime = Date.now();
 		}
+
+		if (changedFiles && removedFiles) {
+			this.#mergeWithCollected(changedFiles, removedFiles);
+		} else if (this.pausedWatcher) {
+			const { changes, removals } = this.pausedWatcher.getInfo();
+			this.#mergeWithCollected(changes, removals);
+		}
+
 		const modifiedFiles = (this.compiler.modifiedFiles =
 			this.#collectedChangedFiles);
 		const deleteFiles = (this.compiler.removedFiles =
@@ -269,6 +279,7 @@ class Watching {
 		if (error) {
 			return handleError(error);
 		}
+
 		const cbs = this.callbacks;
 		this.callbacks = [];
 
@@ -316,6 +327,17 @@ class Watching {
 			}
 		}
 	}
+
+	suspend() {
+		this.suspended = true;
+	}
+
+	resume() {
+		if (this.suspended) {
+			this.suspended = false;
+			this.#invalidate();
+		}
+	}
 }
 
 export default Watching;

packages/rspack/tests/WatchSuspend.test.js

@@ -0,0 +1,181 @@
+// Copy from https://github.com/webpack/webpack/blob/main/test/WatchSuspend.test.js
+"use strict";
+
+const path = require("path");
+const fs = require("fs");
+
+describe("WatchSuspend", () => {
+	if (process.env.NO_WATCH_TESTS) {
+		it.skip("long running tests excluded", () => {});
+		return;
+	}
+
+	jest.setTimeout(5000);
+
+	describe("suspend and resume watcher", () => {
+		const fixturePath = path.join(
+			__dirname,
+			"fixtures",
+			"temp-watch-" + Date.now()
+		);
+		const filePath = path.join(fixturePath, "file.js");
+		const file2Path = path.join(fixturePath, "file2.js");
+		const file3Path = path.join(fixturePath, "file3.js");
+		const outputPath = path.join(__dirname, "js/WatchSuspend");
+		const outputFile = path.join(outputPath, "bundle.js");
+		let compiler = null;
+		let watching = null;
+		let onChange = null;
+
+		beforeAll(() => {
+			try {
+				fs.mkdirSync(fixturePath);
+			} catch (e) {
+				// skip
+			}
+			try {
+				fs.writeFileSync(filePath, "'foo'", "utf-8");
+				fs.writeFileSync(file2Path, "'file2'", "utf-8");
+				fs.writeFileSync(file3Path, "'file3'", "utf-8");
+			} catch (e) {
+				// skip
+			}
+			const { rspack: webpack } = require("../");
+			compiler = webpack({
+				mode: "development",
+				entry: filePath,
+				output: {
+					path: outputPath,
+					filename: "bundle.js"
+				}
+			});
+			watching = compiler.watch({ aggregateTimeout: 50, poll: 1000 }, () => {});
+
+			compiler.hooks.done.tap("WatchSuspendTest", () => {
+				if (onChange) onChange();
+			});
+		});
+
+		afterAll(() => {
+			watching.close();
+			compiler = null;
+			try {
+				fs.unlinkSync(filePath);
+			} catch (e) {
+				// skip
+			}
+			try {
+				fs.rmdirSync(fixturePath);
+			} catch (e) {
+				// skip
+			}
+		});
+
+		it("should compile successfully", done => {
+			onChange = () => {
+				expect(fs.readFileSync(outputFile, "utf-8")).toContain("'foo'");
+				onChange = null;
+				done();
+			};
+		});
+
+		it("should suspend compilation", done => {
+			onChange = jest.fn();
+			watching.suspend();
+			fs.writeFileSync(filePath, "'bar'", "utf-8");
+			setTimeout(() => {
+				expect(onChange.mock.calls.length).toBe(0);
+				onChange = null;
+				done();
+			}, 1000);
+		});
+
+		it("should resume compilation", done => {
+			onChange = () => {
+				expect(fs.readFileSync(outputFile, "utf-8")).toContain("'bar'");
+				onChange = null;
+				done();
+			};
+			watching.resume();
+		});
+
+		for (const changeBefore of [true])
+			for (const delay of [200]) {
+				// eslint-disable-next-line no-loop-func
+				it(`should not ignore changes during resumed compilation (changeBefore: ${changeBefore}, delay: ${delay}ms)`, async () => {
+					// aggregateTimeout must be long enough for this test
+					//  So set-up new watcher and wait when initial compilation is done
+					await new Promise(resolve => {
+						watching.close(() => {
+							watching = compiler.watch(
+								{ aggregateTimeout: 1000, poll: 1000 },
+								() => {
+									resolve();
+								}
+							);
+						});
+					});
+					return new Promise(resolve => {
+						if (changeBefore) fs.writeFileSync(filePath, "'bar'", "utf-8");
+						setTimeout(() => {
+							watching.suspend();
+							fs.writeFileSync(filePath, "'baz'", "utf-8");
+
+							onChange = "throw";
+							setTimeout(() => {
+								onChange = () => {
+									expect(fs.readFileSync(outputFile, "utf-8")).toContain(
+										"'baz'"
+									);
+									expect(
+										compiler.modifiedFiles &&
+											Array.from(compiler.modifiedFiles).sort()
+									).toEqual([filePath]);
+									expect(
+										compiler.removedFiles && Array.from(compiler.removedFiles)
+									).toEqual([]);
+									onChange = null;
+									resolve();
+								};
+								watching.resume();
+							}, delay);
+						}, 200);
+					});
+				});
+			}
+
+		it("should not drop changes when suspended", done => {
+			const aggregateTimeout = 50;
+			// Trigger initial compilation with file2.js (assuming correct)
+			fs.writeFileSync(
+				filePath,
+				'require("./file2.js"); require("./file3.js")',
+				"utf-8"
+			);
+
+			onChange = () => {
+				// Initial compilation is done, start the test
+				watching.suspend();
+
+				// Trigger the first change (works as expected):
+				fs.writeFileSync(file2Path, "'foo'", "utf-8");
+
+				// Trigger the second change _after_ aggregation timeout of the first
+				setTimeout(() => {
+					fs.writeFileSync(file3Path, "'bar'", "utf-8");
+
+					// Wait when the file3 edit is settled and re-compile
+					setTimeout(() => {
+						watching.resume();
+
+						onChange = () => {
+							onChange = null;
+							expect(fs.readFileSync(outputFile, "utf-8")).toContain("'bar'");
+							done();
+						};
+					}, 200);
+				}, aggregateTimeout + 50);
+			};
+		});
+	});
+});