extra-websocket

library0.5.3jsnpmunverified

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.

messaging

npm install extra-websocket

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · EXTRA-WEBSOCKET

extra-websocket

messagingjavascriptv0.5.3

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.

ExtraWebSocket

✓ import { ExtraWebSocket } from 'extra-websocket'

✗ const ExtraWebSocket = require('extra-websocket')

Named export, not default. The package is ESM-only (requires Node >=22).

autoReconnect

✓ import { autoReconnect } from 'extra-websocket'

✗ import autoReconnect from 'extra-websocket'

Named export, do not use default import.

State

✓ import { State } from 'extra-websocket'

✗ import State from 'extra-websocket'

Named export for the State enum.

Creates an ExtraWebSocket, connects, handles events, enables auto-reconnect and heartbeat.

import WebSocket from 'ws'; import { ExtraWebSocket, autoReconnect, startHeartbeat, State, BinaryType } from 'extra-websocket'; const createWebSocket = () => new WebSocket('wss://echo.websocket.org'); const ws = new ExtraWebSocket(createWebSocket); ws.on('open', (event) => { console.log('Connected'); ws.send('Hello'); }); ws.on('message', (event) => { console.log('Received:', event.data.toString()); }); ws.on('error', (event) => { console.error('Error:', event.message); }); ws.on('close', (event) => { console.log('Closed'); }); // Connect with abort signal const controller = new AbortController(); await ws.connect(controller.signal); // Enable auto-reconnect const stopReconnect = autoReconnect(ws, 5000); // Enable heartbeat const stopHeartbeat = startHeartbeat(ws, 30000); // Later, clean up stopReconnect(); stopHeartbeat(); await ws.close(1000, 'Goodbye');

Debug

Known issues

breakingRequires Node.js >=22 due to ESM-only packaging

fix

Upgrade Node.js to version 22 or later.

affects: >=0.5.0

gotchaExtraWebSocket extends Emitter from @blackglory/structures; standard EventTarget methods are not available

fix

Use .on() and .emit() methods instead of addEventListener().

affects: <=0.5.3

gotchaThe connect() method returns a Promise; it may reject with AbortError if the signal is aborted before connection completes

fix

Wrap connect() in try/catch or attach rejection handler.

affects: <=0.5.3

gotchaThe send() method accepts specific buffer types; passing unsupported types will throw

fix

Ensure data is string, ArrayBufferLike, Buffer, TypedArray, or DataView.

affects: <=0.5.3

deprecatedautoReonnectWithExponentialBackOff is misspelled as 'Reonnect' (double n); may be corrected in future versions

fix

Use the correctly spelled function if available, or use autoReconnect with custom retry logic.

affects: =0.5.3

Errors

Common errors & fixes

Error [ERR_REQUIRE_ESM]: require() of ES Module not supported

package is ESM-only and imported via require()

fix

Use import statements instead of require(), or run in an ESM context ("type": "module" in package.json).

TypeError: ws.on is not a function

Using node's native WebSocket or ws directly without wrapping with ExtraWebSocket

fix

Create an ExtraWebSocket instance: const ws = new ExtraWebSocket(() => new WebSocket(url));

AbortError: The operation was aborted

AbortSignal passed to connect() was aborted before connection completed

fix

Ensure signal is not already aborted before calling connect(), or handle rejection.

TypeError: ws.send is not a function

Attempting to call send on a WebSocket before connecting or after closing

fix

Wait for the 'open' event or connect() promise to resolve before calling send().

Upgrade

Version history

0.5.3latest on npm

Audit

Dependencies

wsrequiredPeer dependency; provides the underlying WebSocket implementation

@blackglory/structuresrequiredUsed for the Emitter base class

Agent activity

22 hits · last 30 days

node

OpenAI (training)

Resources

githubssh://git@github.com/BlackGlory/extra-websocket ↗

packageextra-websocket ↗

homepagehttps://github.com/BlackGlory/extra-websocket#readme ↗