react-realtime-hooks 1.0.2 → 1.0.4

package/README.md

@@ -5,7 +5,7 @@
 [![Demo](https://img.shields.io/github/actions/workflow/status/volkov85/react-realtime-hooks/pages.yml?branch=main&label=demo)](https://github.com/volkov85/react-realtime-hooks/actions/workflows/pages.yml)
 [![license](https://img.shields.io/npm/l/react-realtime-hooks)](https://github.com/volkov85/react-realtime-hooks/blob/main/LICENSE)
 [![TypeScript](https://img.shields.io/badge/TypeScript-typed-3178c6)](https://www.typescriptlang.org/)
-[![react](https://img.shields.io/badge/react-18.3%2B%20%7C%2019-149eca)](https://www.npmjs.com/package/react)
+[![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.
 
@@ -60,7 +60,7 @@ npm install react-realtime-hooks
 
 Peer dependency:
 
-- `react@^18.3.0 || ^19.0.0`
+- `react@^19.0.0`
 
 ## How It Feels
 
@@ -350,11 +350,11 @@ export function NetworkIndicator() {
 | `parseMessage`     | `(event) => TIncoming`         | raw `event.data`           | Incoming parser                    |
 | `serializeMessage` | `(message) => ...`             | JSON/string passthrough    | Outgoing serializer                |
 | `reconnect`        | `false \| UseReconnectOptions` | enabled                    | Reconnect configuration            |
-| `heartbeat`        | `false \| UseHeartbeatOptions` | disabled unless configured | Heartbeat configuration            |
+| `heartbeat`        | `false \| UseWebSocketHeartbeatOptions` | disabled unless configured | Heartbeat configuration            |
 | `shouldReconnect`  | `(event) => boolean`           | `true`                     | Reconnect gate on close            |
 | `onOpen`           | `(event, socket) => void`      | `undefined`                | Open callback                      |
 | `onMessage`        | `(message, event) => void`     | `undefined`                | Message callback                   |
-| `onError`          | `(event) => void`              | `undefined`                | Error callback                     |
+| `onError`          | `(event) => void`              | `undefined`                | Called for transport, heartbeat, and parse errors |
 | `onClose`          | `(event) => void`              | `undefined`                | Close callback                     |
 
 ### Result
@@ -375,6 +375,10 @@ export function NetworkIndicator() {
 | `reconnect`        | `() => void`                 | Manual reconnect                                                           |
 | `send`             | `(message) => boolean`       | Sends an outgoing payload                                                  |
 
+When you configure `useWebSocket` heartbeat, you can also set `timeoutAction` and
+`errorAction` to `"none"`, `"close"`, or `"reconnect"`. The default is
+`"reconnect"` when reconnect is enabled and `"close"` otherwise.
+
 </details>
 
 <details>
@@ -393,7 +397,7 @@ export function NetworkIndicator() {
 | `shouldReconnect` | `(event) => boolean`                  | `true`           | Reconnect gate on error             |
 | `onOpen`          | `(event, source) => void`             | `undefined`      | Open callback                       |
 | `onMessage`       | `(message, event) => void`            | `undefined`      | Default `message` callback          |
-| `onError`         | `(event) => void`                     | `undefined`      | Error callback                      |
+| `onError`         | `(event) => void`                     | `undefined`      | Called for transport and parse errors |
 | `onEvent`         | `(eventName, message, event) => void` | `undefined`      | Named event callback                |
 
 ### Result
@@ -464,6 +468,7 @@ export function NetworkIndicator() {
 | `startOnMount` | `boolean`                                           | `true`      | Starts immediately                          |
 | `onBeat`       | `() => void`                                        | `undefined` | Called on every beat                        |
 | `onTimeout`    | `() => void`                                        | `undefined` | Called on timeout                           |
+| `onError`      | `(error) => void`                                   | `undefined` | Called when `beat()` throws or rejects      |
 
 ### Result
 
@@ -507,7 +512,8 @@ export function NetworkIndicator() {
 
 - `useEventSource` is receive-only by design. SSE is not a bidirectional transport.
 - `useWebSocket` heartbeat support is client-side. You still define your own server ping/pong protocol.
-- If `parseMessage` throws, the hook closes the current transport, moves into `error`, stores `lastError`, and stops auto-reconnect until manual `open()` or `reconnect()`.
+- If `parseMessage` throws, the hook calls `onError`, closes the current transport, moves into `error`, stores `lastError`, and stops auto-reconnect until manual `open()` or `reconnect()`.
+- Stopping heartbeat clears timeout state and the previous beat/ack timestamps so a new session starts with fresh metrics.
 - `connect: false` keeps the hook in `idle` until `open()` is called.
 - Manual `close()` is sticky. The hook stays closed until `open()` or `reconnect()` is called.
 - No transport polyfills are bundled. Provide your own runtime support where needed.

package/dist/index.cjs

@@ -404,6 +404,7 @@ var useHeartbeat = (options) => {
   const startOnMount = options.startOnMount ?? true;
   const intervalRef = react.useRef(createManagedInterval());
   const timeoutRef = react.useRef(createManagedTimeout());
+  const generationRef = react.useRef(0);
   const [state, setState] = react.useState(
     () => createInitialState2(enabled && startOnMount)
   );
@@ -430,8 +431,7 @@ var useHeartbeat = (options) => {
       handleTimeout();
     }, options.timeoutMs);
   });
-  const runBeat = react.useEffectEvent(() => {
-    const performedAt = Date.now();
+  const handleBeatSuccess = react.useEffectEvent((performedAt) => {
     commitState((current) => ({
       ...current,
       hasTimedOut: false,
@@ -439,7 +439,35 @@ var useHeartbeat = (options) => {
     }));
     scheduleTimeout();
     options.onBeat?.();
-    void options.beat?.();
+  });
+  const handleBeatError = react.useEffectEvent((error) => {
+    timeoutRef.current.cancel();
+    options.onError?.(error);
+  });
+  const runBeat = react.useEffectEvent(() => {
+    const generation = generationRef.current;
+    const completeBeat = (result) => {
+      if (generation !== generationRef.current || result === false) {
+        return;
+      }
+      handleBeatSuccess(Date.now());
+    };
+    const failBeat = (error) => {
+      if (generation !== generationRef.current) {
+        return;
+      }
+      handleBeatError(error);
+    };
+    try {
+      const result = options.beat?.();
+      if (result !== null && typeof result === "object" && "then" in result) {
+        void Promise.resolve(result).then(completeBeat, failBeat);
+        return;
+      }
+      completeBeat(result);
+    } catch (error) {
+      failBeat(error);
+    }
   });
   const start = () => {
     if (!enabled) {
@@ -457,13 +485,10 @@ var useHeartbeat = (options) => {
     }));
   };
   const stop = () => {
+    generationRef.current += 1;
     intervalRef.current.cancel();
     timeoutRef.current.cancel();
-    commitState((current) => ({
-      ...current,
-      hasTimedOut: false,
-      isRunning: false
-    }));
+    commitState(createInitialState2(false));
   };
   const beat = () => {
     if (!enabled) {
@@ -502,6 +527,7 @@ var useHeartbeat = (options) => {
     return void 0;
   }, [enabled, options.intervalMs, startOnMount]);
   react.useEffect(() => () => {
+    generationRef.current += 1;
     intervalRef.current.cancel();
     timeoutRef.current.cancel();
   }, []);
@@ -607,6 +633,7 @@ var toProtocolsDependency = (protocols) => {
   return Array.isArray(protocols) ? protocols.join("|") : protocols;
 };
 var toHeartbeatConfig = (heartbeat) => heartbeat === void 0 || heartbeat === false ? null : heartbeat;
+var isSocketActive = (socket) => socket.readyState === WebSocket.OPEN || socket.readyState === WebSocket.CONNECTING;
 var useWebSocket = (options) => {
   const connect = options.connect ?? true;
   const supported = isWebSocketSupported();
@@ -618,6 +645,7 @@ var useWebSocket = (options) => {
   const manualOpenRef = react.useRef(false);
   const skipCloseReconnectRef = react.useRef(false);
   const suppressReconnectRef = react.useRef(false);
+  const pendingCloseActionRef = react.useRef(null);
   const terminalErrorRef = react.useRef(null);
   const [openNonce, setOpenNonce] = react.useState(0);
   const [state, setState] = react.useState(
@@ -636,6 +664,7 @@ var useWebSocket = (options) => {
   const heartbeatConfig = toHeartbeatConfig(
     options.heartbeat
   );
+  const defaultHeartbeatAction = options.reconnect === false ? "close" : "reconnect";
   const heartbeatHookOptions = heartbeatConfig === null ? {
     enabled: false,
     intervalMs: 1e3,
@@ -671,6 +700,27 @@ var useWebSocket = (options) => {
   if (heartbeatConfig !== null && heartbeatConfig.onTimeout !== void 0) {
     heartbeatHookOptions.onTimeout = heartbeatConfig.onTimeout;
   }
+  if (heartbeatConfig !== null) {
+    const onTimeout = heartbeatHookOptions.onTimeout;
+    heartbeatHookOptions.onTimeout = () => {
+      applyHeartbeatAction(
+        heartbeatConfig.timeoutAction ?? defaultHeartbeatAction,
+        new Event("heartbeat-timeout"),
+        "heartbeat-timeout"
+      );
+      onTimeout?.();
+    };
+    const onError = heartbeatConfig.onError;
+    heartbeatHookOptions.onError = (error) => {
+      const event = error instanceof Event ? error : new Event("heartbeat-error");
+      applyHeartbeatAction(
+        heartbeatConfig.errorAction ?? heartbeatConfig.timeoutAction ?? defaultHeartbeatAction,
+        event,
+        "error"
+      );
+      onError?.(error);
+    };
+  }
   const heartbeat = useHeartbeat(
     heartbeatHookOptions
   );
@@ -686,10 +736,47 @@ var useWebSocket = (options) => {
     }
     socketRef.current = null;
     socketKeyRef.current = null;
-    if (socket2.readyState === WebSocket.OPEN || socket2.readyState === WebSocket.CONNECTING) {
+    if (isSocketActive(socket2)) {
       socket2.close(code, reason);
     }
   });
+  const applyHeartbeatAction = react.useEffectEvent(
+    (action, error, reconnectTrigger) => {
+      heartbeat.stop();
+      options.onError?.(error);
+      if (action === "none") {
+        commitState((current) => ({
+          ...current,
+          lastChangedAt: Date.now(),
+          lastError: error
+        }));
+        return;
+      }
+      const shouldReconnect = action === "reconnect" && reconnectEnabled && (options.shouldReconnect?.(error) ?? true);
+      manualOpenRef.current = false;
+      terminalErrorRef.current = shouldReconnect ? null : error;
+      const socket2 = socketRef.current;
+      if (socket2 === null || !isSocketActive(socket2)) {
+        commitState((current) => ({
+          ...current,
+          lastChangedAt: Date.now(),
+          lastError: error,
+          status: shouldReconnect ? "reconnecting" : "error"
+        }));
+        if (shouldReconnect) {
+          reconnect.schedule(reconnectTrigger);
+        }
+        return;
+      }
+      pendingCloseActionRef.current = {
+        error,
+        reconnectTrigger: shouldReconnect ? reconnectTrigger : null
+      };
+      skipCloseReconnectRef.current = true;
+      suppressReconnectRef.current = true;
+      closeSocket();
+    }
+  );
   const parseMessage = react.useEffectEvent((event) => {
     const parser = options.parseMessage ?? defaultParseMessage;
     return parser(event);
@@ -734,6 +821,7 @@ var useWebSocket = (options) => {
       suppressReconnectRef.current = true;
       reconnect.cancel();
       heartbeat.stop();
+      options.onError?.(parseError);
       commitState((current) => ({
         ...current,
         lastChangedAt: Date.now(),
@@ -747,6 +835,7 @@ var useWebSocket = (options) => {
     heartbeat.stop();
     commitState((current) => ({
       ...current,
+      lastChangedAt: Date.now(),
       lastError: event,
       status: "error"
     }));
@@ -757,9 +846,26 @@ var useWebSocket = (options) => {
     socketKeyRef.current = null;
     heartbeat.stop();
     updateBufferedAmount();
+    const pendingCloseAction = pendingCloseActionRef.current;
+    pendingCloseActionRef.current = null;
     const terminalError = terminalErrorRef.current;
     const skipCloseReconnect = skipCloseReconnectRef.current;
     skipCloseReconnectRef.current = false;
+    if (pendingCloseAction !== null) {
+      suppressReconnectRef.current = false;
+      commitState((current) => ({
+        ...current,
+        lastChangedAt: Date.now(),
+        lastCloseEvent: event,
+        lastError: pendingCloseAction.error ?? current.lastError,
+        status: pendingCloseAction.reconnectTrigger === null ? "error" : "reconnecting"
+      }));
+      options.onClose?.(event);
+      if (pendingCloseAction.reconnectTrigger !== null) {
+        reconnect.schedule(pendingCloseAction.reconnectTrigger);
+      }
+      return;
+    }
     if (terminalError !== null) {
       suppressReconnectRef.current = false;
       commitState((current) => ({
@@ -918,7 +1024,7 @@ var useWebSocket = (options) => {
     if (socket2 === null) {
       return;
     }
-    if (socket2.readyState === WebSocket.OPEN || socket2.readyState === WebSocket.CONNECTING) {
+    if (isSocketActive(socket2)) {
       socket2.close();
     }
   }, []);
@@ -1076,6 +1182,7 @@ var useEventSource = (options) => {
         suppressReconnectRef.current = true;
         reconnect.cancel();
         closeEventSource();
+        options.onError?.(parseError);
         commitState((current) => ({
           ...current,
           lastChangedAt: Date.now(),