Registry / messaging / resilient-websocket

resilient-websocket

library2.0.0jsnpmunverified

A TypeScript-based WebSocket client wrapper that provides automatic reconnection and ping/pong support with a familiar event-driven API. The library is currently at version 2.0.0 and is actively maintained. It differentiates itself by offering a straightforward interface similar to native WebSocket, automatic handling of JSON serialization/deserialization, and configurable heartbeat functionality. Ideal for real-time applications requiring robust network resilience.

messaging

npm install resilient-websocket

package ↗

INSTALL

IMPORT

SIG · RESILIENT-WEBSOCKE

resilient-websocket

messagingjavascriptv2.0.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.

ResilientWebSocket

✓ import ResilientWebSocket from 'resilient-websocket'

✗ const ResilientWebSocket = require('resilient-websocket')

Library is ESM-only; use import syntax.

WebSocketEvent

✓ import { WebSocketEvent } from 'resilient-websocket'

✗ const { WebSocketEvent } = require('resilient-websocket')

WebSocketEvent is a named export; CommonJS require-style destructuring is not supported.

ResilientWebSocket

✓ import { default as ResilientWebSocket } from 'resilient-websocket'

Default import is preferred; named default import works but is unnecessary.

This example shows how to create a ResilientWebSocket client with JSON serialization and ping/pong enabled, and listen for connection, message, close, and error events.

import ResilientWebSocket, { WebSocketEvent } from 'resilient-websocket'; const url = process.env.WS_URL ?? 'wss://echo.websocket.org'; const opts = { autoJsonify: true, pingEnabled: true }; const rSock = new ResilientWebSocket(url, opts); rSock.on(WebSocketEvent.CONNECTION, () => { console.log('Connected'); }); rSock.on(WebSocketEvent.MESSAGE, (message) => { console.log('Received:', message); rSock.send({ response: 'echo' }); }); rSock.on(WebSocketEvent.CLOSE, (code, reason) => { console.log('Connection closed', code, reason); }); rSock.on(WebSocketEvent.ERROR, (error) => { console.error('Error:', error); });

Debug

Known issues

gotchaIf 'pingEnabled' is false, the library does not automatically detect disconnections; you may need to implement your own heartbeat or rely on TCP keepalive.

fix

Set 'pingEnabled: true' or implement custom heartbeat.

affects: >=2.0

gotchaThe 'autoJsonify' option causes send() to accept only objects (or strings if you want raw text). Sending non-JSON-serializable values (e.g., ArrayBuffer) will throw.

fix

Set 'autoJsonify: false' to send raw strings or binary data, or ensure you only send JSON-friendly data.

affects: >=2.0

breakingIn v2.0.0, the library switched from CommonJS to ESM; direct require() will fail.

fix

Use import syntax instead of require().

affects: >=2.0.0

deprecatedThe 'ReconnectEvent' enum is deprecated and replaced by 'WebSocketEvent.RECONNECT'.

fix

Use WebSocketEvent.RECONNECT instead.

affects: >=2.0.0

gotchaThe constructor does not automatically connect; you must call .connect() or listen for 'CONNECTION' event after instantiation.

fix

Call rSock.connect() or rely on event listener to trigger connection.

affects: >=2.0

deprecatedThe 'maxReconnectAttempts' option defaults to Infinity, which can cause infinite reconnection loops in production.

fix

Set a finite 'maxReconnectAttempts' (e.g., 10) in options.

affects: >=2.0

Errors

Common errors & fixes

TypeError: ResilientWebSocket is not a constructor

Using require() on an ESM-only module in a CommonJS environment.

fix

Change to 'import ResilientWebSocket from 'resilient-websocket'' and ensure your project uses ESM or dynamic import.

Uncaught TypeError: rSock.send is not a function

Attempting to use send() before the connection is established.

fix

Only call send() inside the 'CONNECTION' event handler or after connect() resolves.

Error: Connection refused: no further information

The WebSocket server is unreachable or the URL is invalid.

fix

Verify the URL (e.g., ws:// or wss://) and that the server is running.

Upgrade

Version history

2.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

13 hits · last 30 days

node

OpenAI (training)

Resources

packageresilient-websocket ↗