react-realtime-hooks 1.1.0 → 1.2.1

package/dist/index.d.ts

@@ -29,6 +29,34 @@ type UsePageVisibilityHook = (options?: UsePageVisibilityOptions) => UsePageVisi
 
 declare const usePageVisibility: UsePageVisibilityHook;
 
+type ConnectionGateReason = "ready" | "manual" | "offline" | "hidden";
+interface UseConnectionGateOptions {
+    enabled?: boolean;
+    requireOnline?: boolean;
+    requireVisible?: boolean;
+    hiddenGraceMs?: number;
+    initialOnline?: boolean;
+    initialVisible?: boolean;
+    trackTransitions?: boolean;
+}
+interface UseConnectionGateResult {
+    connect: boolean;
+    isBlocked: boolean;
+    isWaitingForVisibleGrace: boolean;
+    reason: ConnectionGateReason;
+    isOnline: boolean;
+    isOnlineSupported: boolean;
+    isVisible: boolean;
+    isVisibilitySupported: boolean;
+    visibilityState: DocumentVisibilityState | "visible";
+    lastChangedAt: number | null;
+    becameReadyAt: number | null;
+    becameBlockedAt: number | null;
+}
+type UseConnectionGateHook = (options?: UseConnectionGateOptions) => UseConnectionGateResult;
+
+declare const useConnectionGate: UseConnectionGateHook;
+
 type ReconnectStatus = "idle" | "scheduled" | "running" | "stopped";
 type ReconnectTrigger = "mount" | "manual" | "close" | "error" | "heartbeat-timeout" | "offline" | "online" | "visibility";
 interface ReconnectAttempt {
@@ -235,4 +263,4 @@ type UseEventSourceHook = <TMessage = unknown>(options: UseEventSourceOptions<TM
 
 declare const useEventSource: UseEventSourceHook;
 
-export { type ConnectionStateSnapshot, type HeartbeatAckMatcher, type HeartbeatBeatFn, type MessageParser, type MessageSerializer, type Milliseconds, type RealtimeConnectionStatus, type RealtimeTransport, type ReconnectAttempt, type ReconnectDelayContext, type ReconnectDelayStrategy, type ReconnectStatus, type ReconnectTrigger, type UrlProvider, 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, useEventSource, useHeartbeat, useOnlineStatus, usePageVisibility, useReconnect, useWebSocket };
+export { type ConnectionGateReason, type ConnectionStateSnapshot, type HeartbeatAckMatcher, type HeartbeatBeatFn, type MessageParser, type MessageSerializer, type Milliseconds, type RealtimeConnectionStatus, 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

@@ -136,6 +136,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 = useRef(createManagedTimeout());
+  const hiddenSinceRef = useRef(null);
+  const previousStateRef = useRef(null);
+  const [hasExceededHiddenGrace, setHasExceededHiddenGrace] = useState(false);
+  const [isWaitingForVisibleGrace, setIsWaitingForVisibleGrace] = useState(false);
+  const [transitions, setTransitions] = useState(createEmptyTransitionState3);
+  useEffect(() => () => {
+    hiddenGraceTimeoutRef.current.cancel();
+  }, []);
+  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;
+  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,
@@ -272,57 +443,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,
@@ -704,6 +824,9 @@ var useWebSocket = (options) => {
   const protocolsDependency = toProtocolsDependency(options.protocols);
   const socketRef = useRef(null);
   const socketKeyRef = useRef(null);
+  const activeSocketEpochRef = useRef(null);
+  const closingSocketEpochRef = useRef(null);
+  const nextSocketEpochRef = useRef(0);
   const manualCloseRef = useRef(false);
   const manualOpenRef = useRef(false);
   const skipCloseReconnectRef = useRef(false);
@@ -792,17 +915,28 @@ var useWebSocket = (options) => {
     stateRef.current = resolved;
     setState(resolved);
   };
-  const closeSocket = 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 = useEffectEvent((socketEpoch) => {
+    return activeSocketEpochRef.current === socketEpoch;
   });
+  const shouldHandleSocketClose = useEffectEvent((socketEpoch) => {
+    return activeSocketEpochRef.current === socketEpoch || closingSocketEpochRef.current === socketEpoch;
+  });
+  const closeSocket = 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 = useEffectEvent(
     (action, error, reconnectTrigger) => {
       heartbeat.stop();
@@ -837,7 +971,7 @@ var useWebSocket = (options) => {
       };
       skipCloseReconnectRef.current = true;
       suppressReconnectRef.current = true;
-      closeSocket();
+      closeSocket({ trackClose: true });
     }
   );
   const parseMessage = useEffectEvent((event) => {
@@ -891,10 +1025,17 @@ var useWebSocket = (options) => {
         lastError: parseError,
         status: "error"
       }));
-      closeSocket(1003, "parse-error");
+      closeSocket({
+        code: 1003,
+        reason: "parse-error",
+        trackClose: true
+      });
     }
   });
-  const handleError = useEffectEvent((event) => {
+  const handleError = useEffectEvent((event, socketEpoch) => {
+    if (!isActiveSocketEvent(socketEpoch)) {
+      return;
+    }
     heartbeat.stop();
     commitState((current) => ({
       ...current,
@@ -904,9 +1045,18 @@ var useWebSocket = (options) => {
     }));
     options.onError?.(event);
   });
-  const handleClose = useEffectEvent((event) => {
-    socketRef.current = null;
-    socketKeyRef.current = null;
+  const handleClose = 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;
@@ -986,7 +1136,11 @@ var useWebSocket = (options) => {
       lastChangedAt: Date.now(),
       status: "closing"
     }));
-    closeSocket(code, reason);
+    closeSocket({
+      code,
+      reason,
+      trackClose: true
+    });
   };
   const send = (message) => {
     const socket2 = socketRef.current;
@@ -1038,8 +1192,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,
@@ -1048,16 +1206,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);
@@ -1081,6 +1245,8 @@ var useWebSocket = (options) => {
   useEffect(() => () => {
     suppressReconnectRef.current = true;
     socketKeyRef.current = null;
+    activeSocketEpochRef.current = null;
+    closingSocketEpochRef.current = null;
     terminalErrorRef.current = null;
     const socket2 = socketRef.current;
     socketRef.current = null;
@@ -1458,6 +1624,6 @@ var useEventSource = (options) => {
   };
 };
 
-export { useEventSource, useHeartbeat, useOnlineStatus, usePageVisibility, useReconnect, useWebSocket };
+export { useConnectionGate, useEventSource, useHeartbeat, useOnlineStatus, usePageVisibility, useReconnect, useWebSocket };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map