ws-heartbeat-manager 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VastBlast
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,57 @@
+# ws-heartbeat-manager
+
+Lightweight heartbeat manager for `ws` server connections.
+
+## Install
+
+```bash
+npm i ws-heartbeat-manager
+```
+
+Peer dependency: `ws@^8`.
+
+## What it does
+
+- Tracks active clients.
+- Sends periodic `ping` frames.
+- Updates liveness on `pong`.
+- Terminates timed-out or errored sockets.
+- Cleans up listeners and timers automatically.
+
+## Basic usage
+
+```ts
+import { WebSocketServer } from 'ws';
+import { HeartbeatManager } from 'ws-heartbeat-manager';
+
+const wss = new WebSocketServer({ port: 8080 });
+const heartbeat = new HeartbeatManager();
+
+wss.on('connection', (ws) => {
+  heartbeat.addClient(ws);
+});
+
+process.on('SIGTERM', () => {
+  heartbeat.shutdown();
+  wss.close();
+});
+```
+
+## Custom timing
+
+```ts
+const heartbeat = new HeartbeatManager({
+  intervalMs: 15_000,   // send ping every 15s
+  timeoutMs: 30_000,    // terminate if no pong for 30s
+  tickMs: 500,          // internal sweep cadence
+  startJitterMs: 15_000 // stagger start time
+});
+```
+
+## API
+
+- `new HeartbeatManager(options?)`
+- `addClient(ws)`
+- `removeClient(ws)`
+- `shutdown()`
+- `clientCount`

package/dist/index.cjs

