Registry / messaging / awesome-websocket

awesome-websocket

library0.0.25jsnpmunverified

A WebSocket wrapper that adds reconnection, host failover/hunting, keep-alive, and automatic JSON serialization. Current stable version 0.0.25 is a beta-quality release with no recent updates. Unlike native WebSocket or simple wrappers, it provides built-in client-side failover across multiple hosts and automatic message queueing during reconnection. Supports browserify for bundling and has QUnit tests. Limited browser testing (Chrome, Safari).

messaging

npm install awesome-websocket

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · AWESOME-WEBSOCKET

awesome-websocket

messagingjavascriptv0.0.25

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.

AwesomeWebSocket

✓ import { AwesomeWebSocket } from 'awesome-websocket'

✗ const AwesomeWebSocket = require('awesome-websocket')

Package is ESM via browserify but also ships a UMD bundle in test/www/js. Use named import as shown.

ReconnectingWebSocket

✓ import { ReconnectingWebSocket } from 'awesome-websocket'

ReconnectingWebSocket is an internal class exposed via browserify as a separate exported symbol.

default export

✓ import AwesomeWebSocket from 'awesome-websocket'

✗ import { default as AwesomeWebSocket } from 'awesome-websocket'

The package has both a named export and a default export. Prefer default import for direct usage.

Creates an AwesomeWebSocket with failover hosts, auto-reconnect, keep-alive, and object sending.

import AwesomeWebSocket from 'awesome-websocket'; const ws = new AwesomeWebSocket('ws://localhost:8080', ['ws://backup:8080']); ws.onopen = () => { console.log('Connected!'); ws.send({ type: 'hello', payload: 'world' }); }; ws.onmessage = (event) => { console.log('Message:', event.data); }; ws.onclose = () => { console.log('Disconnected, will auto-reconnect...'); }; ws.keepAlive(30000, 'ping');

Debug

Known issues

breakingConstructor signature differs from native WebSocket: accepts array of URLs for failover.

fix

Use new AwesomeWebSocket(url, [failoverUrls]) instead of just url.

affects: >=0.0

deprecatedThe entire package is in maintenance mode with no updates since 2015. Consider using modern alternatives like reconnecting-websocket.

fix

Migrate to actively maintained libraries (e.g., reconnecting-websocket).

affects: >=0.0

gotchasend() method automatically JSON-serializes objects, but does not parse incoming messages; you must JSON.parse manually.

fix

Wrap onmessage handler with JSON.parse(event.data) for object messages.

affects: >=0.0

gotchaHunting (failover) does not reconnect back to primary host after fallback; once switched to backup, stays there.

fix

Monitor manually or implement custom rebalancing logic.

affects: >=0.0

gotchaNo TypeScript definitions; all types are any.

fix

Create .d.ts file manually or use // @ts-ignore.

affects: >=0.0

Errors

Common errors & fixes

Uncaught TypeError: AwesomeWebSocket is not a constructor

Using default import incorrectly or package not bundled correctly.

fix

Ensure you use import AwesomeWebSocket from 'awesome-websocket' or use the browserified bundle at test/www/js/awesome-websocket.js.

Cannot find module 'awesome-websocket'

Package not installed or not in node_modules.

fix

Run npm install awesome-websocket and bundle with browserify.

ws.send is not a function

Calling send() before connection is established.

fix

Call send() only after onopen event fires.

Upgrade

Version history

0.0.25latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

32 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/glg/awesome-websocket ↗

packageawesome-websocket ↗

homepagehttps://github.com/glg/awesome-websocket ↗