@iam4x/reconnecting-websocket 1.2.0 → 1.4.0

package/README.md

@@ -5,7 +5,9 @@ A robust, TypeScript-first WebSocket client with automatic reconnection, exponen
 ## Features
 
 - ✅ **Automatic Reconnection** - Automatically reconnects on connection loss with exponential backoff
+- ✅ **Message Queueing** - Messages sent while disconnected are queued and delivered on reconnection
 - ✅ **Connection Timeout** - Configurable timeout to detect stalled connections
+- ✅ **Inactivity Detection** - Optionally reconnect when no messages are received within a timeout
 - ✅ **Event-Driven API** - Familiar event listener pattern matching WebSocket API
 - ✅ **TypeScript Support** - Full TypeScript definitions included
 - ✅ **Customizable** - Configurable retry delays, backoff factors, and WebSocket implementations
@@ -76,6 +78,8 @@ interface ReconnectOptions {
   maxRetryDelay?: number;        // Maximum retry delay in ms (default: 30000)
   connectionTimeout?: number;    // Connection timeout in ms (default: 10000)
   backoffFactor?: number;        // Exponential backoff multiplier (default: 2)
+  healthCheckInterval?: number;  // Health check interval in ms (default: 30000)
+  watchingInactivityTimeout?: number; // Inactivity timeout in ms (default: 0, disabled)
   WebSocketConstructor?: typeof WebSocket; // Custom WebSocket implementation
 }
 ```
@@ -86,6 +90,8 @@ interface ReconnectOptions {
 - **maxRetryDelay**: The maximum delay between reconnection attempts. The delay will grow exponentially but won't exceed this value
 - **connectionTimeout**: If a connection doesn't establish within this time, it will be aborted and retried
 - **backoffFactor**: The multiplier for exponential backoff. Each retry delay is multiplied by this factor
+- **healthCheckInterval**: Interval for checking if the socket is still healthy. Set to `0` to disable (default: 30000ms)
+- **watchingInactivityTimeout**: If no message is received within this timeout, the connection will be closed and a reconnection attempt will be made. Useful for detecting silent connection failures or keeping connections alive on servers that expect regular activity. Set to `0` to disable (default: 0, disabled). A common value is `300000` (5 minutes)
 - **WebSocketConstructor**: Allows you to provide a custom WebSocket implementation (useful for Node.js environments using libraries like `ws`)
 
 ### Methods
@@ -119,14 +125,14 @@ ws.removeEventListener("open", handler);
 
 #### `send(data)`
 
-Sends data through the WebSocket connection.
+Sends data through the WebSocket connection. If the socket is not open, messages are automatically queued and sent once the connection is established.
 
 ```typescript
 ws.send("Hello, Server!");
 ws.send(JSON.stringify({ type: "ping" }));
 ```
 
-**Note:** This method will silently fail if the socket is not connected. Check `readyState` before sending if needed.
+**Note:** Messages sent while disconnected are queued and delivered in order when the socket opens. The queue is cleared if `close()` is called.
 
 #### `close(code?, reason?)`
 
@@ -181,6 +187,26 @@ const ws = new ReconnectingWebSocket("wss://api.example.com", {
 });
 ```
 
+### Inactivity Timeout
+
+Use `watchingInactivityTimeout` to automatically reconnect when no messages are received for a period of time. This is useful for detecting silent connection failures or when the server expects regular activity:
+
+```typescript
+const ws = new ReconnectingWebSocket("wss://api.example.com", {
+  watchingInactivityTimeout: 300000, // Reconnect if no message received for 5 minutes
+});
+
+ws.addEventListener("message", (event: MessageEvent) => {
+  // Each message received resets the inactivity timer
+  console.log("Received:", event.data);
+});
+
+ws.addEventListener("close", (event) => {
+  // This will fire when inactivity timeout triggers a reconnect
+  console.log("Connection closed:", event.code, event.reason);
+});
+```
+
 ### Using with Node.js
 
 ```typescript
@@ -194,30 +220,24 @@ const ws = new ReconnectingWebSocket("wss://api.example.com", {
 
 ### Handling Reconnections
 
-```typescript
-let messageQueue: string[] = [];
+Messages sent while disconnected are automatically queued and delivered when the connection is restored:
 
