fix(client): ship types for the client exports, and say it is ESM

.changeset/client-type-declarations.md

@@ -0,0 +1,5 @@
+---
+"webpack-dev-middleware": patch
+---
+
+Ship type declarations for the `./client`, `./client/sse`, `./client/ws`, `./client/indicator` and `./client/overlay` exports, and mark the client as the ES modules it has always been. A TypeScript consumer importing one of them got `any` — or, under `node16`/`nodenext` resolution, the module namespace instead of the default export, because the files are ES modules inside a CommonJS package with nothing saying so

package.json

@@ -21,11 +21,26 @@
       "types": "./types/index.d.ts",
       "default": "./dist/index.js"
     },
-    "./client": "./client/index.js",
-    "./client/sse": "./client/clients/EventSourceClient.js",
-    "./client/ws": "./client/clients/WebSocketClient.js",
-    "./client/indicator": "./client/indicator.js",
-    "./client/overlay": "./client/overlay.js",
+    "./client": {
+      "types": "./types/client/index.d.ts",
+      "default": "./client/index.js"
+    },
+    "./client/sse": {
+      "types": "./types/client/clients/EventSourceClient.d.ts",
+      "default": "./client/clients/EventSourceClient.js"
+    },
+    "./client/ws": {
+      "types": "./types/client/clients/WebSocketClient.d.ts",
+      "default": "./client/clients/WebSocketClient.js"
+    },
+    "./client/indicator": {
+      "types": "./types/client/indicator.d.ts",
+      "default": "./client/indicator.js"
+    },
+    "./client/overlay": {
+      "types": "./types/client/overlay.d.ts",
+      "default": "./client/overlay.js"
+    },
     "./package.json": "./package.json"
   },
   "main": "dist/index.js",
@@ -47,7 +62,7 @@
     "fix": "npm-run-all -l fix:js fix:schema-check fix:prettier",
     "clean": "del-cli client dist types",
     "prebuild": "npm run clean",
-    "build:types": "tsc && prettier \"types/**/*.ts\" --write",
+    "build:types": "tsc && tsc -p tsconfig.client.build.json && node ./scripts/mark-client-esm.mjs && prettier \"types/**/*.ts\" --write",
     "build:code": "babel src -d dist --copy-files",
     "build:client": "babel client-src -d client --copy-files",
     "build": "npm-run-all -p \"build:**\"",

scripts/mark-client-esm.mjs

@@ -0,0 +1,27 @@
+// The browser client keeps ESM syntax (babel runs with `modules: false` so
+// webpack can tree-shake it), but the package itself is CommonJS. Without a
+// marker, Node and TypeScript resolve `client/*.js` and its declarations as
+// CommonJS, and a consumer importing the default gets the module namespace
+// rather than the class. A nested `package.json` says what these two
+// directories really contain, without renaming a published file — those paths
+// are what `client.webSocketTransport` points at.
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+// Not `import.meta.dirname`: this package supports node.js 20.9, which does not
+// have it.
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+for (const dir of ["client", "types/client"]) {
+  const target = path.join(ROOT, dir);
+
+  // `build` runs every `build:*` in parallel, so the directory babel writes
+  // `client` into may not exist yet when this runs — and `build:types` on its
+  // own, after a `clean`, never creates it at all.
+  await mkdir(target, { recursive: true });
+  await writeFile(
+    path.join(target, "package.json"),
+    `${JSON.stringify({ type: "module" }, null, 2)}\n`,
+  );
+}

tsconfig.client.build.json

@@ -0,0 +1,14 @@
+{
+  // Emits the declarations for the browser client, which the `./client/*`
+  // exports need: without them a TypeScript consumer importing one gets `any`,
+  // or an error under `noImplicitAny`. Checking happens in
+  // `tsconfig.client.json`; this one only writes the `.d.ts` files.
+  "extends": "./tsconfig.client.json",
+  "compilerOptions": {
+    "noEmit": false,
+    "declaration": true,
+    "emitDeclarationOnly": true,
+    "rootDir": "./client-src",
+    "outDir": "./types/client"
+  }
+}

