react-realtime-hooks 1.3.4 → 1.4.1

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

@@ -805,9 +805,95 @@ var resolveUrlProvider = (url) => {
   const resolved = typeof url === "function" ? url() : url;
   return normalizeResolvedUrl(resolved ?? null);
 };
+var createInitialState3 = () => ({
+  manualClose: false,
+  manualOpen: false,
+  pendingCloseAction: null,
+  reconnectSuppressed: false,
+  skipNextCloseReconnect: false,
+  terminalError: null
+});
+var useWebSocketController = () => {
+  const ref = react.useRef(null);
+  if (ref.current === null) {
+    ref.current = createInitialState3();
+  }
+  const state = ref.current;
+  const controllerRef = react.useRef(null);
+  if (controllerRef.current === null) {
+    controllerRef.current = {
+      clearReconnectSuppression: () => {
+        state.reconnectSuppressed = false;
+      },
+      consumePendingCloseAction: () => {
+        const action = state.pendingCloseAction;
+        state.pendingCloseAction = null;
+        return action;
+      },
+      consumeSkipNextCloseReconnect: () => {
+        const skip = state.skipNextCloseReconnect;
+        state.skipNextCloseReconnect = false;
+        return skip;
+      },
+      hasManualCloseRequested: () => state.manualClose,
+      hasManualOpenRequested: () => state.manualOpen,
+      isReconnectSuppressed: () => state.reconnectSuppressed,
+      noteEffectInitiatedClose: () => {
+        state.reconnectSuppressed = true;
+      },
+      noteHeartbeatActiveSocketClose: (input) => {
+        state.manualOpen = false;
+        state.terminalError = input.reconnectTrigger === null ? input.error : null;
+        state.pendingCloseAction = input;
+        state.skipNextCloseReconnect = true;
+        state.reconnectSuppressed = true;
+      },
+      noteHeartbeatNoActiveSocket: ({ shouldReconnect, error }) => {
+        state.manualOpen = false;
+        state.terminalError = shouldReconnect ? null : error;
+      },
+      noteParseError: (error) => {
+        state.terminalError = error;
+        state.manualOpen = false;
+        state.skipNextCloseReconnect = true;
+        state.reconnectSuppressed = true;
+      },
+      noteSocketOpened: () => {
+        state.manualClose = false;
+        state.manualOpen = false;
+        state.reconnectSuppressed = false;
+        state.terminalError = null;
+      },
+      noteUserCloseRequested: () => {
+        state.manualClose = true;
+        state.manualOpen = false;
+        state.reconnectSuppressed = true;
+        state.terminalError = null;
+      },
+      noteUserOpenRequested: () => {
+        state.manualClose = false;
+        state.manualOpen = true;
+        state.reconnectSuppressed = false;
+        state.terminalError = null;
+      },
+      noteUserReconnectClosed: () => {
+        state.reconnectSuppressed = false;
+      },
+      noteUserReconnectRequested: () => {
+        state.manualClose = false;
+        state.manualOpen = true;
+        state.skipNextCloseReconnect = true;
+        state.reconnectSuppressed = true;
+        state.terminalError = null;
+      },
+      peekTerminalError: () => state.terminalError
+    };
+  }
+  return controllerRef.current;
+};
 
 // src/hooks/useWebSocket.ts
