{"id":49529,"library":"tools-websocket","title":"tools-websocket","description":"A JavaScript WebSocket utility library that provides heartbeat, auto-reconnection, and message retransmission for browser environments. Current stable version is 1.0.6. It was extracted from the tools-vue3 library to be used standalone in plain HTML/JS or any JavaScript project. Key differentiators: built-in heartbeat mechanism to detect stale connections, automatic reconnection with customizable intervals, and reliable message retransmission ensuring messages are not lost during disconnection. It ships with TypeScript type definitions and is ESM-only.","status":"active","version":"1.0.6","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","typescript","tools","websocket"],"install":[{"cmd":"npm install tools-websocket","lang":"bash","label":"npm"},{"cmd":"yarn add tools-websocket","lang":"bash","label":"yarn"},{"cmd":"pnpm add tools-websocket","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"ESM-only package; CommonJS require will fail.","wrong":"const WebSocketTool = require('tools-websocket')","symbol":"WebSocketTool","correct":"import { WebSocketTool } from 'tools-websocket'"},{"note":"Factory function to create a WebSocket instance with default options.","symbol":"createWebSocket","correct":"import { createWebSocket } from 'tools-websocket'"},{"note":"TypeScript type for configuration options.","symbol":"WebSocketOptions","correct":"import type { WebSocketOptions } from 'tools-websocket'"}],"quickstart":{"code":"import { createWebSocket } from 'tools-websocket';\n\nconst ws = createWebSocket('wss://example.com/socket', {\n  heartbeatInterval: 30000,\n  reconnectInterval: 5000,\n  maxReconnectAttempts: 10,\n  onMessage: (data) => {\n    console.log('Received:', data);\n  },\n  onReconnect: (attempt) => {\n    console.log(`Reconnecting attempt ${attempt}`);\n  }\n});\n\nws.send('Hello server!');\n\n// Later: close connection\nws.close();","lang":"typescript","description":"Shows how to create a WebSocket connection with heartbeat, auto-reconnect, and a message handler."},"warnings":[{"fix":"Use import syntax or configure your project to handle ESM (e.g., type: 'module' in package.json, or use dynamic import()).","message":"The package is ESM-only starting from v1.0.0. CommonJS require() will throw an error.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Set heartbeatInterval: 0 to disable, or configure heartbeatMessage to send a custom message and listen for a response.","message":"The heartbeat feature requires the server to respond to a ping/pong mechanism. If the server does not support WebSocket ping/pong frames, you must disable heartbeat or provide a custom heartbeat message.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Implement idempotency keys on the server side or limit retransmission count.","message":"Message retransmission may cause duplicate messages if the server processes the same message twice on reconnection.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'1.0.6':25 'auto':13 'auto-reconnect':12 'automat':57 'browser':19 'built':49 'built-in':48 'connect':56 'current':21 'customiz':60 'definit':78 'detect':54 'differenti':47 'disconnect':72 'ensur':66 'environ':20 'esm':82 'esm-on':81 'extract':28 'heartbeat':11,51 'html/js':41 'interv':61 'javascript':5,44,84 'key':46 'librari':8,34 'lost':70 'mechan':52 'messag':16,64,67 'plain':40 'project':45 'provid':10 'reconnect':14,58 'reliabl':63 'retransmiss':17,65 'ship':74 'stabl':22 'stale':55 'standalon':38 'tool':2,32,86 'tools-vue3':31 'tools-websocket':1 'type':77 'typescript':76,85 'use':37 'util':7 'version':23 'vue3':33 'websocket':3,6,87","created_at":"2026-06-07T17:02:13.602080+00:00","updated_at":"2026-06-07T17:02:13.602080+00:00","problems":[{"fix":"Add \"type\": \"module\" to your package.json or rename file to .mjs, or use dynamic import().","cause":"Trying to use import in a CommonJS file without proper configuration.","error":"SyntaxError: Cannot use import statement outside a module"},{"fix":"Use a WebSocket polyfill like 'ws' and set global.WebSocket before importing tools-websocket.","cause":"In Node.js environments where the native WebSocket API is not available.","error":"ReferenceError: WebSocket is not defined"}],"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://gitee.com/veigarchen","github":null,"docs":null,"changelog":null,"pypi":null,"npm":"tools-websocket","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}}