Registry / messaging / tiny-resilient-websocket

tiny-resilient-websocket

library0.2.0jsnpmunverified

A tiny (~6 KB minified), dependency-free WebSocket client with exponential-backoff reconnect, heartbeats, outgoing queue, and pluggable transports. Version 0.2.0 is the latest stable release (no major updates yet). Supports browsers, Node.js (with the 'ws' package), Deno, Bun, and edge runtimes. Key differentiators: zero runtime dependencies, full TypeScript types, dynamic URL provider for token refresh, and a first-class state machine with both hooks and typed event emitter API. Ideal for production WebSocket connections requiring resilience and minimal bundle size.

messaging

npm install tiny-resilient-websocket

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · TINY-RESILIENT-WEB

tiny-resilient-websocket

messagingjavascriptv0.2.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.

ResilientWebSocketClient

✓ import { ResilientWebSocketClient } from 'resilient-websocket'

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

ESM-only; no CommonJS export is provided.

ResilientWebSocketClient

✓ import { ResilientWebSocketClient } from 'resilient-websocket'

Default import does not exist; must use named import.

type ResilientWebSocketOptions

✓ import type { ResilientWebSocketOptions } from 'resilient-websocket'

TypeScript users can import types directly for configuration objects.

type WebSocketFactory

✓ import type { WebSocketFactory } from 'resilient-websocket'

Useful when defining a custom WebSocket factory function.

Creates a ResilientWebSocketClient with a static URL, hooks for open/close events, and exponential-backoff reconnect policy, then initiates the connection.

import { ResilientWebSocketClient } from 'resilient-websocket'; const client = new ResilientWebSocketClient({ url: process.env.WS_URL ?? 'wss://echo.websocket.org', onConnected: (socket) => { socket.send(JSON.stringify({ type: 'ping' })); }, hooks: { onMessage: (data) => console.log('Received:', data), onClose: (event, willReconnect) => console.log('Closed', event.code, { willReconnect }), }, policy: { initialReconnectDelayMs: 500, maxReconnectDelayMs: 30_000, maxReconnectDurationMs: 5 * 60_000, }, }); await client.connect(); // Later, to close: // client.disconnect();

Debug

Known issues

gotchaThe `webSocketFactory` option is required in Node.js if you want to use the `ws` package with custom options (e.g., headers). Otherwise, the library tries to use the global WebSocket, which does not exist in Node.js and will throw.

fix

Always pass a `webSocketFactory` that creates a WebSocket from the 'ws' package when running in Node.js.

affects: >=0.0.0

gotchaThe `urlProvider` async function is called on every reconnect attempt; if it throws, the client will not retry until next policy interval. Ensure the provider catches errors and returns a valid URL or rejects to stop reconnection.

fix

Wrap the provider in try-catch and handle errors gracefully, or return a fallback URL.

affects: >=0.0.0

gotchaThe outgoing message queue can cause memory leaks if `maxQueuedMessages` is not set appropriately and the connection stays down for a long time. Default is 1000 messages.

fix

Set `maxQueuedMessages` to a reasonable limit, or disable queueing with `queueOutgoingWhileDisconnected: false`.

affects: >=0.0.0

gotchaHeartbeat pong timeout uses a single timer; if the server sends pongs for old pings, the client may incorrectly assume the connection is stale. Implement your own message tracking if needed.

fix

Set a generous pong timeout, or handle application-level pings separately.

affects: >=0.0.0

Errors

Common errors & fixes

ReferenceError: WebSocket is not defined

Running in Node.js without providing a webSocketFactory that uses the 'ws' package.

fix

Pass a webSocketFactory option: webSocketFactory: (url, protocols) => new (require('ws'))(url, protocols, { headers: {...} })

TypeError: resilient_websocket_1.ResilientWebSocketClient is not a constructor

Using default import instead of named import.

fix

Use import { ResilientWebSocketClient } from 'resilient-websocket';

InvalidStateError: Failed to execute 'send' on 'WebSocket': still in CONNECTING state.

Calling client.send() before the connection is established (client.connect() may not have resolved or the socket is not open yet).

fix

Use the `onConnected` hook to send the first messages, or wait for the connect() promise to resolve and then check client.state === 'open' before sending.

ResilientWebSocketClient: URL is required

Neither `url` nor `urlProvider` was provided in the options.

fix

Provide either a static `url` string or an async `urlProvider` function.

Upgrade

Version history

0.2.0latest on npm

Audit

Dependencies

wsoptionalRequired for Node.js environments; the browser has a built-in WebSocket.

Agent activity

21 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/your-org/resilient-websocket ↗

packagetiny-resilient-websocket ↗

homepagehttps://github.com/your-org/resilient-websocket#readme ↗