-var createInitialState3 = (status = "idle") => ({
+var createInitialState4 = (status = "idle") => ({
   bufferedAmount: 0,
   lastChangedAt: null,
   lastCloseEvent: null,
@@ -850,15 +936,10 @@ var useWebSocket = (options) => {
   const activeSocketEpochRef = react.useRef(null);
   const closingSocketEpochRef = react.useRef(null);
   const nextSocketEpochRef = react.useRef(0);
-  const manualCloseRef = react.useRef(false);
-  const manualOpenRef = react.useRef(false);
-  const skipCloseReconnectRef = react.useRef(false);
-  const suppressReconnectRef = react.useRef(false);
-  const pendingCloseActionRef = react.useRef(null);
-  const terminalErrorRef = react.useRef(null);
+  const controller = useWebSocketController();
   const [openNonce, setOpenNonce] = react.useState(0);
   const [state, setState] = react.useState(
-    () => createInitialState3(connect ? "connecting" : "idle")
+    () => createInitialState4(connect ? "connecting" : "idle")
   );
   const stateRef = react.useRef(state);
   stateRef.current = state;
@@ -978,10 +1059,9 @@ var useWebSocket = (options) => {
         return;
       }
       const shouldReconnect = action === "reconnect" && reconnectEnabled && (options.shouldReconnect?.(error) ?? true);
-      manualOpenRef.current = false;
-      terminalErrorRef.current = shouldReconnect ? null : error;
       const socket2 = socketRef.current;
       if (socket2 === null || !isSocketActive(socket2)) {
+        controller.noteHeartbeatNoActiveSocket({ error, shouldReconnect });
         commitState((current) => ({
           ...current,
           lastChangedAt: Date.now(),
@@ -993,12 +1073,10 @@ var useWebSocket = (options) => {
         }
         return;
       }
-      pendingCloseActionRef.current = {
+      controller.noteHeartbeatActiveSocketClose({
         error,
         reconnectTrigger: shouldReconnect ? reconnectTrigger : null
-      };
-      skipCloseReconnectRef.current = true;
-      suppressReconnectRef.current = true;
+      });
       closeSocket({ trackClose: true });
     }
   );
@@ -1013,10 +1091,7 @@ var useWebSocket = (options) => {
     }));
   });
   const handleOpen = useStableCallback((event, socket2) => {
-    manualCloseRef.current = false;
-    manualOpenRef.current = false;
-    suppressReconnectRef.current = false;
-    terminalErrorRef.current = null;
+    controller.noteSocketOpened();
     reconnect.markConnected();
     heartbeat.start();
     commitState((current) => ({
@@ -1043,10 +1118,7 @@ var useWebSocket = (options) => {
         cause: error,
         kind: "parse-error"
       });
-      terminalErrorRef.current = parseError;
-      manualOpenRef.current = false;
-      skipCloseReconnectRef.current = true;
-      suppressReconnectRef.current = true;
+      controller.noteParseError(parseError);
       reconnect.cancel();
       heartbeat.stop();
       options.onError?.(parseError);
@@ -1090,13 +1162,11 @@ var useWebSocket = (options) => {
     }
     heartbeat.stop();
     updateBufferedAmount();
-    const pendingCloseAction = pendingCloseActionRef.current;
-    pendingCloseActionRef.current = null;
-    const terminalError = terminalErrorRef.current;
-    const skipCloseReconnect = skipCloseReconnectRef.current;
-    skipCloseReconnectRef.current = false;
+    const pendingCloseAction = controller.consumePendingCloseAction();
+    const terminalError = controller.peekTerminalError();
+    const skipCloseReconnect = controller.consumeSkipNextCloseReconnect();
     if (pendingCloseAction !== null) {
-      suppressReconnectRef.current = false;
+      controller.clearReconnectSuppression();
       commitState((current) => ({
         ...current,
         lastChangedAt: Date.now(),
@@ -1111,7 +1181,7 @@ var useWebSocket = (options) => {
       return;
     }
     if (terminalError !== null) {
-      suppressReconnectRef.current = false;
+      controller.clearReconnectSuppression();
       commitState((current) => ({
         ...current,
         lastChangedAt: Date.now(),
@@ -1122,7 +1192,7 @@ var useWebSocket = (options) => {
       options.onClose?.(event);
       return;
     }
-    const shouldReconnect = !suppressReconnectRef.current && !skipCloseReconnect && reconnectEnabled && (options.shouldReconnect?.(event) ?? true);
+    const shouldReconnect = !controller.isReconnectSuppressed() && !skipCloseReconnect && reconnectEnabled && (options.shouldReconnect?.(event) ?? true);
     commitState((current) => ({
       ...current,
       lastChangedAt: Date.now(),
@@ -1133,33 +1203,23 @@ var useWebSocket = (options) => {
     if (shouldReconnect) {
       reconnect.schedule("close");
     } else {
-      suppressReconnectRef.current = false;
+      controller.clearReconnectSuppression();
     }
   });
   const open = useStableCallback(() => {
-    manualCloseRef.current = false;
-    manualOpenRef.current = true;
-    suppressReconnectRef.current = false;
-    terminalErrorRef.current = null;
+    controller.noteUserOpenRequested();
     reconnect.cancel();
     setOpenNonce((current) => current + 1);
   });
   const reconnectNow = useStableCallback(() => {
-    manualCloseRef.current = false;
-    manualOpenRef.current = true;
-    skipCloseReconnectRef.current = true;
-    suppressReconnectRef.current = true;
-    terminalErrorRef.current = null;
+    controller.noteUserReconnectRequested();
     heartbeat.stop();
     closeSocket();
-    suppressReconnectRef.current = false;
+    controller.noteUserReconnectClosed();
     reconnect.schedule("manual");
   });
   const close = useStableCallback((code, reason) => {
-    manualCloseRef.current = true;
-    manualOpenRef.current = false;
-    suppressReconnectRef.current = true;
-    terminalErrorRef.current = null;
+    controller.noteUserCloseRequested();
     reconnect.cancel();
     heartbeat.stop();
     commitState((current) => ({
@@ -1201,22 +1261,22 @@ var useWebSocket = (options) => {
       }));
       return;
     }
-    const shouldConnect = terminalErrorRef.current === null && (connect && !manualCloseRef.current || manualOpenRef.current || reconnect.status === "running");
+    const shouldConnect = controller.peekTerminalError() === null && (connect && !controller.hasManualCloseRequested() || controller.hasManualOpenRequested() || reconnect.status === "running");
     const nextSocketKey = `${resolvedUrl}::${protocolsDependency}::${options.binaryType ?? "blob"}`;
     if (!shouldConnect) {
       if (socketRef.current !== null) {
-        suppressReconnectRef.current = true;
+        controller.noteEffectInitiatedClose();
         closeSocket();
       }
       socketKeyRef.current = null;
       commitState((current) => ({
         ...current,
-        status: terminalErrorRef.current !== null ? "error" : manualCloseRef.current ? "closed" : "idle"
+        status: controller.peekTerminalError() !== null ? "error" : controller.hasManualCloseRequested() ? "closed" : "idle"
       }));
       return;
     }
     if (socketRef.current !== null && socketKeyRef.current !== nextSocketKey) {
-      suppressReconnectRef.current = true;
+      controller.noteEffectInitiatedClose();
       closeSocket();
     }
     if (socketRef.current !== null) {
@@ -1283,6 +1343,7 @@ var useWebSocket = (options) => {
     closeSocket,
     commitState,
     connect,
+    controller,
     handleClose,
     handleError,
     handleMessage,
@@ -1297,11 +1358,10 @@ var useWebSocket = (options) => {
     supported
   ]);
   react.useEffect(() => () => {
-    suppressReconnectRef.current = true;
+    controller.noteEffectInitiatedClose();
     socketKeyRef.current = null;
     activeSocketEpochRef.current = null;
     closingSocketEpochRef.current = null;
-    terminalErrorRef.current = null;
     const socket2 = socketRef.current;
     socketRef.current = null;
     if (socket2 === null) {
@@ -1310,13 +1370,65 @@ var useWebSocket = (options) => {
     if (isSocketActive(socket2)) {
       socket2.close();
     }
-  }, []);
+  }, [controller]);
   const stopHeartbeat = heartbeat.stop;
   react.useEffect(() => {
     if (state.status !== "open") {
       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,
@@ -1363,7 +1475,7 @@ var useWebSocket = (options) => {
     socket
   };
 };
-var createInitialState4 = (status = "idle") => ({
+var createInitialState5 = (status = "idle") => ({
   lastChangedAt: null,
   lastError: null,
   lastEventName: null,
@@ -1400,7 +1512,7 @@ var useEventSource = (options) => {
   const terminalErrorRef = react.useRef(null);
   const [openNonce, setOpenNonce] = react.useState(0);
   const [state, setState] = react.useState(
-    () => createInitialState4(connect ? "connecting" : "idle")
+    () => createInitialState5(connect ? "connecting" : "idle")
   );
   const stateRef = react.useRef(state);
   stateRef.current = state;