@@ -0,0 +1,137 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+let node_perf_hooks = require("node:perf_hooks");
+let node_timers = require("node:timers");
+
+//#region src/heartbeatManager.ts
+const WS_OPEN = 1;
+var HeartbeatManager = class {
+	clients = /* @__PURE__ */ new Map();
+	buckets;
+	bucketIndex = 0;
+	startDelayTimer;
+	tickTimer;
+	intervalMs;
+	timeoutMs;
+	tickMs;
+	startJitterMs;
+	constructor(opts = {}) {
+		this.intervalMs = opts.intervalMs ?? 3e4;
+		this.timeoutMs = opts.timeoutMs ?? this.intervalMs * 2;
+		if (!Number.isFinite(this.intervalMs) || this.intervalMs <= 0) throw new RangeError("intervalMs must be a finite number > 0");
+		if (!Number.isFinite(this.timeoutMs) || this.timeoutMs < this.intervalMs) throw new RangeError("timeoutMs must be a finite number >= intervalMs");
+		const desiredTickMs = opts.tickMs ?? Math.min(1e3, this.intervalMs);
+		const maxBuckets = opts.maxBuckets ?? 60;
+		this.startJitterMs = opts.startJitterMs ?? this.intervalMs;
+		if (!Number.isFinite(desiredTickMs) || desiredTickMs <= 0) throw new RangeError("tickMs must be a finite number > 0");
+		if (!Number.isInteger(maxBuckets) || maxBuckets < 1) throw new RangeError("maxBuckets must be an integer >= 1");
+		if (!Number.isFinite(this.startJitterMs) || this.startJitterMs < 0) throw new RangeError("startJitterMs must be a finite number >= 0");
+		const bucketCount = Math.min(maxBuckets, Math.max(1, Math.round(this.intervalMs / Math.max(50, desiredTickMs))));
+		this.tickMs = Math.max(10, Math.round(this.intervalMs / bucketCount));
+		this.buckets = Array.from({ length: bucketCount }, () => /* @__PURE__ */ new Set());
+	}
+	get clientCount() {
+		return this.clients.size;
+	}
+	addClient(ws) {
+		if (this.clients.has(ws)) return;
+		const bucket = Math.floor(Math.random() * this.buckets.length);
+		const state = {
+			lastPongAt: node_perf_hooks.performance.now(),
+			bucket,
+			onPong: () => {
+				state.lastPongAt = node_perf_hooks.performance.now();
+			},
+			onClose: () => {
+				this.removeClient(ws);
+			},
+			onError: () => {
+				this.removeClient(ws, true);
+			}
+		};
+		this.clients.set(ws, state);
+		this.bucketAt(bucket).add(ws);
+		ws.on("pong", state.onPong);
+		ws.once("close", state.onClose);
+		ws.once("error", state.onError);
+		this.startTimersIfNeeded();
+	}
+	removeClient(ws, terminate = false) {
+		if (terminate) try {
+			ws.terminate();
+		} catch {}
+		const state = this.clients.get(ws);
+		if (!state) return;
+		ws.off("pong", state.onPong);
+		ws.off("close", state.onClose);
+		ws.off("error", state.onError);
+		this.bucketAt(state.bucket).delete(ws);
+		this.clients.delete(ws);
+		if (this.clients.size === 0) this.stopTimers();
+	}
+	shutdown() {
+		this.stopTimers();
+		for (const ws of Array.from(this.clients.keys())) this.removeClient(ws, true);
+	}
+	bucketAt(index) {
+		const first = this.buckets[0];
+		if (!first) throw new Error("HeartbeatManager misconfigured: no buckets");
+		return this.buckets[index] ?? first;
+	}
+	startTimersIfNeeded() {
+		if (this.tickTimer || this.startDelayTimer) return;
+		const delay = this.startJitterMs > 0 ? Math.floor(Math.random() * this.startJitterMs) : 0;
+		if (delay === 0) {
+			this.startTickTimer();
+			return;
+		}
+		this.startDelayTimer = (0, node_timers.setTimeout)(() => {
+			this.startDelayTimer = void 0;
+			if (this.clients.size > 0) this.startTickTimer();
+		}, delay);
+		this.startDelayTimer.unref();
+	}
+	startTickTimer() {
+		if (this.tickTimer) return;
+		this.tickTimer = (0, node_timers.setInterval)(() => this.tick(), this.tickMs);
+		this.tickTimer.unref();
+	}
+	stopTimers() {
+		if (this.startDelayTimer) {
+			(0, node_timers.clearTimeout)(this.startDelayTimer);
+			this.startDelayTimer = void 0;
+		}
+		if (this.tickTimer) {
+			(0, node_timers.clearInterval)(this.tickTimer);
+			this.tickTimer = void 0;
+		}
+	}
+	tick() {
+		const now = node_perf_hooks.performance.now();
+		const bucket = this.bucketAt(this.bucketIndex);
+		for (const ws of bucket) {
+			const state = this.clients.get(ws);
+			if (!state) {
+				bucket.delete(ws);
+				continue;
+			}
+			if (ws.readyState !== WS_OPEN) {
+				this.removeClient(ws);
+				continue;
+			}
+			if (now - state.lastPongAt > this.timeoutMs) {
+				this.removeClient(ws, true);
+				continue;
+			}
+			try {
+				ws.ping();
+			} catch {
+				this.removeClient(ws, true);
+			}
+		}
+		this.bucketIndex += 1;
+		if (this.bucketIndex >= this.buckets.length) this.bucketIndex = 0;
+	}
+};
+
+//#endregion
+exports.HeartbeatManager = HeartbeatManager;

package/dist/index.d.cts

@@ -0,0 +1,33 @@
+import { WebSocket } from "ws";
+
+//#region src/heartbeatManager.d.ts
+type HeartbeatManagerOptions = Readonly<{
+  intervalMs?: number;
+  timeoutMs?: number;
+  tickMs?: number;
+  startJitterMs?: number;
+  maxBuckets?: number;
+}>;
+declare class HeartbeatManager {
+  private readonly clients;
+  private readonly buckets;
+  private bucketIndex;
+  private startDelayTimer?;
+  private tickTimer?;
+  private readonly intervalMs;
+  private readonly timeoutMs;
+  private readonly tickMs;
+  private readonly startJitterMs;
+  constructor(opts?: HeartbeatManagerOptions);
+  get clientCount(): number;
+  addClient(ws: WebSocket): void;
+  removeClient(ws: WebSocket, terminate?: boolean): void;
+  shutdown(): void;
+  private bucketAt;
+  private startTimersIfNeeded;
+  private startTickTimer;
+  private stopTimers;
+  private tick;
+}
+//#endregion
+export { HeartbeatManager, type HeartbeatManagerOptions };

