{"id":47541,"library":"extra-websocket","title":"extra-websocket","description":"A wrapper around the ws WebSocket library providing an event emitter interface, automatic reconnection with optional exponential backoff and jitter, heartbeat support, and promise-based connect/close. Currently at version 0.5.3, requires Node.js >=22 and peer dependency ws@^8.7.0. Ships TypeScript type definitions. Differentiators include a clean Emitter-based API, auto-reconnect strategies, and built-in ping/pong heartbeat.","status":"active","version":"0.5.3","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/BlackGlory/extra-websocket","tags":["javascript","typescript"],"install":[{"cmd":"npm install extra-websocket","lang":"bash","label":"npm"},{"cmd":"yarn add extra-websocket","lang":"bash","label":"yarn"},{"cmd":"pnpm add extra-websocket","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency; provides the underlying WebSocket implementation","package":"ws","optional":false},{"reason":"Used for the Emitter base class","package":"@blackglory/structures","optional":false}],"imports":[{"note":"Named export, not default. The package is ESM-only (requires Node >=22).","wrong":"const ExtraWebSocket = require('extra-websocket')","symbol":"ExtraWebSocket","correct":"import { ExtraWebSocket } from 'extra-websocket'"},{"note":"Named export, do not use default import.","wrong":"import autoReconnect from 'extra-websocket'","symbol":"autoReconnect","correct":"import { autoReconnect } from 'extra-websocket'"},{"note":"Named export for the State enum.","wrong":"import State from 'extra-websocket'","symbol":"State","correct":"import { State } from 'extra-websocket'"}],"quickstart":{"code":"import WebSocket from 'ws';\nimport { ExtraWebSocket, autoReconnect, startHeartbeat, State, BinaryType } from 'extra-websocket';\n\nconst createWebSocket = () => new WebSocket('wss://echo.websocket.org');\nconst ws = new ExtraWebSocket(createWebSocket);\n\nws.on('open', (event) => {\n  console.log('Connected');\n  ws.send('Hello');\n});\nws.on('message', (event) => {\n  console.log('Received:', event.data.toString());\n});\nws.on('error', (event) => {\n  console.error('Error:', event.message);\n});\nws.on('close', (event) => {\n  console.log('Closed');\n});\n\n// Connect with abort signal\nconst controller = new AbortController();\nawait ws.connect(controller.signal);\n\n// Enable auto-reconnect\nconst stopReconnect = autoReconnect(ws, 5000);\n\n// Enable heartbeat\nconst stopHeartbeat = startHeartbeat(ws, 30000);\n\n// Later, clean up\nstopReconnect();\nstopHeartbeat();\nawait ws.close(1000, 'Goodbye');\n","lang":"typescript","description":"Creates an ExtraWebSocket, connects, handles events, enables auto-reconnect and heartbeat."},"warnings":[{"fix":"Upgrade Node.js to version 22 or later.","message":"Requires Node.js >=22 due to ESM-only packaging","severity":"breaking","affected_versions":">=0.5.0"},{"fix":"Use .on() and .emit() methods instead of addEventListener().","message":"ExtraWebSocket extends Emitter from @blackglory/structures; standard EventTarget methods are not available","severity":"gotcha","affected_versions":"<=0.5.3"},{"fix":"Wrap connect() in try/catch or attach rejection handler.","message":"The connect() method returns a Promise; it may reject with AbortError if the signal is aborted before connection completes","severity":"gotcha","affected_versions":"<=0.5.3"},{"fix":"Ensure data is string, ArrayBufferLike, Buffer, TypedArray, or DataView.","message":"The send() method accepts specific buffer types; passing unsupported types will throw","severity":"gotcha","affected_versions":"<=0.5.3"},{"fix":"Use the correctly spelled function if available, or use autoReconnect with custom retry logic.","message":"autoReonnectWithExponentialBackOff is misspelled as 'Reonnect' (double n); may be corrected in future versions","severity":"deprecated","affected_versions":"=0.5.3"}],"env_vars":null,"search_vec":"'0.5.3':34 '22':37 '8.7.0':42 'api':54 'around':6 'auto':56 'auto-reconnect':55 'automat':16 'backoff':21 'base':29,53 'built':61 'built-in':60 'clean':50 'connect/close':30 'current':31 'definit':46 'depend':40 'differenti':47 'emitt':14,52 'emitter-bas':51 'event':13 'exponenti':20 'extra':2 'extra-websocket':1 'heartbeat':24,64 'includ':48 'interfac':15 'javascript':65 'jitter':23 'librari':10 'node.js':36 'option':19 'peer':39 'ping/pong':63 'promis':28 'promise-bas':27 'provid':11 'reconnect':17,57 'requir':35 'ship':43 'strategi':58 'support':25 'type':45 'typescript':44,66 'version':33 'websocket':3,9 'wrapper':5 'ws':8,41","created_at":"2026-06-07T16:52:02.541295+00:00","updated_at":"2026-06-07T16:52:02.541295+00:00","problems":[{"fix":"Use import statements instead of require(), or run in an ESM context (\"type\": \"module\" in package.json).","cause":"package is ESM-only and imported via require()","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module not supported"},{"fix":"Create an ExtraWebSocket instance: const ws = new ExtraWebSocket(() => new WebSocket(url));","cause":"Using node's native WebSocket or ws directly without wrapping with ExtraWebSocket","error":"TypeError: ws.on is not a function"},{"fix":"Ensure signal is not already aborted before calling connect(), or handle rejection.","cause":"AbortSignal passed to connect() was aborted before connection completed","error":"AbortError: The operation was aborted"},{"fix":"Wait for the 'open' event or connect() promise to resolve before calling send().","cause":"Attempting to call send on a WebSocket before connecting or after closing","error":"TypeError: ws.send is not a function"}],"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/BlackGlory/extra-websocket#readme","github":"ssh://git@github.com/BlackGlory/extra-websocket","docs":null,"changelog":null,"pypi":null,"npm":"extra-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}}