Registry / messaging / websocket-heartbeats

websocket-heartbeats

library1.2.0jsnpmunverified

A lightweight TypeScript library for monitoring WebSocket connections using heartbeat pings. Version 1.2.0 is the latest stable release. It periodically sends ping frames and detects connection loss with configurable intervals, invoking a callback on timeout. Unlike manually implementing timers, it handles cleanup and disconnection scenarios. Designed for browser and Node.js environments with ESM and CJS support. No external dependencies. Suitable for real-time applications like chat, trading, or IoT.

messaging

npm install websocket-heartbeats

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · WEBSOCKET-HEARTBEA

websocket-heartbeats

messagingjavascriptv1.2.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Heartbeat

✓ import { Heartbeat } from 'websocket-heartbeats'

✗ import Heartbeat from 'websocket-heartbeats'

Named export only. Default import is not available.

HeartbeatOptions

✓ import { HeartbeatOptions } from 'websocket-heartbeats'

✗ type HeartbeatOptions = { ... }

Type export; only needed if using TypeScript.

Heartbeat in CommonJS

✓ const { Heartbeat } = require('websocket-heartbeats')

✗ const Heartbeat = require('websocket-heartbeats')

CJS destructured require. Otherwise you get an object with Heartbeat property.

Creates a Heartbeat instance, starts it on WebSocket open, stops on close, and calls receive on pong messages.

import { Heartbeat } from 'websocket-heartbeats'; const ws = new WebSocket('wss://example.com/socket'); const heartbeat = new Heartbeat({ webSocket: ws, onTimeout: () => { console.error('Connection lost'); ws.close(); }, heartbeatInterval: 30000, // 30 seconds timeoutInterval: 10000 // 10 seconds wait for pong }); ws.onopen = () => heartbeat.start(); ws.onclose = () => heartbeat.stop(); ws.onmessage = (event) => { if (event.data === 'pong') heartbeat.receive(); };

Debug

Known issues

gotchaHeartbeat.stop() must be called on WebSocket close to clear timers; otherwise timers may continue and cause issues.

fix

Call heartbeat.stop() in the WebSocket onclose event handler.

affects: >=1.0.0

gotchaThe library does not automatically handle WebSocket reconnection; it only monitors and calls onTimeout.

fix

Implement your own reconnection logic inside onTimeout callback.

affects: >=1.0.0

deprecatedVersion 1.x uses a non-standard ping/pong mechanism (sending custom messages). Not all servers support this.

fix

Ensure your server sends 'pong' in response to the custom ping message, or use WebSocket built-in ping frames.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: Heartbeat is not a constructor

Using default import instead of named import.

fix

Change import to: import { Heartbeat } from 'websocket-heartbeats'

Error: Cannot find module 'websocket-heartbeats'

Package not installed or incorrect module resolution.

fix

Run 'npm install websocket-heartbeats' and ensure node_modules/websocket-heartbeats exists.

Upgrade

Version history

1.2.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

24 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/luzzif/websocket-heartbeats ↗

packagewebsocket-heartbeats ↗

homepagehttps://github.com/luzzif/websocket-heartbeats#readme ↗