@iam4x/reconnecting-websocket 1.1.0 → 1.3.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

@@ -6,6 +6,8 @@ interface ReconnectOptions {
     connectionTimeout?: number;
     backoffFactor?: number;
     WebSocketConstructor?: typeof WebSocket;
+    healthCheckInterval?: number;
+    watchingInactivityTimeout?: number;
 }
 export declare class ReconnectingWebSocket {
     options: Required<ReconnectOptions & {
@@ -15,20 +17,34 @@ export declare class ReconnectingWebSocket {
     abortController?: AbortController;
     connectTimeout?: ReturnType<typeof setTimeout>;
     reconnectTimeout?: ReturnType<typeof setTimeout>;
+    healthCheckInterval?: ReturnType<typeof setInterval>;
+    inactivityTimeout?: ReturnType<typeof setTimeout>;
     retryCount: number;
     forcedClose: boolean;
     wasConnected: boolean;
+    private openFn?;
+    private msgFn?;
+    private closeFn?;
+    private errorFn?;
+    private abortHandler?;
     listeners: Record<EventType, Listener[]>;
+    private messageQueue;
     get readyState(): number;
     get bufferedAmount(): number;
     constructor(url: string, options?: ReconnectOptions);
     connect(): void;
     emit(event: EventType, payload: any): void;
     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;
     send(...args: Parameters<WebSocket["send"]>): void;
+    private flushMessageQueue;
     close(...args: Parameters<WebSocket["close"]>): void;
 }
 export {};

package/dist/index.js

@@ -4,9 +4,17 @@ export class ReconnectingWebSocket {
     abortController;
     connectTimeout;
     reconnectTimeout;
+    healthCheckInterval;
+    inactivityTimeout;
     retryCount = 0;
     forcedClose = false;
     wasConnected = false;
+    // Store event handlers so we can remove them when cleaning up
+    openFn;
+    msgFn;
+    closeFn;
+    errorFn;
+    abortHandler;
     listeners = {
         open: [],
         message: [],
@@ -14,6 +22,8 @@ export class ReconnectingWebSocket {
         reconnect: [],
         error: [],
     };
+    // Queue for messages sent when socket is not open
+    messageQueue = [];
     get readyState() {
         return this.ws?.readyState ?? WebSocket.CLOSED;
     }
@@ -28,43 +38,93 @@ export class ReconnectingWebSocket {
             connectionTimeout: options.connectionTimeout ?? 10_000,
             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();
     }
     connect() {
+        // Reset forcedClose flag to allow reconnection for new connection attempts
+        // This ensures that manual reconnections (via connect()) can auto-reconnect
+        this.forcedClose = false;
+        // Remove event listeners from old socket
+        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);
+        // Close old socket if still connecting or open
+        if (this.ws?.readyState === WebSocket.CONNECTING ||
+            this.ws?.readyState === WebSocket.OPEN) {
+            this.ws?.close();
+        }
+        // Clear any pending timers (this also removes abort listener from old controller)
+        this.clearTimers();
+        // Create new abort controller
         this.abortController = new AbortController();
-        this.abortController.signal.addEventListener("abort", () => {
+        this.abortHandler = () => {
             if (this.ws?.readyState === WebSocket.CONNECTING) {
                 this.ws.close();
             }
-        });
+        };
+        this.abortController.signal.addEventListener("abort", this.abortHandler);
+        // Create new socket
         this.ws = new this.options.WebSocketConstructor(this.options.url);
         this.connectTimeout = setTimeout(() => {
             this.abortController?.abort();
         }, this.options.connectionTimeout);
-        this.ws.addEventListener("open", (event) => {
-            this.clearTimers();
-            this.retryCount = 0;
-            this.emit("open", event);
-            // Emit reconnect event if this was a reconnection after a disconnection
-            if (this.wasConnected) {
-                this.emit("reconnect", event);
+        // Create and store new event handlers
+        // Capture the new socket reference to check against in handlers
+        const currentWs = this.ws;
+        this.openFn = (event) => {
+            // Only process if event is from the current socket
+            if (event.target === currentWs && this.ws === currentWs) {
+                this.clearTimers();
+                this.retryCount = 0;
+                this.emit("open", event);
+                // Emit reconnect event if this was a reconnection after a disconnection
+                if (this.wasConnected) {
+                    this.emit("reconnect", event);
+                }
+                this.wasConnected = true;
+                this.startHealthCheck();
+                this.startInactivityTimer();
+                // Flush any queued messages now that socket is open
+                this.flushMessageQueue();
             }
-            this.wasConnected = true;
-        });
-        this.ws.addEventListener("message", (event) => {
-            this.emit("message", event);
-        });
-        this.ws.addEventListener("close", (event) => {
-            this.emit("close", { code: event.code, reason: event.reason });
-            if (!this.forcedClose) {
-                this.scheduleReconnect();
+        };
+        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);
+            }
+        };
+        this.closeFn = (event) => {
+            // 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();
+                }
+            }
+        };
+        this.errorFn = (event) => {
+            // Only process if event is from the current socket
+            if (event.target === currentWs && this.ws === currentWs) {
+                this.emit("error", event);
             }
-        });
-        this.ws.addEventListener("error", (event) => {
-            this.emit("error", event);
-            // Error will typically cause connection to close, triggering reconnect
-        });
+        };
+        // Add event listeners to new socket
+        currentWs.addEventListener("open", this.openFn);
+        currentWs.addEventListener("message", this.msgFn);
+        currentWs.addEventListener("close", this.closeFn);
+        currentWs.addEventListener("error", this.errorFn);
     }
     emit(event, payload) {
         for (const listener of this.listeners[event]) {
@@ -72,11 +132,71 @@ export class ReconnectingWebSocket {
         }
     }
     scheduleReconnect() {
+        // Clear any existing reconnect timeout first to prevent multiple reconnects
+        if (this.reconnectTimeout) {
+            clearTimeout(this.reconnectTimeout);
+            this.reconnectTimeout = undefined;
+        }
         const { retryDelay, backoffFactor, maxRetryDelay } = this.options;
         const delay = Math.min(retryDelay * Math.pow(backoffFactor, this.retryCount), maxRetryDelay);
         this.retryCount += 1;
         this.reconnectTimeout = setTimeout(() => this.connect(), delay);
     }
+    startHealthCheck() {
+        this.stopHealthCheck();
+        if (this.options.healthCheckInterval <= 0) {
+            return;
+        }
+        this.healthCheckInterval = setInterval(() => {
+            // Only check if we're not forcing a close and we expect to be connected
+            if (this.forcedClose) {
+                return;
+            }
+            // If we've been connected before and the socket is not OPEN, trigger reconnection
+            if (this.wasConnected && this.readyState !== WebSocket.OPEN) {
+                // Clear the existing socket reference since it's in a bad state
+                if (this.ws) {
+                    // Don't emit close event since we didn't receive one - this is a silent failure
+                    this.ws = undefined;
+                }
+                this.stopHealthCheck();
+                this.scheduleReconnect();
+            }
+        }, this.options.healthCheckInterval);
+    }
+    stopHealthCheck() {
+        if (this.healthCheckInterval) {
+            clearInterval(this.healthCheckInterval);
+            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;
+            }
+            // Trigger reconnection due to inactivity
+            if (this.ws) {
+                this.ws.close();
+            }
+        }, 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);
@@ -86,9 +206,16 @@ export class ReconnectingWebSocket {
             clearTimeout(this.reconnectTimeout);
             this.reconnectTimeout = undefined;
         }
