{"id":49723,"library":"websocket-heartbeats","title":"WebSocket Heartbeats","description":"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.","status":"active","version":"1.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/luzzif/websocket-heartbeats","tags":["javascript","web","socket","heart","beat","beats","heartbeat","websocket"],"install":[{"cmd":"npm install websocket-heartbeats","lang":"bash","label":"npm"},{"cmd":"yarn add websocket-heartbeats","lang":"bash","label":"yarn"},{"cmd":"pnpm add websocket-heartbeats","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Named export only. Default import is not available.","wrong":"import Heartbeat from 'websocket-heartbeats'","symbol":"Heartbeat","correct":"import { Heartbeat } from 'websocket-heartbeats'"},{"note":"Type export; only needed if using TypeScript.","wrong":"type HeartbeatOptions = { ... }","symbol":"HeartbeatOptions","correct":"import { HeartbeatOptions } from 'websocket-heartbeats'"},{"note":"CJS destructured require. Otherwise you get an object with Heartbeat property.","wrong":"const Heartbeat = require('websocket-heartbeats')","symbol":"Heartbeat in CommonJS","correct":"const { Heartbeat } = require('websocket-heartbeats')"}],"quickstart":{"code":"import { Heartbeat } from 'websocket-heartbeats';\n\nconst ws = new WebSocket('wss://example.com/socket');\n\nconst heartbeat = new Heartbeat({\n    webSocket: ws,\n    onTimeout: () => {\n        console.error('Connection lost');\n        ws.close();\n    },\n    heartbeatInterval: 30000, // 30 seconds\n    timeoutInterval: 10000     // 10 seconds wait for pong\n});\n\nws.onopen = () => heartbeat.start();\nws.onclose = () => heartbeat.stop();\nws.onmessage = (event) => {\n    if (event.data === 'pong') heartbeat.receive();\n};","lang":"typescript","description":"Creates a Heartbeat instance, starts it on WebSocket open, stops on close, and calls receive on pong messages."},"warnings":[{"fix":"Call heartbeat.stop() in the WebSocket onclose event handler.","message":"Heartbeat.stop() must be called on WebSocket close to clear timers; otherwise timers may continue and cause issues.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Implement your own reconnection logic inside onTimeout callback.","message":"The library does not automatically handle WebSocket reconnection; it only monitors and calls onTimeout.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure your server sends 'pong' in response to the custom ping message, or use WebSocket built-in ping frames.","message":"Version 1.x uses a non-standard ping/pong mechanism (sending custom messages). Not all servers support this.","severity":"deprecated","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'1.2.0':15 'applic':67 'beat':77,78 'browser':50 'callback':35 'chat':69 'cjs':57 'cleanup':44 'configur':31 'connect':10,28 'depend':61 'design':48 'detect':27 'disconnect':46 'environ':53 'esm':55 'extern':60 'frame':25 'handl':43 'heart':76 'heartbeat':2,12,79 'implement':40 'interv':32 'invok':33 'iot':72 'javascript':73 'latest':18 'librari':6 'lightweight':4 'like':68 'loss':29 'manual':39 'monitor':8 'node.js':52 'period':22 'ping':13,24 'real':65 'real-tim':64 'releas':20 'scenario':47 'send':23 'socket':75 'stabl':19 'suitabl':62 'support':58 'time':66 'timeout':37 'timer':41 'trade':70 'typescript':5 'unlik':38 'use':11 'version':14 'web':74 'websocket':1,9,80","created_at":"2026-06-07T17:03:16.903118+00:00","updated_at":"2026-06-07T17:03:16.903118+00:00","problems":[{"fix":"Change import to: import { Heartbeat } from 'websocket-heartbeats'","cause":"Using default import instead of named import.","error":"TypeError: Heartbeat is not a constructor"},{"fix":"Run 'npm install websocket-heartbeats' and ensure node_modules/websocket-heartbeats exists.","cause":"Package not installed or incorrect module resolution.","error":"Error: Cannot find module 'websocket-heartbeats'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/luzzif/websocket-heartbeats#readme","github":"https://github.com/luzzif/websocket-heartbeats","docs":null,"changelog":null,"pypi":null,"npm":"websocket-heartbeats","openapi_spec":null,"status_page":null,"smithery":null,"categories":["messaging"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}