react-websocket 3.1.0 → 3.2.0

package/dist/core.d.cts

@@ -100,6 +100,21 @@ interface HeartbeatOptions {
      */
     timeout?: number;
 }
+/** Per-message options for `send()`. */
+interface SendOptions {
+    /**
+     * Drop the message instead of queueing it when the socket isn't open. For data that
+     * is stale by the time a reconnect finishes, such as player input or cursor positions.
+     * @default false
+     */
+    volatile?: boolean;
+    /**
+     * Keep only the newest queued message with this key. Sending again with the same key
+     * while disconnected replaces the earlier one, which moves to the back of the queue.
+     * For state where only the latest value matters, such as "my position is now (x, y)".
+     */
+    key?: string;
+}
 /** Bounds for the send queue. */
 interface QueueOptions {
     /**
@@ -285,10 +300,17 @@ interface WebSocketClient<In = unknown, Out = unknown> {
     on<K extends keyof EventMap<In>>(type: K, listener: EventMap<In>[K]): () => void;
     /**
      * Send a message (encoded with `serialize`/`json` if configured). If the socket isn't
-     * open, the message is queued and sent on open (see the `queue` option).
+     * open, the message is queued and sent on open (see the `queue` option), unless
+     * `options.volatile` is set.
      * @returns `true` if it was sent immediately, `false` if it was queued or dropped.
+     *
+     * @example
+     * ```ts
+     * game.send({ type: 'input', dx, dy }, { volatile: true }); // never replayed after a reconnect
+     * game.send({ type: 'position', x, y }, { key: 'position' }); // only the newest is queued
+     * ```
      */
-    send(message: Out): boolean;
+    send(message: Out, options?: SendOptions): boolean;
     /**
      * Start connecting, and keep the connection open even when no hook is using the
      * client, until `close()` is called. Does nothing if already connecting or open.
@@ -335,6 +357,150 @@ interface WebSocketClient<In = unknown, Out = unknown> {
  */
 declare function createWebSocket<In = unknown, Out = unknown>(url: UrlSource, options?: WebSocketOptions<In, Out>): WebSocketClient<In, Out>;
 
+/** Options for {@link createWebSocketLatency}: how pings and pongs look on the wire. */
+interface WebSocketLatencyOptions<In, Out> {
+    /** The ping message, tagged with `id`. Sent with `volatile`, so pings are never queued. */
+    ping: (id: number) => Out;
+    /**
+     * Recognize a pong: return the `id` of the ping it answers, and the server's clock
+     * (`Date.now()` on the server, in ms) when it replied. Return `undefined` (or `null`)
+     * for any other message. Without `time`, only the round-trip time is measured.
+     */
+    pong: (message: In) => {
+        id: number | string;
+        time?: number;
+    } | null | undefined;
+    /**
+     * How often to ping while open, in ms. The first ping goes out as soon as the socket opens.
+     * @default 2000
+     */
+    interval?: number;
+    /**
+     * How many recent measurements to keep. `rtt` is their median, and `offset` comes from
+     * the one with the lowest round trip, the most accurate estimate.
+     * @default 5
+     */
+    samples?: number;
+}
+/** Latest latency measurements. A new object is created on every change. */
+interface Latency {
+    /** Round-trip time in ms: the median of recent pings. `undefined` until the first pong. */
+    readonly rtt: number | undefined;
+    /**
+     * Estimated server clock minus local clock, in ms. Add it to `Date.now()` for server time.
+     * `undefined` until a pong carries `time`.
+     */
+    readonly offset: number | undefined;
+}
+/** Round-trip time and server clock offset for one client. Create with {@link createWebSocketLatency}. */
+interface WebSocketLatency {
+    /** The client being measured. Hooks reading the latency keep it connected. */
+    readonly client: WebSocketClient<any, any>;
+    /** The current {@link Latency}. Returns the same object until it changes. */
+    getSnapshot(): Latency;
+    /** Called whenever a measurement changes. Compatible with `useSyncExternalStore`. */
+    subscribe(listener: () => void): () => void;
+    /** The estimated server time: `Date.now() + offset`, or `Date.now()` before any estimate. */
+    serverNow(): number;
+    /** Ping now instead of waiting for the next interval. Does nothing unless the socket is open. */
+    ping(): void;
+    /** Stop pinging and listening. Only needed for instances created dynamically. */
+    dispose(): void;
+}
+/**
+ * Measure round-trip time and estimate the server's clock, for ping displays, countdowns
+ * and timestamps that must agree across players.
+ *
+ * Pings are sent on an interval while the socket is open, and paused otherwise. Measurements
+ * from a previous connection are discarded on reconnect, but the last values stay readable
+ * until new ones arrive. It doesn't open the connection by itself.
+ *
+ * Pongs are ordinary messages: they also reach `onMessage`, `lastMessage` and state stores.
+ *
+ * @example
+ * ```ts
+ * export const latency = createWebSocketLatency(game, {
+ *   ping: id => ({ type: 'ping', id }),
+ *   pong: message => (message.type === 'pong' ? { id: message.id, time: message.time } : undefined)
+ * });
+ *
+ * // In a component:
+ * const { rtt } = useWebSocketLatency(latency);
+ *
+ * // Anywhere: seconds left in a round that ends at the server's `endsAt`.
+ * const left = (endsAt - latency.serverNow()) / 1000;
+ * ```
+ */
+declare function createWebSocketLatency<In, const Out>(client: WebSocketClient<In, Out>, options: WebSocketLatencyOptions<NoInfer<In>, NoInfer<Out>>): WebSocketLatency;
+
+/** Options for {@link createWebSocketRequests}: how requests and replies look on the wire. */
+interface WebSocketRequestsOptions<Req, In, Out> {
+    /**
+     * Build the outgoing message for `request(message)`, tagged with `id`. Annotate `message`
+     * to type what `request()` accepts.
+     */
+    send: (message: Req, id: number) => Out;
+    /**
+     * The id an incoming message replies to, or `undefined` (or `null`) if it isn't a reply.
+     * A string id matches the number it was sent as, so either echo works.
+     */
+    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.
+     */
+    error?: (message: In) => unknown;
+    /**
+     * Default time to wait for a reply, in ms. `Infinity` waits forever.
+     * @default 10000
+     */
+    timeout?: number;
+}
+/** Per-call options for {@link WebSocketRequests.request}. */
+interface RequestOptions extends SendOptions {
+    /** Time to wait for a reply, in ms. Overrides the manager's `timeout`. */
+    timeout?: number;
+    /** Abort the request. It rejects with `signal.reason`. A late reply is ignored. */
+    signal?: AbortSignal;
+}
+/** Request/response over one client. Create with {@link createWebSocketRequests}. */
+interface WebSocketRequests<Req, In> {
+    /** The client requests are sent on. */
+    readonly client: WebSocketClient<any, any>;
+    /**
+     * Send a request and resolve with its reply. Holds the connection until it settles.
+     *
+     * Rejects with a `TimeoutError` `DOMException` after `timeout`, with `signal.reason` when
+     * aborted, and with an `Error` when the connection it was sent on closes (the reply can
+     * no longer arrive) or the client stops. A request made while disconnected is queued like
+     * any other message and waits for the connection.
+     */
+    request(message: Req, options?: RequestOptions): Promise<In>;
+    /** Number of requests waiting for a reply. */
+    pending(): number;
+    /** Reject every pending request and stop listening. Only needed for managers created dynamically. */
+    dispose(): void;
+}
+/**
+ * Send requests and await their replies, matched by an id the library generates.
+ *
+ * Replies are ordinary messages: they also reach `onMessage`, `lastMessage` and state stores.
+ *
+ * @example
+ * ```ts
+ * type Request = { type: 'join'; room: string } | { type: 'leave' };
+ *
+ * export const rpc = createWebSocketRequests(game, {
+ *   send: (message: Request, id) => ({ ...message, id }),
+ *   reply: message => (message.type === 'reply' ? message.id : undefined),
+ *   error: message => (message.type === 'reply' && message.error ? new Error(message.error) : undefined)
+ * });
+ *
+ * const reply = await rpc.request({ type: 'join', room: 'lobby' }, { timeout: 5000 });
+ * ```
+ */
+declare function createWebSocketRequests<Req, In, const Out>(client: WebSocketClient<In, Out>, options: WebSocketRequestsOptions<Req, NoInfer<In>, NoInfer<Out>>): WebSocketRequests<Req, In>;
+
 /** Options for {@link createWebSocketState}. */
 interface WebSocketStateOptions<S, In> {
     /** The state before any message arrives, and what `reset()` returns to. */
@@ -432,4 +598,4 @@ interface WebSocketTopics {
  */
 declare function createWebSocketTopics<const Out>(client: WebSocketClient<any, Out>, options: WebSocketTopicsOptions<NoInfer<Out>>): WebSocketTopics;
 
-export { type CloseInfo, type EventMap, type HeartbeatOptions, MessageError, type QueueOptions, type ReconnectOptions, type SendData, type Snapshot, type StandardSchemaV1, type Status, type UrlSource, type WebSocketClient, type WebSocketOptions, type WebSocketState, type WebSocketStateOptions, type WebSocketTopics, type WebSocketTopicsOptions, createWebSocket, createWebSocketState, createWebSocketTopics };
+export { type CloseInfo, type EventMap, type HeartbeatOptions, type Latency, MessageError, type QueueOptions, type ReconnectOptions, type RequestOptions, type SendData, type SendOptions, type Snapshot, type StandardSchemaV1, type Status, type UrlSource, type WebSocketClient, type WebSocketLatency, type WebSocketLatencyOptions, type WebSocketOptions, type WebSocketRequests, type WebSocketRequestsOptions, type WebSocketState, type WebSocketStateOptions, type WebSocketTopics, type WebSocketTopicsOptions, createWebSocket, createWebSocketLatency, createWebSocketRequests, createWebSocketState, createWebSocketTopics };

package/dist/core.d.ts

@@ -100,6 +100,21 @@ interface HeartbeatOptions {
      */
     timeout?: number;
 }
+/** Per-message options for `send()`. */
+interface SendOptions {
+    /**
+     * Drop the message instead of queueing it when the socket isn't open. For data that
+     * is stale by the time a reconnect finishes, such as player input or cursor positions.
+     * @default false
+     */
+    volatile?: boolean;
+    /**
+     * Keep only the newest queued message with this key. Sending again with the same key
+     * while disconnected replaces the earlier one, which moves to the back of the queue.
+     * For state where only the latest value matters, such as "my position is now (x, y)".
+     */
+    key?: string;
+}
 /** Bounds for the send queue. */
 interface QueueOptions {
     /**
@@ -285,10 +300,17 @@ interface WebSocketClient<In = unknown, Out = unknown> {
     on<K extends keyof EventMap<In>>(type: K, listener: EventMap<In>[K]): () => void;
     /**
      * Send a message (encoded with `serialize`/`json` if configured). If the socket isn't
-     * open, the message is queued and sent on open (see the `queue` option).
+     * open, the message is queued and sent on open (see the `queue` option), unless
+     * `options.volatile` is set.
      * @returns `true` if it was sent immediately, `false` if it was queued or dropped.
+     *
+     * @example
+     * ```ts
+     * game.send({ type: 'input', dx, dy }, { volatile: true }); // never replayed after a reconnect
+     * game.send({ type: 'position', x, y }, { key: 'position' }); // only the newest is queued
+     * ```
      */
-    send(message: Out): boolean;
+    send(message: Out, options?: SendOptions): boolean;
     /**
      * Start connecting, and keep the connection open even when no hook is using the
      * client, until `close()` is called. Does nothing if already connecting or open.
@@ -335,6 +357,150 @@ interface WebSocketClient<In = unknown, Out = unknown> {
  */
 declare function createWebSocket<In = unknown, Out = unknown>(url: UrlSource, options?: WebSocketOptions<In, Out>): WebSocketClient<In, Out>;
 
+/** Options for {@link createWebSocketLatency}: how pings and pongs look on the wire. */
+interface WebSocketLatencyOptions<In, Out> {
+    /** The ping message, tagged with `id`. Sent with `volatile`, so pings are never queued. */
+    ping: (id: number) => Out;
+    /**
+     * Recognize a pong: return the `id` of the ping it answers, and the server's clock
+     * (`Date.now()` on the server, in ms) when it replied. Return `undefined` (or `null`)
+     * for any other message. Without `time`, only the round-trip time is measured.
+     */
+    pong: (message: In) => {
+        id: number | string;
+        time?: number;
+    } | null | undefined;
+    /**
+     * How often to ping while open, in ms. The first ping goes out as soon as the socket opens.
+     * @default 2000
+     */
+    interval?: number;
+    /**
+     * How many recent measurements to keep. `rtt` is their median, and `offset` comes from
+     * the one with the lowest round trip, the most accurate estimate.
+     * @default 5
+     */
+    samples?: number;
+}
+/** Latest latency measurements. A new object is created on every change. */
+interface Latency {
+    /** Round-trip time in ms: the median of recent pings. `undefined` until the first pong. */
+    readonly rtt: number | undefined;
+    /**
+     * Estimated server clock minus local clock, in ms. Add it to `Date.now()` for server time.
+     * `undefined` until a pong carries `time`.
+     */
+    readonly offset: number | undefined;
+}
+/** Round-trip time and server clock offset for one client. Create with {@link createWebSocketLatency}. */
+interface WebSocketLatency {
+    /** The client being measured. Hooks reading the latency keep it connected. */
+    readonly client: WebSocketClient<any, any>;
+    /** The current {@link Latency}. Returns the same object until it changes. */
+    getSnapshot(): Latency;
+    /** Called whenever a measurement changes. Compatible with `useSyncExternalStore`. */
+    subscribe(listener: () => void): () => void;
+    /** The estimated server time: `Date.now() + offset`, or `Date.now()` before any estimate. */
+    serverNow(): number;
+    /** Ping now instead of waiting for the next interval. Does nothing unless the socket is open. */
+    ping(): void;
+    /** Stop pinging and listening. Only needed for instances created dynamically. */
+    dispose(): void;
+}
+/**
+ * Measure round-trip time and estimate the server's clock, for ping displays, countdowns
+ * and timestamps that must agree across players.
+ *
+ * Pings are sent on an interval while the socket is open, and paused otherwise. Measurements
+ * from a previous connection are discarded on reconnect, but the last values stay readable
+ * until new ones arrive. It doesn't open the connection by itself.
+ *
+ * Pongs are ordinary messages: they also reach `onMessage`, `lastMessage` and state stores.
+ *
+ * @example
+ * ```ts
+ * export const latency = createWebSocketLatency(game, {
+ *   ping: id => ({ type: 'ping', id }),
+ *   pong: message => (message.type === 'pong' ? { id: message.id, time: message.time } : undefined)
+ * });
+ *
+ * // In a component:
+ * const { rtt } = useWebSocketLatency(latency);
+ *
+ * // Anywhere: seconds left in a round that ends at the server's `endsAt`.
+ * const left = (endsAt - latency.serverNow()) / 1000;
+ * ```
+ */
+declare function createWebSocketLatency<In, const Out>(client: WebSocketClient<In, Out>, options: WebSocketLatencyOptions<NoInfer<In>, NoInfer<Out>>): WebSocketLatency;
+
+/** Options for {@link createWebSocketRequests}: how requests and replies look on the wire. */
+interface WebSocketRequestsOptions<Req, In, Out> {
+    /**
+     * Build the outgoing message for `request(message)`, tagged with `id`. Annotate `message`
+     * to type what `request()` accepts.
+     */
+    send: (message: Req, id: number) => Out;
+    /**
+     * The id an incoming message replies to, or `undefined` (or `null`) if it isn't a reply.
+     * A string id matches the number it was sent as, so either echo works.
+     */
+    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.
+     */
+    error?: (message: In) => unknown;
+    /**
+     * Default time to wait for a reply, in ms. `Infinity` waits forever.
+     * @default 10000
+     */
+    timeout?: number;
+}
+/** Per-call options for {@link WebSocketRequests.request}. */
+interface RequestOptions extends SendOptions {
+    /** Time to wait for a reply, in ms. Overrides the manager's `timeout`. */
+    timeout?: number;
+    /** Abort the request. It rejects with `signal.reason`. A late reply is ignored. */
+    signal?: AbortSignal;
+}
+/** Request/response over one client. Create with {@link createWebSocketRequests}. */
+interface WebSocketRequests<Req, In> {
+    /** The client requests are sent on. */
+    readonly client: WebSocketClient<any, any>;
+    /**
+     * Send a request and resolve with its reply. Holds the connection until it settles.
+     *
+     * Rejects with a `TimeoutError` `DOMException` after `timeout`, with `signal.reason` when
+     * aborted, and with an `Error` when the connection it was sent on closes (the reply can
+     * no longer arrive) or the client stops. A request made while disconnected is queued like
+     * any other message and waits for the connection.
+     */
+    request(message: Req, options?: RequestOptions): Promise<In>;
+    /** Number of requests waiting for a reply. */
+    pending(): number;
+    /** Reject every pending request and stop listening. Only needed for managers created dynamically. */
+    dispose(): void;
+}
+/**
+ * Send requests and await their replies, matched by an id the library generates.
+ *
+ * Replies are ordinary messages: they also reach `onMessage`, `lastMessage` and state stores.
+ *
+ * @example
+ * ```ts
+ * type Request = { type: 'join'; room: string } | { type: 'leave' };
+ *
+ * export const rpc = createWebSocketRequests(game, {
+ *   send: (message: Request, id) => ({ ...message, id }),
+ *   reply: message => (message.type === 'reply' ? message.id : undefined),
+ *   error: message => (message.type === 'reply' && message.error ? new Error(message.error) : undefined)
+ * });
+ *
+ * const reply = await rpc.request({ type: 'join', room: 'lobby' }, { timeout: 5000 });
+ * ```
+ */
+declare function createWebSocketRequests<Req, In, const Out>(client: WebSocketClient<In, Out>, options: WebSocketRequestsOptions<Req, NoInfer<In>, NoInfer<Out>>): WebSocketRequests<Req, In>;
+
 /** Options for {@link createWebSocketState}. */
 interface WebSocketStateOptions<S, In> {
     /** The state before any message arrives, and what `reset()` returns to. */
@@ -432,4 +598,4 @@ interface WebSocketTopics {
  */
 declare function createWebSocketTopics<const Out>(client: WebSocketClient<any, Out>, options: WebSocketTopicsOptions<NoInfer<Out>>): WebSocketTopics;
 
-export { type CloseInfo, type EventMap, type HeartbeatOptions, MessageError, type QueueOptions, type ReconnectOptions, type SendData, type Snapshot, type StandardSchemaV1, type Status, type UrlSource, type WebSocketClient, type WebSocketOptions, type WebSocketState, type WebSocketStateOptions, type WebSocketTopics, type WebSocketTopicsOptions, createWebSocket, createWebSocketState, createWebSocketTopics };
+export { type CloseInfo, type EventMap, type HeartbeatOptions, type Latency, MessageError, type QueueOptions, type ReconnectOptions, type RequestOptions, type SendData, type SendOptions, type Snapshot, type StandardSchemaV1, type Status, type UrlSource, type WebSocketClient, type WebSocketLatency, type WebSocketLatencyOptions, type WebSocketOptions, type WebSocketRequests, type WebSocketRequestsOptions, type WebSocketState, type WebSocketStateOptions, type WebSocketTopics, type WebSocketTopicsOptions, createWebSocket, createWebSocketLatency, createWebSocketRequests, createWebSocketState, createWebSocketTopics };

package/dist/core.js

@@ -220,7 +220,7 @@ function createClient(url, options = {}) {
       if (ws !== socket) return;
       const queued = pending;
       pending = [];
-      for (const data of queued) socket.send(data);
+      for (const { data } of queued) socket.send(data);
     };
     socket.onmessage = (event) => receive(event, socket);
     socket.onerror = (event) => emit("error", event);
@@ -316,13 +316,13 @@ function createClient(url, options = {}) {
     set({ lastMessage: message });
     emit("message", message, event);
   }
-  function send(message) {
+  function send(message, sendOptions) {
     const data = options.serialize ? options.serialize(message) : options.json ? JSON.stringify(message) : message;
     if (ws && ws.readyState === OPEN) {
       ws.send(data);
       return true;
     }
-    if (queueLimit === 0) {
+    if (queueLimit === 0 || sendOptions?.volatile) {
       log("dropped message: socket is not open");
       return false;
     }
@@ -330,7 +330,9 @@ function createClient(url, options = {}) {
       log("dropped message: no WebSocket implementation available");
       return false;
     }
-    pending.push(data);
+    const key = sendOptions?.key;
+    if (key !== void 0) pending = pending.filter((entry) => entry.key !== key);
+    pending.push({ data, key });
     if (pending.length > queueLimit) {
       pending.shift();
       log(`dropped oldest queued message: queue limit (${queueLimit}) reached`);
@@ -463,6 +465,189 @@ function createWebSocket(url, options) {
   return createClient(url, options);
 }
 
+// src/latency.ts
+var EMPTY = Object.freeze({ rtt: void 0, offset: void 0 });
+function median(values) {
+  const sorted = [...values].sort((a, b) => a - b);
+  const middle = sorted.length >> 1;
+  return sorted.length % 2 ? sorted[middle] : (sorted[middle - 1] + sorted[middle]) / 2;
+}
+function createWebSocketLatency(client, options) {
+  const interval = options.interval ?? 2e3;
+  const keep = Math.max(1, options.samples ?? 5);
+  const listeners = /* @__PURE__ */ new Set();
+  let snapshot = EMPTY;
+  const inFlight = /* @__PURE__ */ new Map();
+  let samples = [];
+  let nextId = 0;
+  let timer;
+  function ping() {
+    if (client.getSnapshot().status !== "open") return;
+    const id = ++nextId;
+    inFlight.set(String(id), performance.now());
+    if (inFlight.size > keep * 2) inFlight.delete(inFlight.keys().next().value);
+    client.send(options.ping(id), { volatile: true });
+  }
+  function start() {
+    stop();
+    inFlight.clear();
+    samples = [];
+    ping();
+    timer = setInterval(ping, interval);
+  }
+  function stop() {
+    clearInterval(timer);
+    timer = void 0;
+  }
+  function measure(id, serverTime) {
+    const sentAt = inFlight.get(id);
+    if (sentAt === void 0) return;
+    inFlight.delete(id);
+    const rtt = performance.now() - sentAt;
+    const offset = serverTime === void 0 ? void 0 : serverTime + rtt / 2 - Date.now();
+    samples.push({ rtt, offset });
+    if (samples.length > keep) samples.shift();
+    let best;
+    for (const sample of samples) {
+      if (sample.offset !== void 0 && (!best || sample.rtt < best.rtt)) best = sample;
+    }
+    snapshot = {
+      rtt: median(samples.map((sample) => sample.rtt)),
+      offset: best ? best.offset : snapshot.offset
+    };
+    for (const listener of [...listeners]) listener();
+  }
+  const offs = [
+    client.on("open", start),
+    client.on("message", (message) => {
+      const pong = options.pong(message);
+      if (pong != null) measure(String(pong.id), pong.time);
+    }),
+    client.subscribe(() => {
+      if (client.getSnapshot().status !== "open") stop();
+    })
+  ];
+  if (client.getSnapshot().status === "open") start();
+  return {
+    client,
+    getSnapshot: () => snapshot,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    serverNow: () => Date.now() + (snapshot.offset ?? 0),
+    ping,
+    dispose() {
+      stop();
+      offs.forEach((off) => off());
+    }
+  };
+}
+
+// src/requests.ts
+function createWebSocketRequests(client, options) {
+  const waiting = /* @__PURE__ */ new Map();
+  let nextId = 0;
+  function rejectWhere(test, reason) {
+    for (const entry of [...waiting.values()]) if (test(entry)) entry.reject(reason());
+  }
+  const offs = [
+    client.on("message", (message) => {
+      const id = options.reply(message);
+      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);
+    }),
+    // `open` listeners run before the client flushes its queue: queued requests go out on this socket.
+    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,
+          () => new Error("WebSocket was closed before the request was answered")
+        );
+      } else {
+        rejectWhere(
+          (entry) => entry.socket !== null && entry.socket !== client.socket,
+          () => new Error("WebSocket connection was lost before the request was answered")
+        );
+      }
+    })
+  ];
+  return {
+    client,
+    request(message, requestOptions = {}) {
+      const { signal } = requestOptions;
+      if (signal?.aborted) return Promise.reject(signal.reason);
+      const id = ++nextId;
+      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(new Error(`WebSocket is ${status}: request not sent`));
+          return;
+        }
+        let sent;
+        try {
+          sent = client.send(options.send(message, id), requestOptions);
+        } catch (error) {
+          entry.reject(error);
+          return;
+        }
+        if (sent) entry.socket = client.socket;
+        else if (requestOptions.volatile)
+          entry.reject(new Error("WebSocket is not open: request dropped"));
+      });
+    },
+    pending: () => waiting.size,
+    dispose() {
+      offs.forEach((off) => off());
+      rejectWhere(
+        () => true,
+        () => new Error("Requests were disposed")
+      );
+    }
+  };
+}
+
 // src/state.ts
 function createWebSocketState(client, options) {
   const { initialState, reduce } = options;
@@ -558,6 +743,8 @@ function createWebSocketTopics(client, options) {
 export {
   MessageError,
   createWebSocket,
+  createWebSocketLatency,
+  createWebSocketRequests,
   createWebSocketState,
   createWebSocketTopics
 };