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

1npm 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

1import ReconnectingWebSocket from 'reconnecting-websocket';
2
3const rws = new ReconnectingWebSocket('ws://my.site.com');
4
5rws.addEventListener('open', () => {
6    rws.send('hello!');
7});

Update URL

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

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

1import ReconnectingWebSocket from 'reconnecting-websocket';
2
3const urls = ['ws://my.site.com', 'ws://your.site.com', 'ws://their.site.com'];
4let urlIndex = 0;
5
6// round robin url provider
7const urlProvider = () => urls[urlIndex++ % urls.length];
8
9const rws = new ReconnectingWebSocket(urlProvider);

1import ReconnectingWebSocket from 'reconnecting-websocket';
2
3// async url provider
4const urlProvider = async () => {
5    const token = await getSessionToken();
6    return `wss://my.site.com/${token}`;
7};
8
9const rws = new ReconnectingWebSocket(urlProvider);

Options

Sample with custom options

1import ReconnectingWebSocket from 'reconnecting-websocket';
2import WS from 'ws';
3
4const options = {
5    WebSocket: WS, // custom WebSocket constructor
6    connectionTimeout: 1000,
7    maxRetries: 10,
8};
9const rws = new ReconnectingWebSocket('ws://my.site.com', [], options);

Available options

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

Default values

1WebSocket: undefined,
2maxReconnectionDelay: 10000,
3minReconnectionDelay: 1000 + Math.random() * 4000,
4reconnectionDelayGrowFactor: 1.3,
5minUptime: 5000,
6connectionTimeout: 4000,
7maxRetries: Infinity,
8maxEnqueuedMessages: Infinity,
9startClosed: false,
10debug: false,

API

Methods

1constructor(url: UrlProvider, protocols?: string | string[], options?: Options)
2
3close(code?: number, reason?: string)
4reconnect(code?: number, reason?: string)
5
6send(data: string | ArrayBuffer | Blob | ArrayBufferView)
7
8addEventListener(type: 'open' | 'close' | 'message' | 'error', listener: EventListener)
9removeEventListener(type:  'open' | 'close' | 'message' | 'error', listener: EventListener)

Attributes

More info

1binaryType: string;
2bufferedAmount: number;
3extensions: string;
4onclose: EventListener;
5onerror: EventListener;
6onmessage: EventListener;
7onopen: EventListener;
8protocol: string;
9readyState: number;
10url: string;
11retryCount: number;

Constants

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

Contributing

Read here

License

MIT