react-websocket 3.5.0 → 3.6.0

package/README.md

@@ -18,7 +18,7 @@
 - **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,10 +117,11 @@ 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` |

package/dist/core.cjs

@@ -660,6 +660,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 +682,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 +691,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);
 		}
 	};
 }