react-realtime-hooks 1.3.3 → 1.4.0

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

@@ -1220,47 +1220,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,
@@ -1300,6 +1315,58 @@ var useWebSocket = (options) => {
       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,
@@ -1571,55 +1638,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,