react-websocket 3.0.0 → 3.2.0

package/README.md

@@ -13,9 +13,12 @@
 
 - **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.
-- **Send queue.** `send()` before the socket is open just works. The message goes out on connect.
+- **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.
 - **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.
+- **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.
 - **SSR-safe.** Never connects during a server render, hydrates cleanly, and ships a `'use client'` entry for Next.js and other Server Components frameworks.
 - **Small and typed.** Zero dependencies, ESM + CJS, TypeScript declarations with inline docs, plus a React-free `react-websocket/core` entry.
 
@@ -108,7 +111,14 @@ function Room() {
 | `useWebSocket(url \| client, options?)` | Connect; returns `{ status, lastMessage, attempt, send, close, reconnect, client }` |
 | `useWebSocketEvent(client, type, listener)` | Handle `'open'`, `'message'`, `'close'` or `'error'` without re-rendering |
 | `useWebSocketStatus(client)` | The status; re-renders only when it changes |
+| `useWebSocketTopic(topics, topic)` | Hold topic subscriptions that survive reconnects |
+| `useWebSocketState(store, selector?)` | Read state reduced from messages; re-renders only when the selection changes |
+| `useWebSocketLatency(latency)` | Round-trip time and server clock offset |
 | `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 |
+| `createWebSocketLatency(client, { ping, pong })` | Ping tracker for `useWebSocketLatency`, plus `serverNow()` |
 | `MessageError` | Reported to `onError` when a message fails `parse` or `schema` |
 
 | Option | Default | |
@@ -130,7 +140,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) · [Testing](https://mehmetkose.github.io/react-websocket/guide/testing) · [Without React](https://mehmetkose.github.io/react-websocket/guide/without-react)
+- [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) · [Testing](https://mehmetkose.github.io/react-websocket/guide/testing) · [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)
 
 The docs source lives in [`docs/`](docs). Run `npm run docs:dev` to browse it locally.

package/dist/core.cjs

@@ -21,7 +21,11 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var core_exports = {};
 __export(core_exports, {
   MessageError: () => MessageError,
-  createWebSocket: () => createWebSocket
+  createWebSocket: () => createWebSocket,
+  createWebSocketLatency: () => createWebSocketLatency,
+  createWebSocketRequests: () => createWebSocketRequests,
+  createWebSocketState: () => createWebSocketState,
+  createWebSocketTopics: () => createWebSocketTopics
 });
 module.exports = __toCommonJS(core_exports);
 
@@ -247,7 +251,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);
@@ -343,13 +347,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;
     }
@@ -357,7 +361,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`);
@@ -489,9 +495,289 @@ function createClient(url, options = {}) {
 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;
+  let state = initialState;
+  const listeners = /* @__PURE__ */ new Set();
+  function setState(update) {
+    const next = typeof update === "function" ? update(state) : update;
+    if (Object.is(next, state)) return;
+    state = next;
+    for (const listener of [...listeners]) listener();
+  }
+  const off = client.on("message", (message) => setState((current) => reduce(current, message)));
+  return {
+    client,
+    initialState,
+    getState: () => state,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    setState,
+    reset: () => setState(initialState),
+    dispose: off
+  };
+}
+
+// src/topics.ts
+function createWebSocketTopics(client, options) {
+  const counts = /* @__PURE__ */ new Map();
+  const pendingRemoval = /* @__PURE__ */ new Map();
+  let sentOn = null;
+  let sent = /* @__PURE__ */ new Set();
+  function isOpen() {
+    return client.getSnapshot().status === "open" && client.socket !== null;
+  }
+  function subscribe(topic) {
+    if (!isOpen()) return;
+    if (client.socket !== sentOn) {
+      sentOn = client.socket;
+      sent = /* @__PURE__ */ new Set();
+    }
+    if (sent.has(topic)) return;
+    sent.add(topic);
+    client.send(options.subscribe(topic));
+  }
+  function unsubscribe(topic) {
+    if (!isOpen() || client.socket !== sentOn || !sent.delete(topic)) return;
+    if (options.unsubscribe) client.send(options.unsubscribe(topic));
+  }
+  const off = client.on("open", () => {
+    sentOn = client.socket;
+    sent = /* @__PURE__ */ new Set();
+    for (const topic of counts.keys()) subscribe(topic);
+  });
+  return {
+    client,
+    acquire(topic) {
+      const releaseConnection = client.acquire();
+      clearTimeout(pendingRemoval.get(topic));
+      pendingRemoval.delete(topic);
+      counts.set(topic, (counts.get(topic) ?? 0) + 1);
+      subscribe(topic);
+      let released = false;
+      return () => {
+        if (released) return;
+        released = true;
+        const remaining = (counts.get(topic) ?? 1) - 1;
+        if (remaining > 0) {
+          counts.set(topic, remaining);
+        } else {
+          counts.delete(topic);
+          pendingRemoval.set(
+            topic,
+            setTimeout(() => {
+              pendingRemoval.delete(topic);
+              if (!counts.has(topic)) unsubscribe(topic);
+            }, 0)
+          );
+        }
+        releaseConnection();
+      };
+    },
+    active: () => [...counts.keys()],
+    dispose() {
+      off();
+      for (const timer of pendingRemoval.values()) clearTimeout(timer);
+      pendingRemoval.clear();
+    }
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   MessageError,
-  createWebSocket
+  createWebSocket,
+  createWebSocketLatency,
+  createWebSocketRequests,
+  createWebSocketState,
+  createWebSocketTopics
 });
 //# sourceMappingURL=core.cjs.map