types/client/clients/EventSourceClient.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Server-Sent Events. A connection can die without the browser firing `error`
+ * — a proxy that stops forwarding, a laptop that slept — so this one watches
+ * for silence as well, and reports that as a close for the caller to reconnect.
+ *
+ * A failure is not logged here, for the same reason the WebSocket one does not
+ * log it: `error` fires on every routine reconnection, so saying so would be
+ * noise rather than news.
+ * @implements {CommunicationClient}
+ */
+export default class EventSourceClient implements CommunicationClient {
+  /**
+   * @param {string} url url to connect to
+   * @param {{ timeout?: number }=} options how long silence is tolerated
+   */
+  constructor(
+    url: string,
+    options?:
+      | {
+          timeout?: number;
+        }
+      | undefined,
+  );
+  timeout: number;
+  /** @type {ClientHandler | undefined} */
+  openHandler: ClientHandler | undefined;
+  /** @type {ClientHandler | undefined} */
+  closeHandler: ClientHandler | undefined;
+  /** @type {ClientHandler | undefined} */
+  messageHandler: ClientHandler | undefined;
+  closed: boolean;
+  lastActivity: number;
+  client: EventSource;
+  timer: number;
+  /**
+   * End this connection and report it, once.
+   */
+  handleDisconnect(): void;
+  /**
+   * @param {ClientHandler} fn called once the connection is open
+   */
+  onOpen(fn: ClientHandler): void;
+  /**
+   * @param {ClientHandler} fn called once the connection is gone
+   */
+  onClose(fn: ClientHandler): void;
+  /**
+   * @param {ClientHandler} fn called with each message, as a string
+   */
+  onMessage(fn: ClientHandler): void;
+  /**
+   * Stop the watchdog and the connection, without reporting a close.
+   */
+  close(): void;
+}
+export type CommunicationClient =
+  import("./createSocket.js").CommunicationClient;
+export type ClientHandler = import("./createSocket.js").ClientHandler;

types/client/clients/WebSocketClient.d.ts

@@ -0,0 +1,44 @@
+/**
+ * A WebSocket. The browser reports a dropped connection itself, and the server
+ * pings to find a half-open one, so unlike Server-Sent Events this needs no
+ * watchdog of its own.
+ *
+ * A failure is not logged here. The `error` event carries no detail by
+ * specification, so it would print an opaque object, and it is followed by the
+ * `close` the shared socket already reports and acts on — which is also all
+ * Server-Sent Events say, so neither transport is noisier than the other.
+ * @implements {CommunicationClient}
+ */
+export default class WebSocketClient implements CommunicationClient {
+  /**
+   * @param {string} url url to connect to
+   */
+  constructor(url: string);
+  /** @type {ClientHandler | undefined} */
+  openHandler: ClientHandler | undefined;
+  /** @type {ClientHandler | undefined} */
+  closeHandler: ClientHandler | undefined;
+  /** @type {ClientHandler | undefined} */
+  messageHandler: ClientHandler | undefined;
+  closed: boolean;
+  client: WebSocket;
+  /**
+   * @param {ClientHandler} fn called once the connection is open
+   */
+  onOpen(fn: ClientHandler): void;
+  /**
+   * @param {ClientHandler} fn called once the connection is gone
+   */
+  onClose(fn: ClientHandler): void;
+  /**
+   * @param {ClientHandler} fn called with each message, as a string
+   */
+  onMessage(fn: ClientHandler): void;
+  /**
+   * Close without reporting it, so the caller does not reconnect.
+   */
+  close(): void;
+}
+export type CommunicationClient =
+  import("./createSocket.js").CommunicationClient;
+export type ClientHandler = import("./createSocket.js").ClientHandler;

