react-realtime-hooks 1.1.0 → 1.2.1

package/README.md

@@ -7,9 +7,9 @@
 [![TypeScript](https://img.shields.io/badge/TypeScript-typed-3178c6)](https://www.typescriptlang.org/)
 [![react](https://img.shields.io/badge/react-19.x-149eca)](https://www.npmjs.com/package/react)
 
-Production-ready React hooks for WebSocket and SSE with auto-reconnect, heartbeat, typed connection state, and browser network awareness including page visibility.
+Production-ready React hooks for WebSocket and SSE with auto-reconnect, heartbeat, typed connection state, and browser network awareness including page visibility and connection gating.
 
-`react-realtime-hooks` is for apps that need more than "open a socket and hope for the best". It gives you composable hooks for transport lifecycle, retry strategy, heartbeat, online status, and page visibility, so your UI can react to realtime state without rebuilding the same connection logic in every screen.
+`react-realtime-hooks` is for apps that need more than "open a socket and hope for the best". It gives you composable hooks for transport lifecycle, retry strategy, heartbeat, online status, page visibility, and connection gating, so your UI can react to realtime state without rebuilding the same connection logic in every screen.
 
 Live demo: https://volkov85.github.io/react-realtime-hooks/
 
@@ -24,6 +24,7 @@ Real apps need:
 - heartbeat and timeout tracking
 - clean SSR behavior
 - browser network and page visibility awareness
+- environment-aware connection gating for offline state and background tabs
 - typed message parsing and sending
 
 `react-realtime-hooks` packages those concerns into small hooks that compose cleanly in React.
@@ -33,6 +34,7 @@ Real apps need:
 - `useWebSocket` and `useEventSource` return state you can render, not just transport instances.
 - Built-in reconnect flow with exponential backoff, jitter, attempt limits, and manual restart.
 - Heartbeat support with ack matching, timeout detection, and latency measurement.
+- `useConnectionGate` turns online and visibility signals into a single `connect` flag for transport hooks.
 - Discriminated connection snapshots: `idle`, `connecting`, `open`, `reconnecting`, `closing`, `closed`, `error`.
 - First-class TypeScript support with generic message types and custom parsers/serializers.
 - SSR-safe by default. No browser-only globals are touched during server render.
@@ -46,7 +48,7 @@ Real apps need:
 | Connection state  | You model it yourself              | Built-in status model you can render directly    |
 | Reconnect flow    | Manual timers and teardown         | `useReconnect` with backoff, jitter, and limits  |
 | Heartbeat         | Custom ping/pong loop              | `heartbeat` support with timeout and latency     |
-| Browser awareness | Separate browser event wiring      | `useOnlineStatus` and `usePageVisibility` for browser state |
+| Browser awareness | Separate browser event wiring      | `useOnlineStatus`, `usePageVisibility`, and `useConnectionGate` for browser-aware state |
 | SSR safety        | Easy to break during render        | Browser-only behavior stays out of server render |
 | UI ergonomics     | Event handlers and refs everywhere | Hook result already shaped for product UI        |
 
@@ -151,7 +153,7 @@ Browser APIs
   WebSocket / EventSource / navigator.onLine
 
 Core hooks
-  useReconnect / useHeartbeat / useOnlineStatus / usePageVisibility
+  useReconnect / useHeartbeat / useOnlineStatus / usePageVisibility / useConnectionGate
 
 Transport hooks
   useWebSocket / useEventSource
@@ -209,6 +211,7 @@ This library already models those edges in a reusable way.
 | `useEventSource`  | Server-Sent Events streams           | `status`, `eventSource`, `lastMessage`, `lastEventName`, `reconnect()`       |
 | `useReconnect`    | Reusable retry and backoff logic     | `schedule()`, `cancel()`, `reset()`, `attempt`, `status`                     |
 | `useHeartbeat`    | Liveness checks and timeout tracking | `start()`, `stop()`, `beat()`, `notifyAck()`, `latencyMs`                    |
+| `useConnectionGate` | Browser-aware transport gating     | `connect`, `reason`, `isBlocked`, gate transition timestamps                 |
 | `useOnlineStatus` | Browser online/offline state         | `isOnline`, `isSupported`, transition timestamps                             |
 | `usePageVisibility` | Browser tab/page visibility state  | `isVisible`, `visibilityState`, `isSupported`, transition timestamps         |
 
@@ -357,6 +360,33 @@ export function AttentionAwareBadge() {
   );
 }
 ```
+### `useConnectionGate`
+
+```tsx
+import { useConnectionGate, useWebSocket } from "react-realtime-hooks";
+
+export function GatedNotifications() {
+  const gate = useConnectionGate({
+    requireOnline: true,
+    requireVisible: true,
+    hiddenGraceMs: 30_000,
+  });
+  const socket = useWebSocket({
+    connect: gate.connect,
+    reconnect: {
+      initialDelayMs: 1_000,
+      maxAttempts: null,
+    },
+    url: "ws://localhost:8080/notifications",
+  });
+
+  return (
+    <div>
+      Gate: {gate.reason} | Transport: {socket.status}
+    </div>
+  );
+}
+```
 ## API Reference
 
 <details>
@@ -509,6 +539,42 @@ When you configure `useWebSocket` heartbeat, you can also set `timeoutAction` an
 
 </details>
 
+<details>
+<summary><strong>useConnectionGate</strong></summary>
+
+### Options
+
+| Option             | Type      | Default | Description                                                        |
+| ------------------ | --------- | ------- | ------------------------------------------------------------------ |
+| `enabled`          | `boolean` | `true`  | Master on/off switch for the gate                                  |
+| `requireOnline`    | `boolean` | `true`  | Blocks `connect` when the browser reports offline                  |
+| `requireVisible`   | `boolean` | `false` | Blocks `connect` when the page is hidden                           |
+| `hiddenGraceMs`    | `number`  | `0`     | Delay before hidden pages are blocked                              |
+| `initialOnline`    | `boolean` | `true`  | Fallback value when `navigator.onLine` is unavailable              |
+| `initialVisible`   | `boolean` | `true`  | Fallback value when the Visibility API is unavailable              |
+| `trackTransitions` | `boolean` | `true`  | Tracks `lastChangedAt`, `becameReadyAt`, and `becameBlockedAt`     |
+
+### Result
+
+| Field                      | Type                                       | Description                                                |
+| -------------------------- | ------------------------------------------ | ---------------------------------------------------------- |
+| `connect`                  | `boolean`                                  | Flag to pass into `useWebSocket` or `useEventSource`       |
+| `isBlocked`                | `boolean`                                  | Whether the gate is currently blocking connection          |
+| `reason`                   | `"ready" \| "manual" \| "offline" \| "hidden"` | Current gate reason                                        |
+| `isWaitingForVisibleGrace` | `boolean`                                  | `true` while a hidden-tab grace window is still active     |
+| `isOnline`                 | `boolean`                                  | Current browser online state                               |
+| `isOnlineSupported`        | `boolean`                                  | Whether `navigator.onLine` is available                    |
+| `isVisible`                | `boolean`                                  | Whether the current page is visible                        |
+| `isVisibilitySupported`    | `boolean`                                  | Whether `document.visibilityState` is available            |
+| `visibilityState`          | `DocumentVisibilityState \| "visible"`   | Current browser visibility state                           |
+| `lastChangedAt`            | `number \| null`                          | Timestamp of the last gate state change                    |
+| `becameReadyAt`            | `number \| null`                          | Timestamp of the last transition into `reason === "ready"` |
+| `becameBlockedAt`          | `number \| null`                          | Timestamp of the last transition into a blocked state      |
+
+`reason` priority is deterministic: `manual` overrides `offline`, and `offline` overrides `hidden`.
+That keeps the gate predictable when multiple blockers apply at once.
+
+</details>
 <details>
 <summary><strong>useOnlineStatus</strong></summary>
 
@@ -600,3 +666,4 @@ MIT
 
 
 
+

package/dist/index.cjs

@@ -138,6 +138,177 @@ var usePageVisibility = (options = {}) => {
   };
 };
 
+// src/core/timers.ts
+var sanitizeTimerDelay = (delayMs) => {
+  if (!Number.isFinite(delayMs)) {
+    return 0;
+  }
+  return Math.max(0, Math.round(delayMs));
+};
+var createManagedTimeout = () => {
+  let timeoutId = null;
+  return {
+    cancel() {
+      if (timeoutId !== null) {
+        clearTimeout(timeoutId);
+        timeoutId = null;
+      }
+    },
+    isActive() {
+      return timeoutId !== null;
+    },
+    schedule(callback, delayMs) {
+      if (timeoutId !== null) {
+        clearTimeout(timeoutId);
+      }
+      timeoutId = setTimeout(() => {
+        timeoutId = null;
+        callback();
+      }, sanitizeTimerDelay(delayMs));
+    }
+  };
+};
+var createManagedInterval = () => {
+  let intervalId = null;
+  return {
+    cancel() {
+      if (intervalId !== null) {
+        clearInterval(intervalId);
+        intervalId = null;
+      }
+    },
+    isActive() {
+      return intervalId !== null;
+    },
+    start(callback, intervalMs) {
+      if (intervalId !== null) {
+        clearInterval(intervalId);
+      }
+      intervalId = setInterval(callback, sanitizeTimerDelay(intervalMs));
+    }
+  };
+};
+
+// src/hooks/useConnectionGate.ts
+var createEmptyTransitionState3 = () => ({
+  becameBlockedAt: null,
+  becameReadyAt: null,
+  lastChangedAt: null
+});
+var normalizeHiddenGraceMs = (value) => {
+  if (value === void 0 || !Number.isFinite(value)) {
+    return 0;
+  }
+  return Math.max(0, value);
+};
+var useConnectionGate = (options = {}) => {
+  const enabled = options.enabled ?? true;
+  const requireOnline = options.requireOnline ?? true;
+  const requireVisible = options.requireVisible ?? false;
+  const hiddenGraceMs = normalizeHiddenGraceMs(options.hiddenGraceMs);
+  const trackTransitions = options.trackTransitions ?? true;
+  const onlineStatus = useOnlineStatus({
+    ...options.initialOnline === void 0 ? {} : { initialOnline: options.initialOnline },
+    trackTransitions: false
+  });
+  const pageVisibility = usePageVisibility({
+    ...options.initialVisible === void 0 ? {} : { initialVisible: options.initialVisible },
+    trackTransitions: false
+  });
+  const hiddenGraceTimeoutRef = react.useRef(createManagedTimeout());
+  const hiddenSinceRef = react.useRef(null);
+  const previousStateRef = react.useRef(null);
+  const [hasExceededHiddenGrace, setHasExceededHiddenGrace] = react.useState(false);
+  const [isWaitingForVisibleGrace, setIsWaitingForVisibleGrace] = react.useState(false);
+  const [transitions, setTransitions] = react.useState(createEmptyTransitionState3);
+  react.useEffect(() => () => {
+    hiddenGraceTimeoutRef.current.cancel();
+  }, []);
+  react.useEffect(() => {
+    hiddenGraceTimeoutRef.current.cancel();
+    if (!requireVisible || pageVisibility.isVisible) {
+      hiddenSinceRef.current = null;
+      setHasExceededHiddenGrace(false);
+      setIsWaitingForVisibleGrace(false);
+      return;
+    }
+    const hiddenSince = hiddenSinceRef.current ?? Date.now();
+    hiddenSinceRef.current = hiddenSince;
+    if (hiddenGraceMs <= 0) {
+      setHasExceededHiddenGrace(true);
+      setIsWaitingForVisibleGrace(false);
+      return;
+    }
+    const elapsedMs = Date.now() - hiddenSince;
+    if (elapsedMs >= hiddenGraceMs) {
+      setHasExceededHiddenGrace(true);
+      setIsWaitingForVisibleGrace(false);
+      return;
+    }
+    setHasExceededHiddenGrace(false);
+    setIsWaitingForVisibleGrace(true);
+    hiddenGraceTimeoutRef.current.schedule(() => {
+      setHasExceededHiddenGrace(true);
+      setIsWaitingForVisibleGrace(false);
+    }, hiddenGraceMs - elapsedMs);
+  }, [hiddenGraceMs, pageVisibility.isVisible, requireVisible]);
+  let reason = "ready";
+  if (!enabled) {
+    reason = "manual";
+  } else if (requireOnline && !onlineStatus.isOnline) {
+    reason = "offline";
+  } else if (requireVisible && !pageVisibility.isVisible && hasExceededHiddenGrace) {
+    reason = "hidden";
+  }
+  const connect = reason === "ready";
+  const isBlocked = !connect;
+  react.useEffect(() => {
+    if (!trackTransitions) {
+      previousStateRef.current = {
+        connect,
+        reason
+      };
+      setTransitions(createEmptyTransitionState3);
+      return;
+    }
+    const previousState = previousStateRef.current;
+    if (previousState === null) {
+      previousStateRef.current = {
+        connect,
+        reason
+      };
+      return;
+    }
+    if (previousState.connect === connect && previousState.reason === reason) {
+      return;
+    }
+    const changedAt = Date.now();
+    previousStateRef.current = {
+      connect,
+      reason
+    };
+    setTransitions((current) => ({
+      becameBlockedAt: connect ? current.becameBlockedAt : changedAt,
+      becameReadyAt: connect ? changedAt : current.becameReadyAt,
+      lastChangedAt: changedAt
+    }));
+  }, [connect, reason, trackTransitions]);
+  return {
+    becameBlockedAt: transitions.becameBlockedAt,
+    becameReadyAt: transitions.becameReadyAt,
+    connect,
+    isBlocked,
+    isOnline: onlineStatus.isOnline,
+    isOnlineSupported: onlineStatus.isSupported,
+    isVisibilitySupported: pageVisibility.isSupported,
+    isVisible: pageVisibility.isVisible,
+    isWaitingForVisibleGrace,
+    lastChangedAt: transitions.lastChangedAt,
+    reason,
+    visibilityState: pageVisibility.visibilityState
+  };
+};
+
 // src/core/reconnect.ts
 var DEFAULT_RECONNECT_OPTIONS = {
   backoffFactor: 2,
@@ -274,57 +445,6 @@ var createReconnectAttempt = (attempt, trigger, options, lastDelayMs, config = {
   };
 };
 
-// src/core/timers.ts
-var sanitizeTimerDelay = (delayMs) => {
-  if (!Number.isFinite(delayMs)) {
-    return 0;
-  }
-  return Math.max(0, Math.round(delayMs));
-};
-var createManagedTimeout = () => {
-  let timeoutId = null;
-  return {
-    cancel() {
-      if (timeoutId !== null) {
-        clearTimeout(timeoutId);
-        timeoutId = null;
-      }
-    },
-    isActive() {
-      return timeoutId !== null;
-    },
-    schedule(callback, delayMs) {
-      if (timeoutId !== null) {
-        clearTimeout(timeoutId);
-      }
-      timeoutId = setTimeout(() => {
-        timeoutId = null;
-        callback();
-      }, sanitizeTimerDelay(delayMs));
-    }
-  };
-};
-var createManagedInterval = () => {
-  let intervalId = null;
-  return {
-    cancel() {
-      if (intervalId !== null) {
-        clearInterval(intervalId);
-        intervalId = null;
-      }
-    },
-    isActive() {
-      return intervalId !== null;
-    },
-    start(callback, intervalMs) {
-      if (intervalId !== null) {
-        clearInterval(intervalId);
-      }
-      intervalId = setInterval(callback, sanitizeTimerDelay(intervalMs));
-    }
-  };
-};
-
 // src/hooks/useReconnect.ts
 var createInitialState = (enabled) => ({
   attempt: 0,
@@ -706,6 +826,9 @@ var useWebSocket = (options) => {
   const protocolsDependency = toProtocolsDependency(options.protocols);
   const socketRef = react.useRef(null);
   const socketKeyRef = react.useRef(null);
+  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);
@@ -794,17 +917,28 @@ var useWebSocket = (options) => {
     stateRef.current = resolved;
     setState(resolved);
   };
-  const closeSocket = react.useEffectEvent((code, reason) => {
-    const socket2 = socketRef.current;
-    if (socket2 === null) {
-      return;
-    }
-    socketRef.current = null;
-    socketKeyRef.current = null;
-    if (isSocketActive(socket2)) {
-      socket2.close(code, reason);
-    }
+  const isActiveSocketEvent = react.useEffectEvent((socketEpoch) => {
+    return activeSocketEpochRef.current === socketEpoch;
   });
+  const shouldHandleSocketClose = react.useEffectEvent((socketEpoch) => {
+    return activeSocketEpochRef.current === socketEpoch || closingSocketEpochRef.current === socketEpoch;
+  });
+  const closeSocket = react.useEffectEvent(
+    (config = {}) => {
+      const socket2 = socketRef.current;
+      const socketEpoch = activeSocketEpochRef.current;
+      if (socket2 === null || socketEpoch === null) {
+        return;
+      }
+      socketRef.current = null;
+      socketKeyRef.current = null;
+      activeSocketEpochRef.current = null;
+      closingSocketEpochRef.current = config.trackClose ? socketEpoch : null;
+      if (isSocketActive(socket2)) {
+        socket2.close(config.code, config.reason);
+      }
+    }
+  );
   const applyHeartbeatAction = react.useEffectEvent(
     (action, error, reconnectTrigger) => {
       heartbeat.stop();
@@ -839,7 +973,7 @@ var useWebSocket = (options) => {
       };
       skipCloseReconnectRef.current = true;
       suppressReconnectRef.current = true;
-      closeSocket();
+      closeSocket({ trackClose: true });
     }
   );
   const parseMessage = react.useEffectEvent((event) => {
@@ -893,10 +1027,17 @@ var useWebSocket = (options) => {
         lastError: parseError,
         status: "error"
       }));
-      closeSocket(1003, "parse-error");
+      closeSocket({
+        code: 1003,
+        reason: "parse-error",
+        trackClose: true
+      });
     }
   });
-  const handleError = react.useEffectEvent((event) => {
+  const handleError = react.useEffectEvent((event, socketEpoch) => {
+    if (!isActiveSocketEvent(socketEpoch)) {
+      return;
+    }
     heartbeat.stop();
     commitState((current) => ({
       ...current,
@@ -906,9 +1047,18 @@ var useWebSocket = (options) => {
     }));
     options.onError?.(event);
   });
-  const handleClose = react.useEffectEvent((event) => {
-    socketRef.current = null;
-    socketKeyRef.current = null;
+  const handleClose = react.useEffectEvent((event, socketEpoch) => {
+    if (!shouldHandleSocketClose(socketEpoch)) {
+      return;
+    }
+    if (activeSocketEpochRef.current === socketEpoch) {
+      socketRef.current = null;
+      socketKeyRef.current = null;
+      activeSocketEpochRef.current = null;
+    }
+    if (closingSocketEpochRef.current === socketEpoch) {
+      closingSocketEpochRef.current = null;
+    }
     heartbeat.stop();
     updateBufferedAmount();
     const pendingCloseAction = pendingCloseActionRef.current;
@@ -988,7 +1138,11 @@ var useWebSocket = (options) => {
       lastChangedAt: Date.now(),
       status: "closing"
     }));
-    closeSocket(code, reason);
+    closeSocket({
+      code,
+      reason,
+      trackClose: true
+    });
   };
   const send = (message) => {
     const socket2 = socketRef.current;
@@ -1040,8 +1194,12 @@ var useWebSocket = (options) => {
       return;
     }
     const socket2 = new WebSocket(resolvedUrl, options.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,
@@ -1050,16 +1208,22 @@ var useWebSocket = (options) => {
       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)) {
+        return;
+      }
       handleMessage(event);
     };
     const handleSocketError = (event) => {
-      handleError(event);
+      handleError(event, socketEpoch);
     };
     const handleSocketClose = (event) => {
-      handleClose(event);
+      handleClose(event, socketEpoch);
     };
     socket2.addEventListener("open", handleSocketOpen);
     socket2.addEventListener("message", handleSocketMessage);
@@ -1083,6 +1247,8 @@ var useWebSocket = (options) => {
   react.useEffect(() => () => {
     suppressReconnectRef.current = true;
     socketKeyRef.current = null;
+    activeSocketEpochRef.current = null;
+    closingSocketEpochRef.current = null;
     terminalErrorRef.current = null;
     const socket2 = socketRef.current;
     socketRef.current = null;
@@ -1460,6 +1626,7 @@ var useEventSource = (options) => {
   };
 };
 
+exports.useConnectionGate = useConnectionGate;
 exports.useEventSource = useEventSource;
 exports.useHeartbeat = useHeartbeat;
 exports.useOnlineStatus = useOnlineStatus;