-ws.addEventListener("open", () => {
-  // Flush queued messages when reconnected
-  while (messageQueue.length > 0) {
-    ws.send(messageQueue.shift()!);
-  }
-});
+```typescript
+const ws = new ReconnectingWebSocket("wss://api.example.com");
 
 ws.addEventListener("reconnect", () => {
   console.log("Reconnected! Resuming operations...");
 });
 
-// Queue messages when disconnected
-function sendMessage(data: string) {
-  if (ws.readyState === WebSocket.OPEN) {
-    ws.send(data);
-  } else {
-    messageQueue.push(data);
-  }
-}
+// Safe to call anytime - messages are queued if disconnected
+ws.send("message1");
+ws.send("message2");
+
+// When socket opens/reconnects, queued messages are sent automatically
 ```
 
+**Note:** Calling `close()` clears the message queue. Messages queued before a forced close are discarded.
+
 ### Error Handling
 
 ```typescript

package/dist/index.d.ts

@@ -7,6 +7,7 @@ interface ReconnectOptions {
     backoffFactor?: number;
     WebSocketConstructor?: typeof WebSocket;
     healthCheckInterval?: number;
+    watchingInactivityTimeout?: number;
 }
 export declare class ReconnectingWebSocket {
     options: Required<ReconnectOptions & {
@@ -17,6 +18,7 @@ export declare class ReconnectingWebSocket {
     connectTimeout?: ReturnType<typeof setTimeout>;
     reconnectTimeout?: ReturnType<typeof setTimeout>;
     healthCheckInterval?: ReturnType<typeof setInterval>;
+    inactivityTimeout?: ReturnType<typeof setTimeout>;
     retryCount: number;
     forcedClose: boolean;
     wasConnected: boolean;
@@ -35,6 +37,9 @@ export declare class ReconnectingWebSocket {
     scheduleReconnect(): void;
     startHealthCheck(): void;
     stopHealthCheck(): void;
+    startInactivityTimer(): void;
+    stopInactivityTimer(): void;
+    resetInactivityTimer(): void;
     clearTimers(): void;
     addEventListener(event: EventType, listener: Listener): void;
     removeEventListener(event: EventType, listener: Listener): void;

package/dist/index.js

@@ -5,6 +5,7 @@ export class ReconnectingWebSocket {
     connectTimeout;
     reconnectTimeout;
     healthCheckInterval;
+    inactivityTimeout;
     retryCount = 0;
     forcedClose = false;
     wasConnected = false;
@@ -38,6 +39,7 @@ export class ReconnectingWebSocket {
             backoffFactor: options.backoffFactor ?? 2,
             WebSocketConstructor: options.WebSocketConstructor ?? WebSocket,
             healthCheckInterval: options.healthCheckInterval ?? 30_000,
+            watchingInactivityTimeout: options.watchingInactivityTimeout ?? 0, // disabled by default, set to 300_000 for 5 minutes
         };
         this.connect();
     }
@@ -89,6 +91,7 @@ export class ReconnectingWebSocket {
                 }
                 this.wasConnected = true;
                 this.startHealthCheck();
+                this.startInactivityTimer();
                 // Flush any queued messages now that socket is open
                 this.flushMessageQueue();
             }
@@ -96,6 +99,7 @@ export class ReconnectingWebSocket {
         this.msgFn = (event) => {
             // Only process if event is from the current socket
             if (event.target === currentWs && this.ws === currentWs) {
+                this.resetInactivityTimer();
                 this.emit("message", event);
             }
         };
@@ -103,6 +107,7 @@ export class ReconnectingWebSocket {
             // Only process if event is from the current socket
             if (event.target === currentWs && this.ws === currentWs) {
                 this.stopHealthCheck();
+                this.stopInactivityTimer();
                 this.emit("close", { code: event.code, reason: event.reason });
                 if (!this.forcedClose) {
                     this.scheduleReconnect();
@@ -165,6 +170,52 @@ export class ReconnectingWebSocket {
             this.healthCheckInterval = undefined;
         }
     }
+    startInactivityTimer() {
+        this.stopInactivityTimer();
+        if (this.options.watchingInactivityTimeout <= 0) {
+            return;
+        }
+        this.inactivityTimeout = setTimeout(() => {
+            // Only trigger if we're not forcing a close and we expect to be connected
+            if (this.forcedClose) {
+                return;
+            }
+            // Proactively trigger reconnection due to inactivity
+            // Don't rely on the close event as it may never fire on a stalled connection
+            if (this.ws) {
+                // Stop health check to prevent it from also triggering reconnection
+                this.stopHealthCheck();
+                // Remove event listeners to prevent any late events from interfering
+                if (this.openFn)
+                    this.ws.removeEventListener("open", this.openFn);
+                if (this.msgFn)
+                    this.ws.removeEventListener("message", this.msgFn);
+                if (this.closeFn)
+                    this.ws.removeEventListener("close", this.closeFn);
+                if (this.errorFn)
+                    this.ws.removeEventListener("error", this.errorFn);
+                // Try to close the socket (may hang on stalled connections, but we don't wait)
+                this.ws.close();
+                // Clear the socket reference
+                this.ws = undefined;
+                // Emit close event to listeners with a special code indicating inactivity timeout
+                this.emit("close", { code: 4000, reason: "Inactivity timeout" });
+                // Schedule reconnection directly without waiting for close event
+                this.scheduleReconnect();
+            }
+        }, this.options.watchingInactivityTimeout);
+    }
+    stopInactivityTimer() {
+        if (this.inactivityTimeout) {
+            clearTimeout(this.inactivityTimeout);
+            this.inactivityTimeout = undefined;
+        }
+    }
+    resetInactivityTimer() {
+        if (this.options.watchingInactivityTimeout > 0) {
+            this.startInactivityTimer();
+        }
+    }
     clearTimers() {
         if (this.connectTimeout) {
             clearTimeout(this.connectTimeout);
@@ -183,6 +234,7 @@ export class ReconnectingWebSocket {
             this.abortController = undefined;
         }
         this.stopHealthCheck();
+        this.stopInactivityTimer();
     }
     addEventListener(event, listener) {
         this.listeners[event].push(listener);

package/package.json

@@ -3,7 +3,7 @@
   "module": "src/index.ts",
   "type": "module",
   "license": "MIT",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "private": false,
   "types": "./dist/index.d.ts",
   "exports": {
@@ -24,18 +24,18 @@
     "prepare": "husky"
   },
   "devDependencies": {
-    "@eslint/js": "^9.39.1",
-    "@types/bun": "^1.3.3",
-    "@typescript-eslint/parser": "^8.48.1",
-    "eslint": "^9.39.1",
+    "@eslint/js": "^9.39.2",
+    "@types/bun": "^1.3.6",
+    "@typescript-eslint/parser": "^8.54.0",
+    "eslint": "^9.39.2",
     "eslint-config-prettier": "10.1.1",
     "eslint-import-resolver-typescript": "4.3.1",
     "eslint-plugin-import": "^2.32.0",
-    "eslint-plugin-prettier": "^5.5.4",
+    "eslint-plugin-prettier": "^5.5.5",
     "globals": "^16.5.0",
     "husky": "^9.1.7",
-    "prettier": "^3.7.3",
-    "typescript-eslint": "^8.48.1"
+    "prettier": "^3.8.1",
+    "typescript-eslint": "^8.54.0"
   },
   "peerDependencies": {
     "typescript": "^5.8.3"