react-realtime-hooks 1.3.4 → 1.4.1

package/dist/index.d.cts

@@ -168,11 +168,39 @@ interface UseWebSocketHeartbeatOptions<TOutgoing = unknown, TIncoming = TOutgoin
     timeoutAction?: WebSocketHeartbeatAction;
     errorAction?: WebSocketHeartbeatAction;
 }
+/**
+ * Controls how the hook surfaces the live `WebSocket.bufferedAmount`
+ * value through `state.bufferedAmount`.
+ *
+ * The native `WebSocket` does not emit any event when buffered bytes
+ * drain to the network, so by default `state.bufferedAmount` is only
+ * refreshed when the consumer calls `send(...)`, when a message
+ * arrives, or when the socket transitions to `open`. For UIs that need
+ * to display real-time backpressure (e.g. an outbound queue meter,
+ * a "flushing..." indicator, or a flow-control gauge), enable polling.
+ *
+ * - `false` (default): no polling. `state.bufferedAmount` updates only
+ *   on the natural lifecycle events listed above.
+ * - `true`: poll once every 100ms while the socket is `open`.
+ * - `"raf"`: poll on every animation frame while the socket is `open`.
+ *   Recommended for visual gauges that are tied to a render loop.
+ * - `{ intervalMs: N }`: poll every `N` milliseconds. `N` must be a
+ *   positive integer; values <= 0 disable polling.
+ *
+ * Polling is automatically suspended when the socket is not in the
+ * `open` state and resumed when it returns to `open`. The hook diffs
+ * the polled value against the last committed one, so identical
+ * readings do not trigger React re-renders.
+ */
+type BufferedAmountPolling = false | true | "raf" | {
+    intervalMs: number;
+};
 interface UseWebSocketOptions<TIncoming = unknown, TOutgoing = TIncoming> {
     url: UrlProvider;
     protocols?: string | string[];
     connect?: boolean;
     binaryType?: BinaryType;
+    bufferedAmountPolling?: BufferedAmountPolling;
     parseMessage?: MessageParser<TIncoming>;
     serializeMessage?: MessageSerializer<TOutgoing>;
     reconnect?: false | UseReconnectOptions;
@@ -274,4 +302,4 @@ declare class RealtimeErrorEvent extends Event {
     constructor(type: string, init: RealtimeErrorEventInit);
 }
 
-export { type ConnectionGateReason, type ConnectionStateSnapshot, type HeartbeatAckMatcher, type HeartbeatBeatFn, type MessageParser, type MessageSerializer, type Milliseconds, type RealtimeConnectionStatus, RealtimeErrorEvent, type RealtimeErrorEventInit, type RealtimeErrorKind, type RealtimeTransport, type ReconnectAttempt, type ReconnectDelayContext, type ReconnectDelayStrategy, type ReconnectStatus, type ReconnectTrigger, type UrlProvider, type UseConnectionGateHook, type UseConnectionGateOptions, type UseConnectionGateResult, type UseEventSourceHook, type UseEventSourceOptions, type UseEventSourceResult, type UseHeartbeatHook, type UseHeartbeatOptions, type UseHeartbeatResult, type UseOnlineStatusHook, type UseOnlineStatusOptions, type UseOnlineStatusResult, type UsePageVisibilityHook, type UsePageVisibilityOptions, type UsePageVisibilityResult, type UseReconnectHook, type UseReconnectOptions, type UseReconnectResult, type UseWebSocketHeartbeatOptions, type UseWebSocketHook, type UseWebSocketOptions, type UseWebSocketResult, type WebSocketHeartbeatAction, useConnectionGate, useEventSource, useHeartbeat, useOnlineStatus, usePageVisibility, useReconnect, useWebSocket };
+export { type BufferedAmountPolling, type ConnectionGateReason, type ConnectionStateSnapshot, type HeartbeatAckMatcher, type HeartbeatBeatFn, type MessageParser, type MessageSerializer, type Milliseconds, type RealtimeConnectionStatus, RealtimeErrorEvent, type RealtimeErrorEventInit, type RealtimeErrorKind, type RealtimeTransport, type ReconnectAttempt, type ReconnectDelayContext, type ReconnectDelayStrategy, type ReconnectStatus, type ReconnectTrigger, type UrlProvider, type UseConnectionGateHook, type UseConnectionGateOptions, type UseConnectionGateResult, type UseEventSourceHook, type UseEventSourceOptions, type UseEventSourceResult, type UseHeartbeatHook, type UseHeartbeatOptions, type UseHeartbeatResult, type UseOnlineStatusHook, type UseOnlineStatusOptions, type UseOnlineStatusResult, type UsePageVisibilityHook, type UsePageVisibilityOptions, type UsePageVisibilityResult, type UseReconnectHook, type UseReconnectOptions, type UseReconnectResult, type UseWebSocketHeartbeatOptions, type UseWebSocketHook, type UseWebSocketOptions, type UseWebSocketResult, type WebSocketHeartbeatAction, useConnectionGate, useEventSource, useHeartbeat, useOnlineStatus, usePageVisibility, useReconnect, useWebSocket };

package/dist/index.d.ts

@@ -168,11 +168,39 @@ interface UseWebSocketHeartbeatOptions<TOutgoing = unknown, TIncoming = TOutgoin
     timeoutAction?: WebSocketHeartbeatAction;
     errorAction?: WebSocketHeartbeatAction;
 }
