react-ws-kit 1.0.2 → 1.1.0

package/README.md

@@ -9,6 +9,7 @@ A production-quality, typed WebSocket hook for React with intelligent connection
 - **Per-Hook State**: Each hook maintains its own `allData` history and UI state
 - **Message Queuing**: Optional FIFO queue for offline message buffering
 - **Auto-Reconnect**: Configurable linear backoff strategy
+- **Heartbeat/Ping**: Built-in connection health monitoring with automatic ping/pong
 - **Kill Switch**: Programmatically close connections for all subscribers
 - **Zero Dependencies**: Only peer dependency is React 16.8+ (hooks support)
 
@@ -95,6 +96,18 @@ function TypedChat() {
 | `parse` | `(event: MessageEvent) => TIn` | `JSON.parse` | Custom message parser |
 | `serialize` | `(data: TOut) => string` | `JSON.stringify` | Custom message serializer |
 | `key` | `string` | `undefined` | Deterministic key for function identity |
+| `heartbeat` | `HeartbeatOptions` | `undefined` | Heartbeat/ping configuration (see below) |
+
+#### Heartbeat Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enabled` | `boolean` | `false` | Enable automatic heartbeat/ping |
+| `interval` | `number` | `30000` | Interval between ping messages (ms) |
+| `timeout` | `number` | `5000` | Timeout waiting for pong response (ms) |
+| `pingMessage` | `TOut \| (() => TOut)` | `{ type: 'ping' }` | Message to send as ping |
+| `isPong` | `(message: TIn) => boolean` | `(msg) => msg?.type === 'pong'` | Function to detect pong response |
+| `reconnectOnFailure` | `boolean` | `true` | Trigger reconnection on heartbeat failure |
 
 #### Return Value
 
@@ -179,6 +192,57 @@ send({ message: 'World' })
 // On reconnect, both messages are sent in order
 ```
 
+## Heartbeat/Ping
+
+Enable automatic connection health monitoring with heartbeat/ping:
+
+```typescript
+const socket = useSocket('ws://api.example.com/chat', {
+  autoConnect: true,
+  autoReconnect: true,
+  heartbeat: {
+    enabled: true,
+    interval: 30000,      // Send ping every 30 seconds
+    timeout: 5000,        // Expect pong within 5 seconds
+    pingMessage: { type: 'ping' },
+    isPong: (msg) => msg.type === 'pong',
+    reconnectOnFailure: true  // Auto-reconnect if pong not received
+  }
+})
+```
+
+### Custom Ping/Pong Messages
+
+You can customize the ping message format and pong detection:
+
+```typescript
+const socket = useSocket('ws://api.example.com/chat', {
+  heartbeat: {
+    enabled: true,
+    interval: 20000,
+    // Dynamic ping message
+    pingMessage: () => ({ 
+      cmd: 'heartbeat', 
+      timestamp: Date.now() 
+    }),
+    // Custom pong detection
+    isPong: (msg) => msg.cmd === 'heartbeat_ack',
+  }
+})
+```
+
+### How It Works
+
+1. **Ping Interval**: When connected, a ping message is sent at the configured interval
+2. **Pong Detection**: When a message matching `isPong()` is received, the heartbeat timer is reset
+3. **Timeout**: If no pong is received within the timeout period, the connection is considered unhealthy
+4. **Reconnection**: If `reconnectOnFailure` is true, the socket will close and trigger auto-reconnect
+5. **No Broadcast**: Pong messages are filtered and not broadcast to `allData` or `lastReturnedData`
+
+### Native WebSocket Ping/Pong
+
+If your WebSocket server uses native WebSocket ping/pong frames (not application-level messages), you don't need to configure heartbeat - the browser handles it automatically!
+
 ## Testing
 
 The package includes comprehensive unit tests:

package/dist/index.d.mts

@@ -56,6 +56,41 @@ interface Options<TIn = unknown, TOut = unknown> {
      * Use when parse/serialize functions are not referentially stable
      */
     key?: string;
+    /**
+     * Heartbeat/ping configuration for connection health monitoring
+     */
+    heartbeat?: {
+        /**
+         * Enable automatic heartbeat/ping
+         * @default false
+         */
+        enabled?: boolean;
+        /**
+         * Interval between ping messages in milliseconds
+         * @default 30000 (30 seconds)
+         */
+        interval?: number;
+        /**
+         * Timeout waiting for pong response in milliseconds
+         * @default 5000 (5 seconds)
+         */
+        timeout?: number;
+        /**
+         * Message to send as ping. Can be a static value or function.
+         * @default { type: 'ping' }
+         */
+        pingMessage?: TOut | (() => TOut);
+        /**
+         * Function to detect if an incoming message is a pong response
+         * @default (msg) => msg?.type === 'pong'
+         */
+        isPong?: (message: TIn) => boolean;
+        /**
+         * Trigger automatic reconnection on heartbeat failure
+         * @default true
+         */
+        reconnectOnFailure?: boolean;
+    };
 }
 /**
  * Return value of the useSocket hook

package/dist/index.d.ts

@@ -56,6 +56,41 @@ interface Options<TIn = unknown, TOut = unknown> {
      * Use when parse/serialize functions are not referentially stable
      */
     key?: string;
+    /**
+     * Heartbeat/ping configuration for connection health monitoring
+     */
+    heartbeat?: {
+        /**
+         * Enable automatic heartbeat/ping
+         * @default false
+         */
+        enabled?: boolean;
+        /**
+         * Interval between ping messages in milliseconds
+         * @default 30000 (30 seconds)
+         */
+        interval?: number;
+        /**
+         * Timeout waiting for pong response in milliseconds
+         * @default 5000 (5 seconds)
+         */
+        timeout?: number;
+        /**
+         * Message to send as ping. Can be a static value or function.
+         * @default { type: 'ping' }
+         */
+        pingMessage?: TOut | (() => TOut);
+        /**
+         * Function to detect if an incoming message is a pong response
+         * @default (msg) => msg?.type === 'pong'
+         */
+        isPong?: (message: TIn) => boolean;
+        /**
+         * Trigger automatic reconnection on heartbeat failure
+         * @default true
+         */
+        reconnectOnFailure?: boolean;
+    };
 }
 /**
  * Return value of the useSocket hook

package/dist/index.js

@@ -143,7 +143,7 @@ var defaultSerialize = (data) => {
   return JSON.stringify(data);
 };
 function normalizeOptions(options) {
-  return {
+  const normalized = {
     autoConnect: options?.autoConnect ?? false,
     protocols: options?.protocols,
     autoReconnect: options?.autoReconnect ?? false,
@@ -155,11 +155,67 @@ function normalizeOptions(options) {
     serialize: options?.serialize ?? defaultSerialize,
     key: options?.key
   };
+  if (options?.heartbeat?.enabled) {
+    normalized.heartbeat = {
+      enabled: true,
+      interval: options.heartbeat.interval ?? 3e4,
+      timeout: options.heartbeat.timeout ?? 5e3,
+      pingMessage: options.heartbeat.pingMessage ?? { type: "ping" },
+      isPong: options.heartbeat.isPong ?? ((msg) => msg?.type === "pong"),
+      reconnectOnFailure: options.heartbeat.reconnectOnFailure ?? true
+    };
+  }
+  return normalized;
 }
 var subscriberIdCounter = 0;
 function generateSubscriberId() {
   return `sub-${++subscriberIdCounter}-${Date.now()}`;
 }
+function startHeartbeat(instance) {
+  if (!instance.config.heartbeat?.enabled || !instance.socket) {
+    return;
+  }
+  const { interval, timeout, pingMessage, reconnectOnFailure } = instance.config.heartbeat;
+  const sendPing = () => {
+    if (instance.socket?.readyState !== WebSocket.OPEN) {
+      return;
+    }
+    try {
+      const ping = typeof pingMessage === "function" ? pingMessage() : pingMessage;
+      const serialized = instance.config.serialize(ping);
+      instance.socket.send(serialized);
+      instance.heartbeatTimeout = setTimeout(() => {
+        console.warn("[useSocket] Heartbeat timeout - no pong received");
+        if (reconnectOnFailure && instance.socket) {
+          instance.socket.close();
+        }
+      }, timeout);
+    } catch (error) {
+      console.error("[useSocket] Heartbeat ping error:", error);
+    }
+  };
+  instance.heartbeatInterval = setInterval(sendPing, interval);
+  sendPing();
+  console.log(`[useSocket] Heartbeat started (interval: ${interval}ms, timeout: ${timeout}ms)`);
+}
+function stopHeartbeat(instance) {
+  if (instance.heartbeatInterval) {
+    clearInterval(instance.heartbeatInterval);
+    instance.heartbeatInterval = null;
+  }
+  if (instance.heartbeatTimeout) {
+    clearTimeout(instance.heartbeatTimeout);
+    instance.heartbeatTimeout = null;
+  }
+  console.log("[useSocket] Heartbeat stopped");
+}
+function recordPong(instance) {
+  if (instance.heartbeatTimeout) {
+    clearTimeout(instance.heartbeatTimeout);
+    instance.heartbeatTimeout = null;
+  }
+  instance.lastPongTime = Date.now();
+}
 function useSocket(url, options) {
   const config = (0, import_react.useRef)(normalizeOptions(options)).current;
   const socketKey = (0, import_react.useRef)(createSocketKey(url, config)).current;
@@ -254,10 +310,15 @@ function useSocket(url, options) {
         instance.reconnectAttemptsMade = 0;
         updateAllSubscribers(instance, "connected");
         flushQueue(instance);
+        startHeartbeat(instance);
       };
       ws.onmessage = (event) => {
         try {
           const data = instance.config.parse(event);
+          if (instance.config.heartbeat?.enabled && instance.config.heartbeat.isPong(data)) {
+            recordPong(instance);
+            return;
+          }
           instance.subscribers.forEach((sub) => {
             if (sub.isConnected) {
               sub.setLastReturnedData(data);
@@ -274,6 +335,7 @@ function useSocket(url, options) {
       };
       ws.onclose = () => {
         console.log("[useSocket] Disconnected:", socketKey);
+        stopHeartbeat(instance);
         instance.socket = null;
         if (!instance.killed && instance.config.autoReconnect && instance.refCount > 0) {
           scheduleReconnect(instance);
@@ -323,6 +385,7 @@ function useSocket(url, options) {
         clearTimeout(instance.reconnectTimer);
         instance.reconnectTimer = null;
       }
+      stopHeartbeat(instance);
       if (instance.socket) {
         instance.socket.close();
         instance.socket = null;
@@ -363,6 +426,7 @@ function useSocket(url, options) {
       clearTimeout(instance.reconnectTimer);
       instance.reconnectTimer = null;
     }
+    stopHeartbeat(instance);
     if (instance.socket) {
       instance.socket.close();
       instance.socket = null;

package/dist/index.mjs

@@ -116,7 +116,7 @@ var defaultSerialize = (data) => {
   return JSON.stringify(data);
 };
 function normalizeOptions(options) {
-  return {
+  const normalized = {
     autoConnect: options?.autoConnect ?? false,
     protocols: options?.protocols,
     autoReconnect: options?.autoReconnect ?? false,
@@ -128,11 +128,67 @@ function normalizeOptions(options) {
     serialize: options?.serialize ?? defaultSerialize,
     key: options?.key
   };
+  if (options?.heartbeat?.enabled) {
+    normalized.heartbeat = {
+      enabled: true,
+      interval: options.heartbeat.interval ?? 3e4,
+      timeout: options.heartbeat.timeout ?? 5e3,
+      pingMessage: options.heartbeat.pingMessage ?? { type: "ping" },
+      isPong: options.heartbeat.isPong ?? ((msg) => msg?.type === "pong"),
+      reconnectOnFailure: options.heartbeat.reconnectOnFailure ?? true
+    };
+  }
+  return normalized;
 }
 var subscriberIdCounter = 0;
 function generateSubscriberId() {
   return `sub-${++subscriberIdCounter}-${Date.now()}`;
 }
+function startHeartbeat(instance) {
+  if (!instance.config.heartbeat?.enabled || !instance.socket) {
+    return;
+  }
+  const { interval, timeout, pingMessage, reconnectOnFailure } = instance.config.heartbeat;
+  const sendPing = () => {
+    if (instance.socket?.readyState !== WebSocket.OPEN) {
+      return;
+    }
+    try {
+      const ping = typeof pingMessage === "function" ? pingMessage() : pingMessage;
+      const serialized = instance.config.serialize(ping);
+      instance.socket.send(serialized);
+      instance.heartbeatTimeout = setTimeout(() => {
+        console.warn("[useSocket] Heartbeat timeout - no pong received");
+        if (reconnectOnFailure && instance.socket) {
+          instance.socket.close();
+        }
+      }, timeout);
+    } catch (error) {
+      console.error("[useSocket] Heartbeat ping error:", error);
+    }
+  };
+  instance.heartbeatInterval = setInterval(sendPing, interval);
+  sendPing();
+  console.log(`[useSocket] Heartbeat started (interval: ${interval}ms, timeout: ${timeout}ms)`);
+}
+function stopHeartbeat(instance) {
+  if (instance.heartbeatInterval) {
+    clearInterval(instance.heartbeatInterval);
+    instance.heartbeatInterval = null;
+  }
+  if (instance.heartbeatTimeout) {
+    clearTimeout(instance.heartbeatTimeout);
+    instance.heartbeatTimeout = null;
+  }
+  console.log("[useSocket] Heartbeat stopped");
+}
+function recordPong(instance) {
+  if (instance.heartbeatTimeout) {
+    clearTimeout(instance.heartbeatTimeout);
+    instance.heartbeatTimeout = null;
+  }
+  instance.lastPongTime = Date.now();
+}
 function useSocket(url, options) {
   const config = useRef(normalizeOptions(options)).current;
   const socketKey = useRef(createSocketKey(url, config)).current;
@@ -227,10 +283,15 @@ function useSocket(url, options) {
         instance.reconnectAttemptsMade = 0;
         updateAllSubscribers(instance, "connected");
         flushQueue(instance);
+        startHeartbeat(instance);
       };
       ws.onmessage = (event) => {
         try {
           const data = instance.config.parse(event);
+          if (instance.config.heartbeat?.enabled && instance.config.heartbeat.isPong(data)) {
+            recordPong(instance);
+            return;
+          }
           instance.subscribers.forEach((sub) => {
             if (sub.isConnected) {
               sub.setLastReturnedData(data);
@@ -247,6 +308,7 @@ function useSocket(url, options) {
       };
       ws.onclose = () => {
         console.log("[useSocket] Disconnected:", socketKey);
+        stopHeartbeat(instance);
         instance.socket = null;
         if (!instance.killed && instance.config.autoReconnect && instance.refCount > 0) {
           scheduleReconnect(instance);
@@ -296,6 +358,7 @@ function useSocket(url, options) {
         clearTimeout(instance.reconnectTimer);
         instance.reconnectTimer = null;
       }
+      stopHeartbeat(instance);
       if (instance.socket) {
         instance.socket.close();
         instance.socket = null;
@@ -336,6 +399,7 @@ function useSocket(url, options) {
       clearTimeout(instance.reconnectTimer);
       instance.reconnectTimer = null;
     }
+    stopHeartbeat(instance);
     if (instance.socket) {
       instance.socket.close();
       instance.socket = null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-ws-kit",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "Production-quality typed WebSocket hook for React with intelligent connection sharing, auto-reconnect, and message queuing",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -59,7 +59,9 @@
     "message-queue",
     "typed-websocket",
     "react-hook",
-    "websocket-client"
+    "websocket-client",
+    "heartbeat",
+    "ping-pong"
   ],
   "license": "MIT",
   "sideEffects": false,