iso-websocket

library0.5.0jsnpmunverified

Isomorphic WebSocket client with auto-reconnect, connection timeout, message queuing, and extensible retry strategy. Works in browser and Node.js. Current stable version is 0.5.0. Supports standard WebSocket API, typed events, and custom reconnection URLs. Differentiates from alternatives like ws or reconnecting-websocket by being isomorphic and providing built-in retry and queue.

messaging

npm install iso-websocket

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · ISO-WEBSOCKET

iso-websocket

messagingjavascriptv0.5.0

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.

✓ import { WS } from 'iso-websocket'

✗ import WS from 'iso-websocket'

Named export, not default. Also available as default export? Check docs. ESM only.

isomorphic-ws

✓ import { WebSocket } from 'ws'

✗ import { WS } from 'iso-websocket'

Not part of iso-websocket. This package exports WS, not WebSocket.

WebSocket

✓ import { WS } from 'iso-websocket'

✗ const WebSocket = require('iso-websocket')

CommonJS require may not work; package is ESM-only.

Basic usage: create WebSocket connection with retry and connection timeout.

import { WS } from 'iso-websocket'; const ws = new WS('ws://localhost:8080', [], { shouldRetry: (err, attempt) => attempt < 3, connectionTimeout: 5000 }); ws.addEventListener('open', () => { console.log('Connected'); ws.send('Hello'); }); ws.addEventListener('message', (e) => { console.log('Received:', e.data); }); ws.addEventListener('close', () => { console.log('Disconnected'); });

Debug

Known issues

gotchaWS constructor is required. On Node.js, it wraps ws.WebSocket; make sure ws package is installed if not using bundler.

fix

Install ws as a dependency if using Node.js without bundler.

affects: >=0.0.0

breakingVersion 0.x may have breaking changes between minor versions. Pin to exact version.

fix

Use package.json resolutions or lockfile.

affects: >=0.0.0

gotchaMessage queuing is enabled by default. If not connected, messages are queued and sent on reconnect.

fix

Set options.queueMessages: false to disable.

affects: >=0.0.0

deprecatedSome options like 'url' may change. Use constructor signature: new WS(url, protocols?, options?).

fix

Ensure you pass url first, then protocols array, then options object.

affects: >=0.5.0

Errors

Common errors & fixes

Error: Cannot find module 'ws'

Missing ws dependency on Node.js

fix

npm install ws

TypeError: WS is not a constructor

Incorrect import; using default import instead of named import

fix

import { WS } from 'iso-websocket'

TypeError: ws.send is not a function

WS instance not ready; waiting for 'open' event needed

fix

Call ws.send only after 'open' event is fired

Upgrade

Version history

0.5.0latest on npm

Audit

Dependencies

retryoptionalUsed for extensible retry strategy (node-retry)

Agent activity

15 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/hugomrdias/iso-repo ↗

packageiso-websocket ↗

homepagehttps://github.com/hugomrdias/iso-repo/tree/master/packages/iso-websocket ↗