react-realtime-hooks 1.1.0 → 1.2.0

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,
@@ -1458,6 +1578,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