fix(hot): align statsOptions and heartbeat validation and pair duplicate-name bundles by occurrence

statsOptions now accepts only the object form everywhere: the schema
rejected string presets the types allowed, and booleans validated but
were silently ignored since toBundles only merges objects over the
middleware's base stats options. Schema, JSDoc, and generated types all
agree now, so invalid forms fail validation instead of at runtime.

heartbeat: 0 was schema-valid but silently replaced with the 10s
default by a falsy check — the schema now requires >= 1 and the code
uses ?? so the option and its validation tell the same story.

Author: bjohansebas

src/hot.js

@@ -8,7 +8,9 @@
 /** @typedef {import("./index.js").IncomingMessage} IncomingMessage */
 /** @typedef {import("./index.js").ServerResponse} ServerResponse */
 
-/** @typedef {NonNullable<import("webpack").Configuration["stats"]>} StatsOptions */
+// The object form only (no presets/booleans) — it is merged over the
+// middleware's own base options, which string or boolean forms cannot be.
+/** @typedef {import("webpack").StatsOptions} StatsOptions */
 
 /**
  * @typedef {object} HotOptions
@@ -219,7 +221,7 @@ function toBundles(statsResult, statsOptions) {
     timings: true,
     errors: true,
     warnings: true,
-    ...(statsOptions && typeof statsOptions === "object" ? statsOptions : {}),
+    ...statsOptions,
   };
 
   // Multi-compiler stats have stats for each child compiler.
@@ -257,18 +259,29 @@ function bundlePayload(stats, action) {
  * @param {EventStream} eventStream event stream
  */
 function publishBundles(bundles, previousBundles, eventStream) {
+  /** @type {Map<string, number>} */
+  const occurrences = new Map();
+
   for (const [index, stats] of bundles.entries()) {
     const name = stats.name || "";
 
     // Paired by name so a changing set of compilations (children appearing,
-    // config reloads) cannot compare a bundle against a sibling's hash;
-    // unnamed bundles fall back to their position.
+    // config reloads) cannot compare a bundle against a sibling's hash.
+    // Webpack does not forbid duplicate names, so same-named bundles pair by
+    // occurrence; unnamed bundles fall back to their position.
     let previous = null;
 
     if (previousBundles !== null) {
-      previous = name
-        ? previousBundles.find((bundle) => (bundle.name || "") === name) || null
-        : previousBundles[index] || null;
+      if (name) {
+        const occurrence = occurrences.get(name) || 0;
+        occurrences.set(name, occurrence + 1);
+        previous =
+          previousBundles.filter((bundle) => (bundle.name || "") === name)[
+            occurrence
+          ] || null;
+      } else {
+        previous = previousBundles[index] || null;
+      }
     }
 
     const changed =
@@ -296,7 +309,7 @@ function publishBundles(bundles, previousBundles, eventStream) {
 function createHot(compiler, userOptions) {
   const options = userOptions === true ? {} : userOptions;
   const path = options.path || HOT_DEFAULT_PATH;
-  const heartbeat = options.heartbeat || HOT_DEFAULT_HEARTBEAT;
+  const heartbeat = options.heartbeat ?? HOT_DEFAULT_HEARTBEAT;
   const { statsOptions } = options;
   const logger = compiler.getInfrastructureLogger("webpack-dev-middleware");
 

src/options.json

@@ -197,23 +197,16 @@
             "heartbeat": {
               "description": "Heartbeat interval (in milliseconds) used to keep the SSE connection alive.",
               "type": "number",
-              "minimum": 0
+              "minimum": 1
             },
             "progress": {
               "description": "Publish compilation progress events to the clients.",
               "type": "boolean"
             },
             "statsOptions": {
               "description": "Webpack stats options used when serializing compilation results.",
-              "anyOf": [
-                {
-                  "type": "boolean"
-                },
-                {
-                  "type": "object",
-                  "additionalProperties": true
-                }
-              ]
+              "type": "object",
+              "additionalProperties": true
             }
           }
         }

test/__snapshots__/validation-options.test.js.snap.webpack5

@@ -77,7 +77,13 @@ exports[`validation should throw an error on the "headers" option with "true" va
 
 exports[`validation should throw an error on the "hot" option with "{"heartbeat":-1}" value 1`] = `
 "Invalid options object. Dev Middleware has been initialized using an options object that does not match the API schema.
- - options.hot.heartbeat should be >= 0.
+ - options.hot.heartbeat should be >= 1.
+   -> Heartbeat interval (in milliseconds) used to keep the SSE connection alive."
+`;
+
+exports[`validation should throw an error on the "hot" option with "{"heartbeat":0}" value 1`] = `
+"Invalid options object. Dev Middleware has been initialized using an options object that does not match the API schema.
+ - options.hot.heartbeat should be >= 1.
    -> Heartbeat interval (in milliseconds) used to keep the SSE connection alive."
 `;
 
@@ -87,6 +93,20 @@ exports[`validation should throw an error on the "hot" option with "{"path":""}"
    -> The path the SSE endpoint is served at."
 `;
 
+exports[`validation should throw an error on the "hot" option with "{"statsOptions":"errors-only"}" value 1`] = `
+"Invalid options object. Dev Middleware has been initialized using an options object that does not match the API schema.
+ - options.hot.statsOptions should be an object:
+   object { … }
+   -> Webpack stats options used when serializing compilation results."
+`;
+
+exports[`validation should throw an error on the "hot" option with "{"statsOptions":true}" value 1`] = `
+"Invalid options object. Dev Middleware has been initialized using an options object that does not match the API schema.
+ - options.hot.statsOptions should be an object:
+   object { … }
+   -> Webpack stats options used when serializing compilation results."
+`;
+
 exports[`validation should throw an error on the "hot" option with "{"unknown":true}" value 1`] = `
 "Invalid options object. Dev Middleware has been initialized using an options object that does not match the API schema.
  - options.hot has an unknown property 'unknown'. These properties are valid:

test/hot.test.js

@@ -437,6 +437,33 @@ describe("createHot", () => {
     hot.close();
   });
 
+  it("pairs bundles sharing a name by occurrence so unchanged ones publish sync", () => {
+    const compiler = makeFakeCompiler();
+    const hot = createHot(compiler, {});
+    const { writes } = attachClient({ handler: hot.handle });
+
+    // Webpack does not forbid two configs with the same name. Pairing by name
+    // alone would compare the second "app" against the first one's hash and
+    // report it as built on every rebuild.
+    const multiStats = {
+      stats: [
+        makeFakeStats({ name: "app", hash: "a1" }),
+        makeFakeStats({ name: "app", hash: "b1" }),
+      ],
+    };
+
+    compiler.emitDone(multiStats);
+    writes.length = 0;
+
+    compiler.emitInvalid();
+    compiler.emitDone(multiStats);
+
+    expect(writes.filter((w) => w.includes('"action":"sync"'))).toHaveLength(2);
+    expect(writes.some((w) => w.includes('"action":"built"'))).toBe(false);
+
+    hot.close();
+  });
+
   it("publishes built when the bundle's hash changed", () => {
     const compiler = makeFakeCompiler();
     const hot = createHot(compiler, {});

test/validation-options.test.js

@@ -92,10 +92,21 @@ describe("validation", () => {
         {},
         { path: "/__hmr" },
         { heartbeat: 1000 },
-        { statsOptions: true },
         { statsOptions: { all: false } },
       ],
-      failure: ["foo", 0, { path: "" }, { heartbeat: -1 }, { unknown: true }],
+      failure: [
+        "foo",
+        0,
+        { path: "" },
+        { heartbeat: -1 },
+        // 0 would silently fall back to the default interval — reject it.
+        { heartbeat: 0 },
+        { unknown: true },
+        // Presets and booleans cannot be merged over the middleware's base
+        // stats options — only the object form is accepted.
+        { statsOptions: "errors-only" },
+        { statsOptions: true },
+      ],
     },
   };
 

types/hot.d.ts

@@ -51,7 +51,7 @@ declare const HOT_DEFAULT_HEARTBEAT: number;
 /** @typedef {import("webpack").StatsError} StatsError */
 /** @typedef {import("./index.js").IncomingMessage} IncomingMessage */
 /** @typedef {import("./index.js").ServerResponse} ServerResponse */
-/** @typedef {NonNullable<import("webpack").Configuration["stats"]>} StatsOptions */
+/** @typedef {import("webpack").StatsOptions} StatsOptions */
 /**
  * @typedef {object} HotOptions
  * @property {string=} path the path the SSE endpoint is served at
@@ -154,7 +154,7 @@ type StatsCompilation = import("webpack").StatsCompilation;
 type StatsError = import("webpack").StatsError;
 type IncomingMessage = import("./index.js").IncomingMessage;
 type ServerResponse = import("./index.js").ServerResponse;
-type StatsOptions = NonNullable<import("webpack").Configuration["stats"]>;
+type StatsOptions = import("webpack").StatsOptions;
 type HotOptions = {
   /**
    * the path the SSE endpoint is served at