feat(client): add disconnect() to close the SSE connection

README.md

@@ -420,6 +420,10 @@ hotClient.useCustomOverlay({
 // Connect manually when `autoConnect=false`. Accepts the same option keys as
 // the query-string API above.
 hotClient.setOptionsAndConnect({ path: "/__hmr" });
+
+// Close the SSE connection and stop reconnecting (e.g. before tearing the
+// page down). A later `setOptionsAndConnect` call opens a fresh connection.
+hotClient.disconnect();
 ```
 
 ## API

client-src/globals.d.ts

@@ -20,6 +20,7 @@ interface ClientReporter {
 
 interface EventSourceWrapper {
   addMessageListener(fn: (event: { data: string }) => void): void;
+  close(): void;
 }
 
 interface Window {

client-src/index.js

@@ -78,7 +78,7 @@ function setOverrides(overrides) {
  */
 
 /**
- * @returns {{ addMessageListener: (fn: MessageListener) => void }} event source wrapper
+ * @returns {{ addMessageListener: (fn: MessageListener) => void, close: () => void }} event source wrapper
  */
 function createEventSourceWrapper() {
   /** @type {EventSource} */
@@ -104,9 +104,17 @@ function createEventSourceWrapper() {
     }
   };
 
-  const handleDisconnect = () => {
+  /**
+   * Close the connection and stop the activity timer without scheduling a
+   * reconnection.
+   */
+  const close = () => {
     clearInterval(timer);
     source.close();
+  };
+
+  const handleDisconnect = () => {
+    close();
     setTimeout(init, /** @type {number} */ (options.timeout));
   };
 
@@ -134,6 +142,7 @@ function createEventSourceWrapper() {
     addMessageListener(fn) {
       listeners.push(fn);
     },
+    close,
   };
 }
 
@@ -179,6 +188,20 @@ export function setOptionsAndConnect(overrides) {
   connect();
 }
 
+/**
+ * Close the SSE connection for the current path and stop reconnecting. A
+ * later `setOptionsAndConnect` call opens a fresh connection.
+ */
+export function disconnect() {
+  const path = /** @type {string} */ (options.path);
+  const wrappers = window[WRAPPER_KEY];
+
+  if (wrappers && wrappers[path]) {
+    wrappers[path].close();
+    delete wrappers[path];
+  }
+}
+
 // eslint-disable-next-line jsdoc/reject-any-type
 /** @typedef {any} EXPECTED_ANY */
 

test/client.test.js

@@ -597,6 +597,32 @@ describe("client", () => {
       jest.advanceTimersByTime(20 * 1000);
       expect(EventSourceStub.instances).toHaveLength(2);
     });
+
+    it("disconnect() closes the connection and does not reconnect", () => {
+      jest.useFakeTimers({ doNotFake: ["nextTick"] });
+      delete globalThis.__wdmEventSourceWrapper;
+      EventSourceStub.instances.length = 0;
+      client = loadClient();
+
+      const [first] = EventSourceStub.instances;
+      client.disconnect();
+
+      expect(first.closed).toBe(true);
+      // Neither the watchdog nor a reconnect timer may re-open it.
+      jest.advanceTimersByTime(60 * 1000);
+      expect(EventSourceStub.instances).toHaveLength(1);
+    });
+
+    it("disconnect() drops the cached wrapper so a new connect starts fresh", () => {
+      client.disconnect();
+      expect(
+        globalThis.__wdmEventSourceWrapper["/__webpack_hmr"],
+      ).toBeUndefined();
+
+      client.setOptionsAndConnect({});
+      expect(EventSourceStub.instances).toHaveLength(2);
+      expect(EventSourceStub.lastInstance().closed).toBe(false);
+    });
   });
 
   describe("with logging option", () => {