reconnecting-websocket

What is reconnecting-websocket?

The 'reconnecting-websocket' npm package provides a WebSocket client that automatically reconnects if the connection is lost. It is designed to be a drop-in replacement for the standard WebSocket, adding the ability to handle disconnections and reconnections seamlessly.

What are reconnecting-websocket's main functionalities?

Automatic Reconnection

This feature allows the WebSocket to automatically reconnect if the connection is lost. The code sample demonstrates how to create a new ReconnectingWebSocket instance and handle open, close, and message events.

const ReconnectingWebSocket = require('reconnecting-websocket');
const rws = new ReconnectingWebSocket('ws://example.com');
rws.addEventListener('open', () => {
  console.log('Connected');
});
rws.addEventListener('close', () => {
  console.log('Disconnected');
});
rws.addEventListener('message', (event) => {
  console.log('Message from server:', event.data);
});

Custom Reconnection Logic

This feature allows you to customize the reconnection logic by setting options such as connection timeout, maximum retries, and reconnection delays. The code sample demonstrates how to create a ReconnectingWebSocket instance with custom options.

const ReconnectingWebSocket = require('reconnecting-websocket');
const options = {
  connectionTimeout: 1000,
  maxRetries: 10,
  maxReconnectionDelay: 10000,
  minReconnectionDelay: 1000
};
const rws = new ReconnectingWebSocket('ws://example.com', [], options);
rws.addEventListener('open', () => {
  console.log('Connected');
});
rws.addEventListener('close', () => {
  console.log('Disconnected');
});
rws.addEventListener('message', (event) => {
  console.log('Message from server:', event.data);
});

Event Handling

This feature allows you to handle various WebSocket events such as open, close, message, and error. The code sample demonstrates how to add event listeners for these events.

const ReconnectingWebSocket = require('reconnecting-websocket');
const rws = new ReconnectingWebSocket('ws://example.com');
rws.addEventListener('open', () => {
  console.log('Connected');
});
rws.addEventListener('close', () => {
  console.log('Disconnected');
});
rws.addEventListener('message', (event) => {
  console.log('Message from server:', event.data);
});
rws.addEventListener('error', (error) => {
  console.error('WebSocket error:', error);
});

Other packages similar to reconnecting-websocket

ws

The 'ws' package is a simple to use, blazing fast, and thoroughly tested WebSocket client and server for Node.js. Unlike 'reconnecting-websocket', it does not provide automatic reconnection out of the box, but it offers more control and flexibility for WebSocket communication.

socket.io-client

The 'socket.io-client' package is a client library for Socket.IO, which enables real-time, bidirectional, and event-based communication. It includes automatic reconnection and other advanced features like multiplexing and broadcasting. It is more feature-rich compared to 'reconnecting-websocket' but also more complex.

websocket

The 'websocket' package provides a WebSocket client and server library for Node.js. It supports automatic reconnection through additional configuration and offers a robust set of features for WebSocket communication. It is more comprehensive compared to 'reconnecting-websocket'.

README

Reconnecting WebSocket

WebSocket that will automatically reconnect if the connection is closed.

Features

• WebSocket API compatible (same interface, Level0 and Level2 event model)
• Fully configurable
• Multi-platform (Web, ServiceWorkers, Node.js, React Native)
• Dependency free (does not depend on Window, DOM or any EventEmitter library)
• Handle connection timeouts
• Allows changing server URL between reconnections
• Buffering. Will send accumulated messages on open
• Multiple builds available (see dist folder)
• Debug mode

Install

npm install --save reconnecting-websocket

Usage

Compatible with WebSocket Browser API

So this documentation should be valid: MDN WebSocket API.

Ping me if you find any problems. Or, even better, write a test for your case and make a pull request :)

Simple usage

import ReconnectingWebSocket from 'reconnecting-websocket';

const rws = new ReconnectingWebSocket('ws://my.site.com');

rws.addEventListener('open', () => {
    rws.send('hello!');
});

Update URL

The url parameter will be resolved before connecting, possible types:

• string
• () => string
• () => Promise<string>

import ReconnectingWebSocket from 'reconnecting-websocket';

const urls = ['ws://my.site.com', 'ws://your.site.com', 'ws://their.site.com'];
let urlIndex = 0;

// round robin url provider
const urlProvider = () => urls[urlIndex++ % urls.length];

const rws = new ReconnectingWebSocket(urlProvider);

import ReconnectingWebSocket from 'reconnecting-websocket';

// async url provider
const urlProvider = async () => {
    const token = await getSessionToken();
    return `wss://my.site.com/${token}`;
};

const rws = new ReconnectingWebSocket(urlProvider);

Options

Sample with custom options

import ReconnectingWebSocket from 'reconnecting-websocket';
import WS from 'ws';

const options = {
    WebSocket: WS, // custom WebSocket constructor
    connectionTimeout: 1000,
    maxRetries: 10,
};
const rws = new ReconnectingWebSocket('ws://my.site.com', [], options);

Available options

type Options = {
    WebSocket?: any; // WebSocket constructor, if none provided, defaults to global WebSocket
    maxReconnectionDelay?: number; // max delay in ms between reconnections
    minReconnectionDelay?: number; // min delay in ms between reconnections
    reconnectionDelayGrowFactor?: number; // how fast the reconnection delay grows
    minUptime?: number; // min time in ms to consider connection as stable
    connectionTimeout?: number; // retry connect if not connected after this time, in ms
    maxRetries?: number; // maximum number of retries
    maxEnqueuedMessages?: number; // maximum number of messages to buffer until reconnection
    startClosed?: boolean; // start websocket in CLOSED state, call `.reconnect()` to connect
    debug?: boolean; // enables debug output
};

Default values

WebSocket: undefined,
maxReconnectionDelay: 10000,
minReconnectionDelay: 1000 + Math.random() * 4000,
reconnectionDelayGrowFactor: 1.3,
minUptime: 5000,
connectionTimeout: 4000,
maxRetries: Infinity,
maxEnqueuedMessages: Infinity,
startClosed: false,
debug: false,

API

Methods

constructor(url: UrlProvider, protocols?: string | string[], options?: Options)

close(code?: number, reason?: string)
reconnect(code?: number, reason?: string)

send(data: string | ArrayBuffer | Blob | ArrayBufferView)

addEventListener(type: 'open' | 'close' | 'message' | 'error', listener: EventListener)
removeEventListener(type:  'open' | 'close' | 'message' | 'error', listener: EventListener)

Attributes

More info

binaryType: string;
bufferedAmount: number;
extensions: string;
onclose: EventListener;
onerror: EventListener;
onmessage: EventListener;
onopen: EventListener;
protocol: string;
readyState: number;
url: string;
retryCount: number;

Constants

CONNECTING 0 The connection is not yet open.
OPEN       1 The connection is open and ready to communicate.
CLOSING    2 The connection is in the process of closing.
CLOSED     3 The connection is closed or couldn't be opened.

Contributing

Read here

License

MIT