react-websocket 3.5.0 → 4.0.0

package/README.md

@@ -12,13 +12,13 @@
 **[Documentation](https://mehmetkose.github.io/react-websocket/)** · [Getting started](https://mehmetkose.github.io/react-websocket/guide/getting-started) · [API](https://mehmetkose.github.io/react-websocket/api/) · [Recipes](https://mehmetkose.github.io/react-websocket/recipes) · [Changelog](CHANGELOG.md)
 
 - **Shared connections.** Components using the same URL share one socket. StrictMode, `<Activity>` and route transitions never open duplicates.
-- **Auto-reconnect.** Exponential backoff with jitter, plus an immediate retry when the browser comes back online or the tab becomes visible. Optional heartbeats detect dead links.
+- **Auto-reconnect.** Exponential backoff with full jitter, plus an immediate retry when the browser comes back online or the tab becomes visible. It backs off from a server that closes right after accepting, and stops on close codes that retrying can't fix. Optional heartbeats detect dead links.
 - **Send queue.** `send()` before the socket is open just works. The message goes out on connect. Mark input `volatile` so it's never replayed late, or `key` it so only the newest is sent. Put control messages first with `priority`, and drop stream data on a slow link with `maxBuffered`.
 - **Typed messages.** `json: true`, your own codec, or validation with any [Standard Schema](https://standardschema.dev) library (zod, valibot, arktype), with inferred types.
 - **Suspense.** `use(client.ready)` waits for the first connection, and reconnects never flash a fallback.
 - **Topic subscriptions.** Reference-counted `subscribe`/`unsubscribe` messages that are sent again after every reconnect, so feeds don't silently stop.
 - **Message state.** Reduce messages into a store, and let each component re-render only when its slice changes, at most once per frame if you like.
-- **Requests and latency.** Await replies with timeouts and cancellation, and measure round-trip time and the server's clock for ping displays and synchronized countdowns.
+- **Requests, streams and latency.** Await a reply, or iterate over streamed ones such as an LLM's tokens, with timeouts and a cancel that tells the server to stop. Measure round-trip time and the server's clock for ping displays and synchronized countdowns.
 - **Games.** Snapshot interpolation and client-side prediction with server reconciliation, from `react-websocket/timeline`, so other players move smoothly and your own controls respond at once. A send rate that adapts to the connection keeps players on a poor link from building up lag.
 - **Server requests.** Answer requests from the server, such as an AI agent's, in code for browser-only tools, or from a dialog for human approval. Every request gets exactly one reply, and none is sent to the wrong connection.
 - **SSR-safe.** Never connects during a server render, hydrates cleanly, and ships a `'use client'` entry for Next.js and other Server Components frameworks.
@@ -117,14 +117,16 @@ function Room() {
 | `useWebSocketState(store, selector?)` | Read state reduced from messages; re-renders only when the selection changes |
 | `useWebSocketLatency(latency)` | Round-trip time and server clock offset |
 | `useAgentApproval(responder, method)` | Requests from the server waiting for a person to answer |
+| `useWebSocketStream(rpc, options?)` | Stream the replies to a request into a value, e.g. tokens into an answer; returns `{ value, status, error, start, abort }` |
 | `createWebSocket(url, options?)` | A shareable client: `send`, `on`, `connect`, `close`, `reconnect`, `ready`, `getSnapshot`, `subscribe` |
 | `createWebSocketTopics(client, { subscribe, unsubscribe })` | Topic subscription manager for `useWebSocketTopic` |
 | `createWebSocketState(client, { initialState, reduce })` | Message-state store for `useWebSocketState` |
-| `createWebSocketRequests(client, { send, reply })` | `request(message)` returns a promise of the reply, with timeouts |
+| `createWebSocketRequests(client, { send, reply })` | `request(message)` returns a promise of the reply, and `stream(message)` an async iterator of replies, with timeouts and `cancel` |
 | `createWebSocketLatency(client, { ping, pong })` | Ping tracker for `useWebSocketLatency`, plus `serverNow()` |
 | `createWebSocketSendRate(client, options?)` | `send(message, key)` coalesced per key at a rate that drops on a congested link |
 | `createWebSocketResponder(client, { request, respond, error })` | Answer the server's requests: `onRequest(method, handler)`, or a person through `useAgentApproval` |
 | `MessageError` | Reported to `onError` when a message fails `parse` or `schema` |
+| `retryableClose(close)` | The default `reconnect.shouldReconnect`: retries every close except `1002`, `1003` and `1008` |
 | `createWebSocketTimeline(client, { snapshot, interpolate, input })` | From `react-websocket/timeline`: interpolated server snapshots (`at()`) and predicted inputs (`predicted()`, `input()`) for multiplayer games |
 | `createChaosWebSocket(options)` | From `react-websocket/chaos`: a `WebSocket` class that adds latency, lost messages and dropped connections in development |
 
@@ -135,9 +137,9 @@ function Room() {
 | `json` | `false` | `JSON.parse` incoming and `JSON.stringify` outgoing messages |
 | `parse(data)` / `serialize(message)` | | Custom codec; takes precedence over `json` |
 | `schema` | | Standard Schema validation; types are inferred |
-| `reconnect` | `true` | `false`, or `{ maxAttempts, minDelay, maxDelay, factor, jitter, shouldReconnect }` |
+| `reconnect` | `true` | `false`, or `{ maxAttempts, minDelay, maxDelay, factor, jitter, minUptime, shouldReconnect }` |
 | `heartbeat` | | `{ interval, message, pong, timeout }` |
-| `queue` | `true` | `false`, or `{ limit }` |
+| `queue` | `true` (100 messages) | `false`, or `{ limit }` |
 | `logger` | | e.g. `console.debug` |
 | `WebSocket` | global | Custom implementation for tests, Node, or chaos testing |
 
@@ -148,7 +150,7 @@ function Room() {
 - [Shared clients](https://mehmetkose.github.io/react-websocket/guide/shared-clients) · [Messages and types](https://mehmetkose.github.io/react-websocket/guide/messages) · [Reconnecting and heartbeats](https://mehmetkose.github.io/react-websocket/guide/reconnecting)
 - [Suspense](https://mehmetkose.github.io/react-websocket/guide/suspense) · [Server rendering and Next.js](https://mehmetkose.github.io/react-websocket/guide/ssr) · [StrictMode, Activity and lifecycle](https://mehmetkose.github.io/react-websocket/guide/lifecycle)
 - [Authentication](https://mehmetkose.github.io/react-websocket/guide/authentication) · [Performance](https://mehmetkose.github.io/react-websocket/guide/performance) · [Real-time games](https://mehmetkose.github.io/react-websocket/guide/games) · [AI agents](https://mehmetkose.github.io/react-websocket/guide/agents) · [Testing](https://mehmetkose.github.io/react-websocket/guide/testing) · [Chaos testing](https://mehmetkose.github.io/react-websocket/guide/chaos) · [Without React](https://mehmetkose.github.io/react-websocket/guide/without-react)
-- [Recipes](https://mehmetkose.github.io/react-websocket/recipes) · [Troubleshooting](https://mehmetkose.github.io/react-websocket/troubleshooting) · [Migrating from v2](https://mehmetkose.github.io/react-websocket/migration)
+- [Recipes](https://mehmetkose.github.io/react-websocket/recipes) · [Troubleshooting](https://mehmetkose.github.io/react-websocket/troubleshooting) · [Migrating from v3](https://mehmetkose.github.io/react-websocket/migration-v3) · [Migrating from v2](https://mehmetkose.github.io/react-websocket/migration)
 
 The docs source lives in [`docs/`](docs). Run `npm run docs:dev` to browse it locally.
 
@@ -160,6 +162,10 @@ The docs source lives in [`docs/`](docs). Run `npm run docs:dev` to browse it lo
 | Runtimes | Modern browsers; Node via the `WebSocket` option |
 | Frameworks | Vite, Next.js (App and Pages Router), Remix/React Router, Astro islands, and any React setup |
 
+## Migrating from v3
+
+v4 changes no APIs, only four defaults: the backoff resets once a connection has stayed open for 5 seconds, close codes `1002`, `1003` and `1008` aren't retried, jitter is full, and the send queue holds 100 messages. Each has a one-line opt-out. See [Migrating from v3](https://mehmetkose.github.io/react-websocket/migration-v3).
+
 ## Migrating from v2
 
 v2 was a `<Websocket>` class component. v3 replaces it with hooks: `<Websocket url onMessage />` becomes `useWebSocket(url, { onMessage })`, and `ref.sendMessage(msg)` becomes `send(msg)`. See the [migration guide](https://mehmetkose.github.io/react-websocket/migration) for the full mapping.

package/dist/core.cjs

@@ -31,8 +31,26 @@ const RECONNECT_DEFAULTS = {
 	minDelay: 1e3,
 	maxDelay: 3e4,
 	factor: 2,
-	jitter: .5
+	jitter: 1,
+	minUptime: 5e3
 };
+const QUEUE_LIMIT = 100;
+/**
+* The default `reconnect.shouldReconnect`: retry every close except `1002` (protocol error),
+* `1003` (unsupported data) and `1008` (policy violation, often a rejected login), which
+* retrying the same way can't fix. Call it from your own `shouldReconnect` to keep that rule.
+*
+* @example
+* ```ts
+* createWebSocket(url, {
+*   // Also stop on our server's "invalid token" code.
+*   reconnect: { shouldReconnect: close => close.code !== 4001 && retryableClose(close) }
+* });
+* ```
+*/
+function retryableClose(close) {
+	return close.code !== 1002 && close.code !== 1003 && close.code !== 1008;
+}
 const READY_GRACE = 5e3;
 function createDeferred() {
 	let resolve;
@@ -84,7 +102,7 @@ function createClient(url, options = {}) {
 		...RECONNECT_DEFAULTS,
 		...typeof options.reconnect === "object" ? options.reconnect : {}
 	};
-	const queueLimit = options.queue === false ? 0 : typeof options.queue === "object" ? Math.max(0, options.queue.limit ?? Infinity) : Infinity;
+	const queueLimit = options.queue === false ? 0 : Math.max(0, (typeof options.queue === "object" ? options.queue.limit : void 0) ?? QUEUE_LIMIT);
 	let snapshot = {
 		status: "idle",
 		lastMessage: void 0,
@@ -109,8 +127,10 @@ function createClient(url, options = {}) {
 	let inbox = null;
 	let generation = 0;
 	let windowBound = false;
+	let failures = 0;
 	let retryTimer;
 	let teardownTimer;
+	let stableTimer;
 	let heartbeatTimer;
 	let pongTimer;
 	function set(patch) {
@@ -177,10 +197,12 @@ function createClient(url, options = {}) {
 			}, heartbeat.timeout);
 		}, heartbeat.interval);
 	}
-	function stopHeartbeat() {
+	/** Stop the timers that belong to the current open socket. */
+	function stopSocketTimers() {
 		clearInterval(heartbeatTimer);
 		clearTimeout(pongTimer);
-		heartbeatTimer = pongTimer = void 0;
+		clearTimeout(stableTimer);
+		heartbeatTimer = pongTimer = stableTimer = void 0;
 	}
 	/** Stop tracking `socket`. Its eventual close event is still reported unless `reportClose` is false. */
 	function detach(socket, reportClose) {
@@ -251,6 +273,7 @@ function createClient(url, options = {}) {
 				status: "open",
 				attempt: 0
 			});
+			if (retry) stableTimer = setTimeout(() => failures = 0, retry.minUptime);
 			startHeartbeat(socket);
 			ready?.resolve();
 			if (refs === 0 && !pinned) {
@@ -275,14 +298,14 @@ function createClient(url, options = {}) {
 		};
 	}
 	function handleClose(info) {
-		stopHeartbeat();
+		stopSocketTimers();
 		log("closed", info);
 		retryOrFail(info);
 		emit("close", info);
 	}
 	function retryOrFail(info, error) {
-		if (wanted && retry && snapshot.attempt < retry.maxAttempts && (retry.shouldReconnect?.(info) ?? true)) {
-			const attempt = snapshot.attempt + 1;
+		if (wanted && retry && failures < retry.maxAttempts && (retry.shouldReconnect ?? retryableClose)(info)) {
+			const attempt = ++failures;
 			const delay = backoff(attempt);
 			set({
 				status: "reconnecting",
@@ -297,7 +320,10 @@ function createClient(url, options = {}) {
 		opened = false;
 		unbindWindow();
 		pending = [];
-		set({ status: "closed" });
+		set({
+			status: "closed",
+			attempt: failures
+		});
 		rejectReady(reason);
 	}
 	function receive(event, socket) {
@@ -402,6 +428,7 @@ function createClient(url, options = {}) {
 			opened = false;
 			if (ready?.settled) ready = null;
 		}
+		failures = 0;
 		snapshot = {
 			...snapshot,
 			attempt: 0
@@ -423,7 +450,8 @@ function createClient(url, options = {}) {
 		generation++;
 		clearTimeout(retryTimer);
 		retryTimer = void 0;
-		stopHeartbeat();
+		failures = 0;
+		stopSocketTimers();
 		unbindWindow();
 		pending = [];
 		if (ws) {
@@ -446,7 +474,7 @@ function createClient(url, options = {}) {
 		if (!getImpl()) return;
 		clearTimeout(retryTimer);
 		retryTimer = void 0;
-		stopHeartbeat();
+		stopSocketTimers();
 		if (ws) {
 			const socket = ws;
 			detach(socket, true);
@@ -660,6 +688,8 @@ function createWebSocketLatency(client, options) {
 //#endregion
 //#region src/requests.ts
 const lastIds = /* @__PURE__ */ new WeakMap();
+const VOLATILE$2 = { volatile: true };
+const noop = () => {};
 /**
 * Send requests and await their replies, matched by an id the library generates.
 *
@@ -680,8 +710,8 @@ const lastIds = /* @__PURE__ */ new WeakMap();
 */
 function createWebSocketRequests(client, options) {
 	const waiting = /* @__PURE__ */ new Map();
-	function rejectWhere(test, reason) {
-		for (const entry of [...waiting.values()]) if (test(entry)) entry.reject(reason());
+	function endWhere(test, reason, cancel) {
+		for (const entry of [...waiting.values()]) if (test(entry)) entry.end(true, reason(), cancel);
 	}
 	const offs = [
 		client.on("message", (message) => {
@@ -689,78 +719,131 @@ function createWebSocketRequests(client, options) {
 			const entry = id == null ? void 0 : waiting.get(String(id));
 			if (!entry) return;
 			const error = options.error?.(message);
-			if (error === void 0) entry.resolve(message);
-			else entry.reject(error);
+			if (error === void 0) entry.receive(message);
+			else entry.end(true, error);
 		}),
 		client.on("open", () => {
 			for (const entry of waiting.values()) entry.socket ??= client.socket;
 		}),
 		client.subscribe(() => {
 			const { status } = client.getSnapshot();
-			if (status === "closed" || status === "idle") rejectWhere(() => true, () => /* @__PURE__ */ new Error("WebSocket was closed before the request was answered"));
-			else rejectWhere((entry) => entry.socket !== null && entry.socket !== client.socket, () => /* @__PURE__ */ new Error("WebSocket connection was lost before the request was answered"));
+			if (status === "closed" || status === "idle") endWhere(() => true, () => /* @__PURE__ */ new Error("WebSocket was closed before the request was answered"));
+			else endWhere((entry) => entry.socket !== null && entry.socket !== client.socket, () => /* @__PURE__ */ new Error("WebSocket connection was lost before the request was answered"));
 		})
 	];
+	/**
+	* Send `message` as a new request. `next` gets each reply that isn't an error and returns
+	* whether it was the last; `done` runs once, when the request ends. Returns a function that
+	* ends it from this side and tells the server.
+	*/
+	function start(message, requestOptions, next, done) {
+		const { signal, priority } = requestOptions;
+		if (signal?.aborted) {
+			done(true, signal.reason);
+			return noop;
+		}
+		const id = (lastIds.get(client) ?? 0) + 1;
+		lastIds.set(client, id);
+		const key = String(id);
+		const timeout = requestOptions.timeout ?? options.timeout ?? 1e4;
+		const release = client.acquire();
+		let timer;
+		const onAbort = () => entry.end(true, signal.reason, true);
+		function arm() {
+			clearTimeout(timer);
+			if (timeout > 0 && timeout < Infinity) timer = setTimeout(() => entry.end(true, new DOMException(`Request ${id} timed out after ${timeout}ms`, "TimeoutError"), true), timeout);
+		}
+		const entry = {
+			socket: null,
+			receive(reply) {
+				if (next(reply)) entry.end(false);
+				else arm();
+			},
+			end(failed, reason, cancel) {
+				if (!waiting.delete(key)) return;
+				clearTimeout(timer);
+				signal?.removeEventListener("abort", onAbort);
+				release();
+				done(failed, reason);
+				if (cancel && options.cancel) try {
+					client.send(options.cancel(id), entry.socket ? VOLATILE$2 : { priority });
+				} catch (error) {
+					queueMicrotask(() => {
+						throw error;
+					});
+				}
+			}
+		};
+		waiting.set(key, entry);
+		signal?.addEventListener("abort", onAbort, { once: true });
+		arm();
+		const { status } = client.getSnapshot();
+		if (status === "closed" || status === "idle") entry.end(true, /* @__PURE__ */ new Error(`WebSocket is ${status}: request not sent`));
+		else try {
+			if (client.send(options.send(message, id), {
+				...requestOptions,
+				onDrop() {
+					entry.end(true, /* @__PURE__ */ new Error("Request was dropped from the send queue before it was sent"));
+					requestOptions.onDrop?.();
+				}
+			})) entry.socket = client.socket;
+			else if (client.socket?.readyState === 1) entry.end(true, /* @__PURE__ */ new Error("WebSocket send buffer is full: request dropped"));
+			else if (requestOptions.volatile) entry.end(true, /* @__PURE__ */ new Error("WebSocket is not open: request dropped"));
+		} catch (error) {
+			entry.end(true, error);
+		}
+		return () => entry.end(false, void 0, true);
+	}
 	return {
 		client,
 		request(message, requestOptions = {}) {
-			const { signal } = requestOptions;
-			if (signal?.aborted) return Promise.reject(signal.reason);
-			const id = (lastIds.get(client) ?? 0) + 1;
-			lastIds.set(client, id);
-			const key = String(id);
-			const timeout = requestOptions.timeout ?? options.timeout ?? 1e4;
 			return new Promise((resolve, reject) => {
-				let timer;
-				const release = client.acquire();
-				const onAbort = () => entry.reject(signal.reason);
-				function settle() {
-					waiting.delete(key);
-					clearTimeout(timer);
-					signal?.removeEventListener("abort", onAbort);
-					release();
-				}
-				const entry = {
-					socket: null,
-					resolve(reply) {
-						settle();
-						resolve(reply);
-					},
-					reject(reason) {
-						settle();
-						reject(reason);
-					}
-				};
-				waiting.set(key, entry);
-				signal?.addEventListener("abort", onAbort, { once: true });
-				if (timeout > 0 && timeout < Infinity) timer = setTimeout(() => entry.reject(new DOMException(`Request ${id} timed out after ${timeout}ms`, "TimeoutError")), timeout);
-				const { status } = client.getSnapshot();
-				if (status === "closed" || status === "idle") {
-					entry.reject(/* @__PURE__ */ new Error(`WebSocket is ${status}: request not sent`));
-					return;
-				}
-				let sent;
+				start(message, requestOptions, (reply) => {
+					resolve(reply);
+					return true;
+				}, (failed, reason) => {
+					if (failed) reject(reason);
+				});
+			});
+		},
+		stream(message, requestOptions = {}) {
+			const last = options.done;
+			if (!last) throw new TypeError("stream() needs the `done` option");
+			const replies = [];
+			let ended;
+			let wake = noop;
+			const stop = start(message, requestOptions, (reply) => {
+				replies.push(reply);
+				wake();
+				return last(reply);
+			}, (failed, reason) => {
+				if (requestOptions.signal?.aborted) replies.length = 0;
+				ended = [failed, reason];
+				wake();
+			});
+			async function* read() {
 				try {
-					sent = client.send(options.send(message, id), {
-						...requestOptions,
-						onDrop() {
-							entry.reject(/* @__PURE__ */ new Error("Request was dropped from the send queue before it was sent"));
-							requestOptions.onDrop?.();
-						}
-					});
-				} catch (error) {
-					entry.reject(error);
-					return;
+					for (;;) if (replies.length) yield replies.shift();
+					else if (ended) {
+						if (ended[0]) throw ended[1];
+						return;
+					} else await new Promise((resolve) => wake = resolve);
+				} finally {
+					stop();
 				}
-				if (sent) entry.socket = client.socket;
-				else if (client.socket?.readyState === 1) entry.reject(/* @__PURE__ */ new Error("WebSocket send buffer is full: request dropped"));
-				else if (requestOptions.volatile) entry.reject(/* @__PURE__ */ new Error("WebSocket is not open: request dropped"));
-			});
+			}
+			const iterator = read();
+			const close = iterator.return;
+			iterator.return = (value) => {
+				stop();
+				return close.call(iterator, value);
+			};
+			return iterator;
 		},
 		pending: () => waiting.size,
 		dispose() {
 			offs.forEach((off) => off());
-			rejectWhere(() => true, () => /* @__PURE__ */ new Error("Requests were disposed"));
+			endWhere(() => true, () => /* @__PURE__ */ new Error("Requests were disposed"), true);
 		}
 	};
 }
@@ -1177,5 +1260,6 @@ exports.createWebSocketResponder = createWebSocketResponder;
 exports.createWebSocketSendRate = createWebSocketSendRate;
 exports.createWebSocketState = createWebSocketState;
 exports.createWebSocketTopics = createWebSocketTopics;
+exports.retryableClose = retryableClose;
 
 //# sourceMappingURL=core.cjs.map