+/**
+ * Controls how the hook surfaces the live `WebSocket.bufferedAmount`
+ * value through `state.bufferedAmount`.
+ *
+ * The native `WebSocket` does not emit any event when buffered bytes
+ * drain to the network, so by default `state.bufferedAmount` is only
+ * refreshed when the consumer calls `send(...)`, when a message
+ * arrives, or when the socket transitions to `open`. For UIs that need
+ * to display real-time backpressure (e.g. an outbound queue meter,
+ * a "flushing..." indicator, or a flow-control gauge), enable polling.
+ *
+ * - `false` (default): no polling. `state.bufferedAmount` updates only
+ *   on the natural lifecycle events listed above.
+ * - `true`: poll once every 100ms while the socket is `open`.
+ * - `"raf"`: poll on every animation frame while the socket is `open`.
+ *   Recommended for visual gauges that are tied to a render loop.
+ * - `{ intervalMs: N }`: poll every `N` milliseconds. `N` must be a
+ *   positive integer; values <= 0 disable polling.
+ *
+ * Polling is automatically suspended when the socket is not in the
+ * `open` state and resumed when it returns to `open`. The hook diffs
+ * the polled value against the last committed one, so identical
+ * readings do not trigger React re-renders.
+ */
+type BufferedAmountPolling = false | true | "raf" | {
+    intervalMs: number;
+};
 interface UseWebSocketOptions<TIncoming = unknown, TOutgoing = TIncoming> {
     url: UrlProvider;
     protocols?: string | string[];
     connect?: boolean;
     binaryType?: BinaryType;
+    bufferedAmountPolling?: BufferedAmountPolling;
     parseMessage?: MessageParser<TIncoming>;
     serializeMessage?: MessageSerializer<TOutgoing>;
     reconnect?: false | UseReconnectOptions;
@@ -274,4 +302,4 @@ declare class RealtimeErrorEvent extends Event {
     constructor(type: string, init: RealtimeErrorEventInit);
 }
 
-export { type ConnectionGateReason, type ConnectionStateSnapshot, type HeartbeatAckMatcher, type HeartbeatBeatFn, type MessageParser, type MessageSerializer, type Milliseconds, type RealtimeConnectionStatus, RealtimeErrorEvent, type RealtimeErrorEventInit, type RealtimeErrorKind, type RealtimeTransport, type ReconnectAttempt, type ReconnectDelayContext, type ReconnectDelayStrategy, type ReconnectStatus, type ReconnectTrigger, type UrlProvider, type UseConnectionGateHook, type UseConnectionGateOptions, type UseConnectionGateResult, type UseEventSourceHook, type UseEventSourceOptions, type UseEventSourceResult, type UseHeartbeatHook, type UseHeartbeatOptions, type UseHeartbeatResult, type UseOnlineStatusHook, type UseOnlineStatusOptions, type UseOnlineStatusResult, type UsePageVisibilityHook, type UsePageVisibilityOptions, type UsePageVisibilityResult, type UseReconnectHook, type UseReconnectOptions, type UseReconnectResult, type UseWebSocketHeartbeatOptions, type UseWebSocketHook, type UseWebSocketOptions, type UseWebSocketResult, type WebSocketHeartbeatAction, useConnectionGate, useEventSource, useHeartbeat, useOnlineStatus, usePageVisibility, useReconnect, useWebSocket };
+export { type BufferedAmountPolling, type ConnectionGateReason, type ConnectionStateSnapshot, type HeartbeatAckMatcher, type HeartbeatBeatFn, type MessageParser, type MessageSerializer, type Milliseconds, type RealtimeConnectionStatus, RealtimeErrorEvent, type RealtimeErrorEventInit, type RealtimeErrorKind, type RealtimeTransport, type ReconnectAttempt, type ReconnectDelayContext, type ReconnectDelayStrategy, type ReconnectStatus, type ReconnectTrigger, type UrlProvider, type UseConnectionGateHook, type UseConnectionGateOptions, type UseConnectionGateResult, type UseEventSourceHook, type UseEventSourceOptions, type UseEventSourceResult, type UseHeartbeatHook, type UseHeartbeatOptions, type UseHeartbeatResult, type UseOnlineStatusHook, type UseOnlineStatusOptions, type UseOnlineStatusResult, type UsePageVisibilityHook, type UsePageVisibilityOptions, type UsePageVisibilityResult, type UseReconnectHook, type UseReconnectOptions, type UseReconnectResult, type UseWebSocketHeartbeatOptions, type UseWebSocketHook, type UseWebSocketOptions, type UseWebSocketResult, type WebSocketHeartbeatAction, useConnectionGate, useEventSource, useHeartbeat, useOnlineStatus, usePageVisibility, useReconnect, useWebSocket };

package/dist/index.js

@@ -803,9 +803,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 = useRef(null);
+  if (ref.current === null) {
+    ref.current = createInitialState3();
+  }
+  const state = ref.current;
+  const controllerRef = 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,
@@ -848,15 +934,10 @@ var useWebSocket = (options) => {
   const activeSocketEpochRef = useRef(null);
   const closingSocketEpochRef = useRef(null);
   const nextSocketEpochRef = useRef(0);
-  const manualCloseRef = useRef(false);
-  const manualOpenRef = useRef(false);
-  const skipCloseReconnectRef = useRef(false);
-  const suppressReconnectRef = useRef(false);
-  const pendingCloseActionRef = useRef(null);
-  const terminalErrorRef = useRef(null);
+  const controller = useWebSocketController();
   const [openNonce, setOpenNonce] = useState(0);
   const [state, setState] = useState(
-    () => createInitialState3(connect ? "connecting" : "idle")
+    () => createInitialState4(connect ? "connecting" : "idle")
   );
   const stateRef = useRef(state);
   stateRef.current = state;
@@ -976,10 +1057,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(),
@@ -991,12 +1071,10 @@ var useWebSocket = (options) => {
         }
         return;
       }
-      pendingCloseActionRef.current = {
+      controller.noteHeartbeatActiveSocketClose({
         error,
         reconnectTrigger: shouldReconnect ? reconnectTrigger : null
-      };
-      skipCloseReconnectRef.current = true;
-      suppressReconnectRef.current = true;
+      });
       closeSocket({ trackClose: true });
     }
   );
