react-realtime-hooks 1.3.3 → 1.4.0

package/README.md

@@ -257,6 +257,21 @@ export function ChatSocket() {
 }
 ```
 
+The native `WebSocket` does not emit any event when buffered bytes drain to the network, so by default `bufferedAmount` only refreshes on `send()`, on incoming messages, and on the `open` transition. Pass `bufferedAmountPolling` to surface the live value for backpressure indicators:
+
+```tsx
+const socket = useWebSocket<IncomingMessage, OutgoingMessage>({
+  url: "ws://localhost:8080",
+  // "raf" reads `bufferedAmount` on every animation frame while open;
+  // use `true` for a 100ms interval, or `{ intervalMs: 50 }` for custom.
+  bufferedAmountPolling: "raf",
+});
+
+// `socket.bufferedAmount` now ticks down as the OS flushes the buffer,
+// even between `send` calls. Identical readings do not trigger React
+// re-renders.
+```
+
 ### `useEventSource`
 
 ```tsx
@@ -400,6 +415,7 @@ export function GatedNotifications() {
 | `protocols`        | `string \| string[]`           | `undefined`                | WebSocket subprotocols             |
 | `connect`          | `boolean`                      | `true`                     | Auto-connect on mount              |
 | `binaryType`       | `BinaryType`                   | `"blob"`                   | Socket binary mode                 |
+| `bufferedAmountPolling` | `false \| true \| "raf" \| { intervalMs: number }` | `false` | Live polling of `WebSocket.bufferedAmount` for backpressure UIs |
 | `parseMessage`     | `(event) => TIncoming`         | raw `event.data`           | Incoming parser                    |
 | `serializeMessage` | `(message) => ...`             | JSON/string passthrough    | Outgoing serializer                |
 | `reconnect`        | `false \| UseReconnectOptions` | enabled                    | Reconnect configuration            |
@@ -420,7 +436,7 @@ export function GatedNotifications() {
 | `lastMessageEvent` | `MessageEvent \| null`       | Last raw message event                                                     |
 | `lastCloseEvent`   | `CloseEvent \| null`         | Last close event                                                           |
 | `lastError`        | `Event \| null`              | Last transport error, or `RealtimeErrorEvent` for parse/heartbeat failures |
-| `bufferedAmount`   | `number`                     | Current socket buffer size                                                 |
+| `bufferedAmount`   | `number`                     | Current socket buffer size (refresh cadence is controlled by `bufferedAmountPolling`) |
 | `reconnectState`   | reconnect snapshot or `null` | Current reconnect data                                                     |
 | `heartbeatState`   | heartbeat snapshot or `null` | Current heartbeat data                                                     |
 | `open`             | `() => void`                 | Manual connect                                                             |

package/dist/index.cjs

@@ -1222,47 +1222,62 @@ var useWebSocket = (options) => {
     if (socketRef.current !== null) {
       return;
     }
-    const socket2 = new WebSocket(resolvedUrl, protocols);
-    const socketEpoch = nextSocketEpochRef.current + 1;
-    socketRef.current = socket2;
-    socketKeyRef.current = nextSocketKey;
-    activeSocketEpochRef.current = socketEpoch;
-    closingSocketEpochRef.current = null;
-    nextSocketEpochRef.current = socketEpoch;
-    socket2.binaryType = options.binaryType ?? "blob";
     commitState((current) => ({
       ...current,
-      bufferedAmount: socket2.bufferedAmount,
+      bufferedAmount: 0,
       lastChangedAt: Date.now(),
       status: reconnect.status === "running" || reconnect.status === "scheduled" ? "reconnecting" : "connecting"
     }));
-    const handleSocketOpen = (event) => {
-      if (!isActiveSocketEvent(socketEpoch)) {
-        return;
-      }
-      handleOpen(event, socket2);
-    };
-    const handleSocketMessage = (event) => {
-      if (!isActiveSocketEvent(socketEpoch)) {
+    let cancelled = false;
+    let detachListeners = null;
+    queueMicrotask(() => {
+      if (cancelled) {
         return;
       }
-      handleMessage(event);
-    };
-    const handleSocketError = (event) => {
-      handleError(event, socketEpoch);
-    };
-    const handleSocketClose = (event) => {
-      handleClose(event, socketEpoch);
-    };
-    socket2.addEventListener("open", handleSocketOpen);
-    socket2.addEventListener("message", handleSocketMessage);
-    socket2.addEventListener("error", handleSocketError);
-    socket2.addEventListener("close", handleSocketClose);
+      const socket2 = new WebSocket(resolvedUrl, protocols);
+      const socketEpoch = nextSocketEpochRef.current + 1;
+      socketRef.current = socket2;
+      socketKeyRef.current = nextSocketKey;
+      activeSocketEpochRef.current = socketEpoch;
+      closingSocketEpochRef.current = null;
+      nextSocketEpochRef.current = socketEpoch;
+      socket2.binaryType = options.binaryType ?? "blob";
+      commitState((current) => ({
+        ...current,
+        bufferedAmount: socket2.bufferedAmount
+      }));
+      const handleSocketOpen = (event) => {
+        if (!isActiveSocketEvent(socketEpoch)) {
+          return;
+        }
+        handleOpen(event, socket2);
+      };
+      const handleSocketMessage = (event) => {
+        if (!isActiveSocketEvent(socketEpoch)) {
+          return;
+        }
+        handleMessage(event);
+      };
+      const handleSocketError = (event) => {
+        handleError(event, socketEpoch);
+      };
+      const handleSocketClose = (event) => {
+        handleClose(event, socketEpoch);
+      };
+      socket2.addEventListener("open", handleSocketOpen);
+      socket2.addEventListener("message", handleSocketMessage);
+      socket2.addEventListener("error", handleSocketError);
+      socket2.addEventListener("close", handleSocketClose);
+      detachListeners = () => {
+        socket2.removeEventListener("open", handleSocketOpen);
+        socket2.removeEventListener("message", handleSocketMessage);
+        socket2.removeEventListener("error", handleSocketError);
+        socket2.removeEventListener("close", handleSocketClose);
+      };
+    });
     return () => {
-      socket2.removeEventListener("open", handleSocketOpen);
-      socket2.removeEventListener("message", handleSocketMessage);
-      socket2.removeEventListener("error", handleSocketError);
-      socket2.removeEventListener("close", handleSocketClose);
+      cancelled = true;
+      detachListeners?.();
     };
   }, [
     closeSocket,
@@ -1302,6 +1317,58 @@ var useWebSocket = (options) => {
       stopHeartbeat();
     }
   }, [state.status, stopHeartbeat]);
+  const rawBufferedAmountPolling = options.bufferedAmountPolling;
+  const bufferedAmountPollingMode = react.useMemo(() => {
+    if (rawBufferedAmountPolling === void 0 || rawBufferedAmountPolling === false) {
+      return null;
+    }
+    if (rawBufferedAmountPolling === true) {
+      return 100;
+    }
+    if (rawBufferedAmountPolling === "raf") {
+      return "raf";
+    }
+    const intervalMs = rawBufferedAmountPolling.intervalMs;
+    return Number.isFinite(intervalMs) && intervalMs > 0 ? intervalMs : null;
+  }, [rawBufferedAmountPolling]);
+  const pollBufferedAmount = useStableCallback(() => {
+    const socket2 = socketRef.current;
+    if (socket2 === null) {
+      return;
+    }
+    const next = socket2.bufferedAmount;
+    if (stateRef.current.bufferedAmount === next) {
+      return;
+    }
+    commitState((current) => ({
+      ...current,
+      bufferedAmount: next
+    }));
+  });
+  react.useEffect(() => {
+    if (bufferedAmountPollingMode === null) {
+      return;
+    }
+    if (state.status !== "open") {
+      return;
+    }
+    if (bufferedAmountPollingMode === "raf") {
+      if (typeof requestAnimationFrame !== "function") {
+        return;
+      }
+      let frame = requestAnimationFrame(function loop() {
+        pollBufferedAmount();
+        frame = requestAnimationFrame(loop);
+      });
+      return () => {
+        cancelAnimationFrame(frame);
+      };
+    }
+    const intervalId = setInterval(pollBufferedAmount, bufferedAmountPollingMode);
+    return () => {
+      clearInterval(intervalId);
+    };
+  }, [bufferedAmountPollingMode, state.status, pollBufferedAmount]);
   const status = (reconnect.status === "scheduled" || reconnect.status === "running") && state.status !== "open" ? "reconnecting" : state.status;
   const snapshot = createConnectionStateSnapshot(status, {
     isSupported: supported,
@@ -1573,55 +1640,66 @@ var useEventSource = (options) => {
     if (eventSourceRef.current !== null) {
       return;
     }
-    const source = new EventSource(resolvedUrl, {
-      withCredentials: options.withCredentials ?? false
-    });
-    const sourceEpoch = nextEventSourceEpochRef.current + 1;
-    eventSourceRef.current = source;
-    eventSourceKeyRef.current = nextEventSourceKey;
-    activeEventSourceEpochRef.current = sourceEpoch;
-    nextEventSourceEpochRef.current = sourceEpoch;
     commitState((current) => ({
       ...current,
       lastChangedAt: Date.now(),
       status: reconnect.status === "running" || reconnect.status === "scheduled" ? "reconnecting" : "connecting"
     }));
-    const handleSourceOpen = (event) => {
-      if (!isActiveEventSourceEvent(sourceEpoch)) {
+    let cancelled = false;
+    let detachListeners = null;
+    queueMicrotask(() => {
+      if (cancelled) {
         return;
       }
-      handleOpen(event, source);
-    };
-    const handleSourceMessage = (event) => {
-      if (!isActiveEventSourceEvent(sourceEpoch)) {
-        return;
-      }
-      commitParsedMessage("message", event, false);
-    };
-    const namedEventHandlers = /* @__PURE__ */ new Map();
-    const handleSourceError = (event) => {
-      handleError(event, source, sourceEpoch);
-    };
-    source.addEventListener("open", handleSourceOpen);
-    source.addEventListener("message", handleSourceMessage);
-    for (const eventName of namedEvents) {
-      const handler = (event) => {
+      const source = new EventSource(resolvedUrl, {
+        withCredentials: options.withCredentials ?? false
+      });
+      const sourceEpoch = nextEventSourceEpochRef.current + 1;
+      eventSourceRef.current = source;
+      eventSourceKeyRef.current = nextEventSourceKey;
+      activeEventSourceEpochRef.current = sourceEpoch;
+      nextEventSourceEpochRef.current = sourceEpoch;
+      const handleSourceOpen = (event) => {
         if (!isActiveEventSourceEvent(sourceEpoch)) {
           return;
         }
-        commitParsedMessage(eventName, event, true);
+        handleOpen(event, source);
       };
-      namedEventHandlers.set(eventName, handler);
-      source.addEventListener(eventName, handler);
-    }
-    source.addEventListener("error", handleSourceError);
-    return () => {
-      source.removeEventListener("open", handleSourceOpen);
-      source.removeEventListener("message", handleSourceMessage);
-      for (const [eventName, handler] of namedEventHandlers) {
-        source.removeEventListener(eventName, handler);
+      const handleSourceMessage = (event) => {
+        if (!isActiveEventSourceEvent(sourceEpoch)) {
+          return;
+        }
+        commitParsedMessage("message", event, false);
+      };
+      const namedEventHandlers = /* @__PURE__ */ new Map();
+      const handleSourceError = (event) => {
+        handleError(event, source, sourceEpoch);
+      };
+      source.addEventListener("open", handleSourceOpen);
+      source.addEventListener("message", handleSourceMessage);
+      for (const eventName of namedEvents) {
+        const handler = (event) => {
+          if (!isActiveEventSourceEvent(sourceEpoch)) {
+            return;
+          }
+          commitParsedMessage(eventName, event, true);
+        };
+        namedEventHandlers.set(eventName, handler);
+        source.addEventListener(eventName, handler);
       }
-      source.removeEventListener("error", handleSourceError);
+      source.addEventListener("error", handleSourceError);
+      detachListeners = () => {
+        source.removeEventListener("open", handleSourceOpen);
+        source.removeEventListener("message", handleSourceMessage);
+        for (const [eventName, handler] of namedEventHandlers) {
+          source.removeEventListener(eventName, handler);
+        }
+        source.removeEventListener("error", handleSourceError);
+      };
+    });
+    return () => {
+      cancelled = true;
+      detachListeners?.();
     };
   }, [
     closeEventSource,