package/dist/index.d.mts

@@ -0,0 +1,33 @@
+import { WebSocket } from "ws";
+
+//#region src/heartbeatManager.d.ts
+type HeartbeatManagerOptions = Readonly<{
+  intervalMs?: number;
+  timeoutMs?: number;
+  tickMs?: number;
+  startJitterMs?: number;
+  maxBuckets?: number;
+}>;
+declare class HeartbeatManager {
+  private readonly clients;
+  private readonly buckets;
+  private bucketIndex;
+  private startDelayTimer?;
+  private tickTimer?;
+  private readonly intervalMs;
+  private readonly timeoutMs;
+  private readonly tickMs;
+  private readonly startJitterMs;
+  constructor(opts?: HeartbeatManagerOptions);
+  get clientCount(): number;
+  addClient(ws: WebSocket): void;
+  removeClient(ws: WebSocket, terminate?: boolean): void;
+  shutdown(): void;
+  private bucketAt;
+  private startTimersIfNeeded;
+  private startTickTimer;
+  private stopTimers;
+  private tick;
+}
+//#endregion
+export { HeartbeatManager, type HeartbeatManagerOptions };

package/dist/index.mjs

@@ -0,0 +1,136 @@
+import { performance } from "node:perf_hooks";
+import { clearInterval, clearTimeout, setInterval, setTimeout } from "node:timers";
+
+//#region src/heartbeatManager.ts
+const WS_OPEN = 1;
+var HeartbeatManager = class {
+	clients = /* @__PURE__ */ new Map();
+	buckets;
+	bucketIndex = 0;
+	startDelayTimer;
+	tickTimer;
+	intervalMs;
+	timeoutMs;
+	tickMs;
+	startJitterMs;
+	constructor(opts = {}) {
+		this.intervalMs = opts.intervalMs ?? 3e4;
+		this.timeoutMs = opts.timeoutMs ?? this.intervalMs * 2;
+		if (!Number.isFinite(this.intervalMs) || this.intervalMs <= 0) throw new RangeError("intervalMs must be a finite number > 0");
+		if (!Number.isFinite(this.timeoutMs) || this.timeoutMs < this.intervalMs) throw new RangeError("timeoutMs must be a finite number >= intervalMs");
+		const desiredTickMs = opts.tickMs ?? Math.min(1e3, this.intervalMs);
+		const maxBuckets = opts.maxBuckets ?? 60;
+		this.startJitterMs = opts.startJitterMs ?? this.intervalMs;
+		if (!Number.isFinite(desiredTickMs) || desiredTickMs <= 0) throw new RangeError("tickMs must be a finite number > 0");
+		if (!Number.isInteger(maxBuckets) || maxBuckets < 1) throw new RangeError("maxBuckets must be an integer >= 1");
+		if (!Number.isFinite(this.startJitterMs) || this.startJitterMs < 0) throw new RangeError("startJitterMs must be a finite number >= 0");
+		const bucketCount = Math.min(maxBuckets, Math.max(1, Math.round(this.intervalMs / Math.max(50, desiredTickMs))));
+		this.tickMs = Math.max(10, Math.round(this.intervalMs / bucketCount));
+		this.buckets = Array.from({ length: bucketCount }, () => /* @__PURE__ */ new Set());
+	}
+	get clientCount() {
+		return this.clients.size;
+	}
+	addClient(ws) {
+		if (this.clients.has(ws)) return;
+		const bucket = Math.floor(Math.random() * this.buckets.length);
+		const state = {
+			lastPongAt: performance.now(),
+			bucket,
+			onPong: () => {
+				state.lastPongAt = performance.now();
+			},
+			onClose: () => {
+				this.removeClient(ws);
+			},
+			onError: () => {
+				this.removeClient(ws, true);
+			}
+		};
+		this.clients.set(ws, state);
+		this.bucketAt(bucket).add(ws);
+		ws.on("pong", state.onPong);
+		ws.once("close", state.onClose);
+		ws.once("error", state.onError);
+		this.startTimersIfNeeded();
+	}
+	removeClient(ws, terminate = false) {
+		if (terminate) try {
+			ws.terminate();
+		} catch {}
+		const state = this.clients.get(ws);
+		if (!state) return;
+		ws.off("pong", state.onPong);
+		ws.off("close", state.onClose);
+		ws.off("error", state.onError);
+		this.bucketAt(state.bucket).delete(ws);
+		this.clients.delete(ws);
+		if (this.clients.size === 0) this.stopTimers();
+	}
+	shutdown() {
+		this.stopTimers();
+		for (const ws of Array.from(this.clients.keys())) this.removeClient(ws, true);
+	}
+	bucketAt(index) {
+		const first = this.buckets[0];
+		if (!first) throw new Error("HeartbeatManager misconfigured: no buckets");
+		return this.buckets[index] ?? first;
+	}
+	startTimersIfNeeded() {
+		if (this.tickTimer || this.startDelayTimer) return;
+		const delay = this.startJitterMs > 0 ? Math.floor(Math.random() * this.startJitterMs) : 0;
+		if (delay === 0) {
+			this.startTickTimer();
+			return;
+		}
+		this.startDelayTimer = setTimeout(() => {
+			this.startDelayTimer = void 0;
+			if (this.clients.size > 0) this.startTickTimer();
+		}, delay);
+		this.startDelayTimer.unref();
+	}
+	startTickTimer() {
+		if (this.tickTimer) return;
+		this.tickTimer = setInterval(() => this.tick(), this.tickMs);
+		this.tickTimer.unref();
+	}
+	stopTimers() {
+		if (this.startDelayTimer) {
+			clearTimeout(this.startDelayTimer);
+			this.startDelayTimer = void 0;
+		}
+		if (this.tickTimer) {
+			clearInterval(this.tickTimer);
+			this.tickTimer = void 0;
+		}
+	}
+	tick() {
+		const now = performance.now();
+		const bucket = this.bucketAt(this.bucketIndex);
+		for (const ws of bucket) {
+			const state = this.clients.get(ws);
+			if (!state) {
+				bucket.delete(ws);
+				continue;
+			}
+			if (ws.readyState !== WS_OPEN) {
+				this.removeClient(ws);
+				continue;
+			}
+			if (now - state.lastPongAt > this.timeoutMs) {
+				this.removeClient(ws, true);
+				continue;
+			}
+			try {
+				ws.ping();
+			} catch {
+				this.removeClient(ws, true);
+			}
+		}
+		this.bucketIndex += 1;
+		if (this.bucketIndex >= this.buckets.length) this.bucketIndex = 0;
+	}
+};
+
+//#endregion
+export { HeartbeatManager };

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "ws-heartbeat-manager",
+  "version": "0.1.0",
+  "description": "Lightweight WebSocket heartbeat manager for ws servers.",
+  "scripts": {
+    "build": "tsdown",
+    "build:watch": "tsdown --watch",
+    "lint": "oxlint --type-aware",
+    "lint:fix": "oxlint --fix --type-aware",
+    "check:types": "tsgo --noEmit",
+    "check": "npm run lint && npm run check:types",
+    "test": "vitest",
+    "prepublishOnly": "npm test -- --run && npm run check && npm run build"
+  },
+  "keywords": [
+    "websocket",
+    "ws",
+    "heartbeat",
+    "ping",
+    "pong"
+  ],
+  "author": "VastBlast",
+  "license": "MIT",
+  "files": [
+    "dist/"
+  ],
+  "sideEffects": false,
+  "peerDependencies": {
+    "ws": "^8.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.3",
+    "@types/ws": "^8.18.1",
+    "@typescript/native-preview": "^7.0.0-dev.20251223.1",
+    "oxlint": "^1.35.0",
+    "oxlint-tsgolint": "^0.14.2",
+    "tsdown": "^0.20.3",
+    "typescript": "^5.8.3",
+    "vitest": "^4.0.16"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.cts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  }
+}