-        if (this.abortController) {
+        if (this.abortController && this.abortHandler) {
+            this.abortController.signal.removeEventListener("abort", this.abortHandler);
+            this.abortController = undefined;
+            this.abortHandler = undefined;
+        }
+        else if (this.abortController) {
             this.abortController = undefined;
         }
+        this.stopHealthCheck();
+        this.stopInactivityTimer();
     }
     addEventListener(event, listener) {
         this.listeners[event].push(listener);
@@ -97,12 +224,35 @@ export class ReconnectingWebSocket {
         this.listeners[event] = this.listeners[event].filter((l) => l !== listener);
     }
     send(...args) {
-        this.ws?.send(...args);
+        if (this.ws?.readyState === WebSocket.OPEN) {
+            this.ws.send(...args);
+        }
+        else {
+            this.messageQueue.push(args);
+        }
+    }
+    flushMessageQueue() {
+        while (this.messageQueue.length > 0 &&
+            this.ws?.readyState === WebSocket.OPEN) {
+            const args = this.messageQueue.shift();
+            this.ws.send(...args);
+        }
     }
     close(...args) {
         this.forcedClose = true;
         this.clearTimers();
+        // Clear the message queue on forced close
+        this.messageQueue = [];
         if (this.ws) {
+            // Remove event listeners before closing to prevent memory leaks
+            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);
             this.ws.close(...args);
             this.ws = undefined;
         }

package/package.json

@@ -3,7 +3,7 @@
   "module": "src/index.ts",
   "type": "module",
   "license": "MIT",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "private": false,
   "types": "./dist/index.d.ts",
   "exports": {
@@ -24,17 +24,18 @@
     "prepare": "husky"
   },
   "devDependencies": {
-    "@eslint/js": "^9.38.0",
-    "@typescript-eslint/parser": "^8.46.2",
-    "eslint": "^9.38.0",
+    "@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",
-    "globals": "^16.4.0",
+    "eslint-plugin-prettier": "^5.5.5",
+    "globals": "^16.5.0",
     "husky": "^9.1.7",
-    "prettier": "^3.6.2",
-    "typescript-eslint": "^8.46.2"
+    "prettier": "^3.8.1",
+    "typescript-eslint": "^8.54.0"
   },
   "peerDependencies": {
     "typescript": "^5.8.3"