@@ -1011,10 +1089,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) => ({
@@ -1041,10 +1116,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);
@@ -1088,13 +1160,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(),
@@ -1109,7 +1179,7 @@ var useWebSocket = (options) => {
       return;
     }
     if (terminalError !== null) {
-      suppressReconnectRef.current = false;
+      controller.clearReconnectSuppression();
       commitState((current) => ({
         ...current,
         lastChangedAt: Date.now(),
@@ -1120,7 +1190,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(),
@@ -1131,33 +1201,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) => ({
@@ -1199,22 +1259,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) {
@@ -1281,6 +1341,7 @@ var useWebSocket = (options) => {
     closeSocket,
     commitState,
     connect,
+    controller,
     handleClose,
     handleError,
     handleMessage,
@@ -1295,11 +1356,10 @@ var useWebSocket = (options) => {
     supported
   ]);
   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) {
@@ -1308,13 +1368,65 @@ var useWebSocket = (options) => {
     if (isSocketActive(socket2)) {
       socket2.close();
     }
-  }, []);
+  }, [controller]);
   const stopHeartbeat = heartbeat.stop;
   useEffect(() => {
     if (state.status !== "open") {
       stopHeartbeat();
     }
   }, [state.status, stopHeartbeat]);
+  const rawBufferedAmountPolling = options.bufferedAmountPolling;
+  const bufferedAmountPollingMode = 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
+    }));
+  });
+  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,
@@ -1361,7 +1473,7 @@ var useWebSocket = (options) => {
     socket
   };
 };
-var createInitialState4 = (status = "idle") => ({
+var createInitialState5 = (status = "idle") => ({
   lastChangedAt: null,
   lastError: null,
   lastEventName: null,
@@ -1398,7 +1510,7 @@ var useEventSource = (options) => {
   const terminalErrorRef = useRef(null);
   const [openNonce, setOpenNonce] = useState(0);
   const [state, setState] = useState(
-    () => createInitialState4(connect ? "connecting" : "idle")
+    () => createInitialState5(connect ? "connecting" : "idle")
   );
   const stateRef = useRef(state);
   stateRef.current = state;