react-websocket 3.5.0 → 3.6.0

package/dist/core.d.ts

@@ -487,20 +487,36 @@ interface WebSocketRequestsOptions<Req, In, Out> {
   reply: (message: In) => number | string | null | undefined;
   /**
    * Called on a reply. Return something other than `undefined` to reject the request with
-   * it instead of resolving, e.g. for a server-side error reply.
+   * it instead of resolving, e.g. for a server-side error reply. A stream throws it.
    */
   error?: (message: In) => unknown;
   /**
-   * Default time to wait for a reply, in ms. `Infinity` waits forever.
+   * Whether a reply is the last one of a stream. `stream()` needs it. That reply is yielded
+   * too, then the stream ends.
+   */
+  done?: (message: In) => boolean;
+  /**
+   * Build the message that tells the server to stop working on request `id`. Sent when this
+   * side gives up: the request's `signal` aborts, it times out, a loop over a stream exits
+   * early, or the manager is disposed. Not sent after the last reply, an error reply, a lost
+   * connection or `close()`.
+   */
+  cancel?: (id: number) => Out;
+  /**
+   * Default time to wait for a reply, in ms. For a stream, the time to wait for each reply,
+   * including the first. `Infinity` waits forever.
    * @default 10000
    */
   timeout?: number;
 }
-/** Per-call options for {@link WebSocketRequests.request}. */
+/** Per-call options for {@link WebSocketRequests.request} and {@link WebSocketRequests.stream}. */
 interface RequestOptions extends SendOptions {
-  /** Time to wait for a reply, in ms. Overrides the manager's `timeout`. */
+  /**
+   * Time to wait for a reply (for a stream, for each reply), in ms. Overrides the manager's
+   * `timeout`.
+   */
   timeout?: number;
-  /** Abort the request. It rejects with `signal.reason`. A late reply is ignored. */
+  /** Abort the request. It rejects (a stream throws) with `signal.reason`. A late reply is ignored. */
   signal?: AbortSignal;
 }
 /** Request/response over one client. Create with {@link createWebSocketRequests}. */
@@ -517,7 +533,26 @@ interface WebSocketRequests<Req, In> {
    * queue (replaced by a newer request with the same `key`, or evicted by `queue.limit`).
    */
   request(message: Req, options?: RequestOptions): Promise<In>;
-  /** Number of requests waiting for a reply. */
+  /**
+   * Send a request and iterate over its replies, up to and including the one `done` matches.
+   * Holds the connection until the stream ends. Needs the `done` option.
+   *
+   * `timeout` is the time to wait for each reply. Replies that arrive before the loop reads
+   * them are buffered. The stream is one-shot: iterate it once.
+   *
+   * Fails where `request()` rejects, with the same errors, after yielding the replies already
+   * received. Aborting `signal` throws `signal.reason` right away and discards them. Leaving
+   * the loop early, aborting and timing out send `cancel`.
+   *
+   * @example
+   * ```ts
+   * for await (const reply of rpc.stream({ type: 'ask', prompt }, { signal })) {
+   *   text += reply.delta;
+   * }
+   * ```
+   */
+  stream(message: Req, options?: RequestOptions): AsyncIterableIterator<In>;
+  /** Number of requests and streams waiting for a reply. */
   pending(): number;
   /** Reject every pending request and stop listening. Only needed for managers created dynamically. */
   dispose(): void;

package/dist/core.js

@@ -659,6 +659,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.
 *
@@ -679,8 +681,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) => {
@@ -688,78 +690,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);
 		}
 	};
 }