types/client/clients/createSocket.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Called with no argument for open and close, and with the message string for
+ * a message.
+ * @typedef {(data?: string) => void} ClientHandler
+ */
+/**
+ * One transport, as the page speaks it. Constructed with the url, the same
+ * shape webpack-dev-server's `client.webSocketTransport` has always taken, so
+ * a client written for that works here unchanged.
+ * @typedef {object} CommunicationClient
+ * @property {(fn: ClientHandler) => void} onOpen called once the connection is open
+ * @property {(fn: ClientHandler) => void} onClose called once the connection is gone
+ * @property {(fn: ClientHandler) => void} onMessage called with each message, as a string
+ * @property {() => void} close close without reporting it
+ */
+/**
+ * @typedef {new (url: string, options?: EXPECTED_ANY) => CommunicationClient} CommunicationClientConstructor
+ */
+/** @typedef {any} EXPECTED_ANY */
+/**
+ * @typedef {object} SocketOptions
+ * @property {number=} retries how many times to reconnect before giving up, `Infinity` to keep trying
+ * @property {((attempt: number) => number)=} retryDelay how long to wait before the attempt, in milliseconds
+ * @property {boolean=} logRetries say so before each attempt, which only a bounded number of them can afford to do
+ * @property {(() => void)=} onDisconnect called once per outage — on the first drop, whether or not that connection ever opened
+ * @property {EXPECTED_ANY=} clientOptions passed to the client's constructor
+ */
+/**
+ * Hold a connection open, reconnecting when it drops, and fan each message out
+ * to everyone listening. What "reconnect" costs is the transport's to say: a
+ * dropped WebSocket backs off, whereas Server-Sent Events retries at a steady
+ * interval for as long as the page is open.
+ * @param {CommunicationClientConstructor} Client what speaks the transport
+ * @param {string} url url to connect to
+ * @param {SocketOptions=} options how it reconnects
+ * @returns {{ addMessageListener: (fn: (event: { data: string }) => void) => void, close: () => void }} the socket
+ */
+export default function createSocket(
+  Client: CommunicationClientConstructor,
+  url: string,
+  options?: SocketOptions | undefined,
+): {
+  addMessageListener: (fn: (event: { data: string }) => void) => void;
+  close: () => void;
+};
+/**
+ * Called with no argument for open and close, and with the message string for
+ * a message.
+ */
+export type ClientHandler = (data?: string) => void;
+/**
+ * One transport, as the page speaks it. Constructed with the url, the same
+ * shape webpack-dev-server's `client.webSocketTransport` has always taken, so
+ * a client written for that works here unchanged.
+ */
+export type CommunicationClient = {
+  /**
+   * called once the connection is open
+   */
+  onOpen: (fn: ClientHandler) => void;
+  /**
+   * called once the connection is gone
+   */
+  onClose: (fn: ClientHandler) => void;
+  /**
+   * called with each message, as a string
+   */
+  onMessage: (fn: ClientHandler) => void;
+  /**
+   * close without reporting it
+   */
+  close: () => void;
+};
+export type CommunicationClientConstructor = new (
+  url: string,
+  options?: EXPECTED_ANY,
+) => CommunicationClient;
+export type EXPECTED_ANY = any;
+export type SocketOptions = {
+  /**
+   * how many times to reconnect before giving up, `Infinity` to keep trying
+   */
+  retries?: number | undefined;
+  /**
+   * how long to wait before the attempt, in milliseconds
+   */
+  retryDelay?: ((attempt: number) => number) | undefined;
+  /**
+   * say so before each attempt, which only a bounded number of them can afford to do
+   */
+  logRetries?: boolean | undefined;
+  /**
+   * called once per outage — on the first drop, whether or not that connection ever opened
+   */
+  onDisconnect?: (() => void) | undefined;
+  /**
+   * passed to the client's constructor
+   */
+  clientOptions?: EXPECTED_ANY | undefined;
+};