react-realtime-hooks 1.0.4 → 1.2.0

package/dist/index.d.ts

@@ -13,6 +13,50 @@ type UseOnlineStatusHook = (options?: UseOnlineStatusOptions) => UseOnlineStatus
 
 declare const useOnlineStatus: UseOnlineStatusHook;
 
+interface UsePageVisibilityOptions {
+    initialVisible?: boolean;
+    trackTransitions?: boolean;
+}
+interface UsePageVisibilityResult {
+    isVisible: boolean;
+    visibilityState: DocumentVisibilityState | "visible";
+    isSupported: boolean;
+    lastChangedAt: number | null;
+    becameVisibleAt: number | null;
+    becameHiddenAt: number | null;
+}
+type UsePageVisibilityHook = (options?: UsePageVisibilityOptions) => UsePageVisibilityResult;
+
+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 {
@@ -219,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 UseReconnectHook, type UseReconnectOptions, type UseReconnectResult, type UseWebSocketHeartbeatOptions, type UseWebSocketHook, type UseWebSocketOptions, type UseWebSocketResult, type WebSocketHeartbeatAction, useEventSource, useHeartbeat, useOnlineStatus, 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

@@ -6,6 +6,7 @@ import { useSyncExternalStore, useRef, useState, useEffect, useEffectEvent, useM
 var isWebSocketSupported = () => typeof WebSocket !== "undefined";
 var isEventSourceSupported = () => typeof EventSource !== "undefined";
 var hasNavigatorOnLineSupport = () => typeof navigator !== "undefined" && typeof navigator.onLine === "boolean";
+var hasDocumentVisibilitySupport = () => typeof document !== "undefined" && typeof document.visibilityState === "string";
 var readOnlineStatus = (initialOnline = true) => {
   if (!hasNavigatorOnLineSupport()) {
     return {
@@ -18,6 +19,20 @@ var readOnlineStatus = (initialOnline = true) => {
     isSupported: true
   };
 };
+var readPageVisibility = (initialVisible = true) => {
+  if (!hasDocumentVisibilitySupport()) {
+    return {
+      isVisible: initialVisible,
+      isSupported: false,
+      visibilityState: initialVisible ? "visible" : "hidden"
+    };
+  }
+  return {
+    isVisible: document.visibilityState === "visible",
+    isSupported: true,
+    visibilityState: document.visibilityState
+  };
+};
 
 // src/hooks/useOnlineStatus.ts
 var subscribeToOnlineStatus = (onStoreChange) => {
@@ -70,6 +85,227 @@ var useOnlineStatus = (options = {}) => {
     ...transitions
   };
 };
+var subscribeToPageVisibility = (onStoreChange) => {
+  if (typeof document === "undefined" || !hasDocumentVisibilitySupport()) {
+    return () => {
+    };
+  }
+  document.addEventListener("visibilitychange", onStoreChange);
+  return () => {
+    document.removeEventListener("visibilitychange", onStoreChange);
+  };
+};
+var createEmptyTransitionState2 = () => ({
+  lastChangedAt: null,
+  becameHiddenAt: null,
+  becameVisibleAt: null
+});
+var usePageVisibility = (options = {}) => {
+  const initialVisible = options.initialVisible ?? true;
+  const trackTransitions = options.trackTransitions ?? true;
+  const visibilityState = useSyncExternalStore(
+    subscribeToPageVisibility,
+    () => readPageVisibility(initialVisible).visibilityState,
+    () => initialVisible ? "visible" : "hidden"
+  );
+  const isVisible = visibilityState === "visible";
+  const previousVisibleRef = useRef(isVisible);
+  const [transitions, setTransitions] = useState(createEmptyTransitionState2);
+  useEffect(() => {
+    if (!trackTransitions) {
+      previousVisibleRef.current = isVisible;
+      setTransitions(createEmptyTransitionState2);
+      return;
+    }
+    if (previousVisibleRef.current === isVisible) {
+      return;
+    }
+    const changedAt = Date.now();
+    previousVisibleRef.current = isVisible;
+    setTransitions((current) => ({
+      lastChangedAt: changedAt,
+      becameHiddenAt: isVisible ? current.becameHiddenAt : changedAt,
+      becameVisibleAt: isVisible ? changedAt : current.becameVisibleAt
+    }));
+  }, [isVisible, trackTransitions]);
+  return {
+    isSupported: hasDocumentVisibilitySupport(),
+    isVisible,
+    visibilityState,
+    ...transitions
+  };
+};
+
+// 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 = {
@@ -207,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,
@@ -1393,6 +1578,6 @@ var useEventSource = (options) => {
   };
 };
 
-export { useEventSource, useHeartbeat, useOnlineStatus, useReconnect, useWebSocket };
+export { useConnectionGate, useEventSource, useHeartbeat, useOnlineStatus, usePageVisibility, useReconnect, useWebSocket };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map