Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/pladaria/reconnecting-websocket
Reconnecting WebSocket. For Web, React Native, cli (Node.js)
https://github.com/pladaria/reconnecting-websocket
Last synced: 3 days ago
JSON representation
Reconnecting WebSocket. For Web, React Native, cli (Node.js)
- Host: GitHub
- URL: https://github.com/pladaria/reconnecting-websocket
- Owner: pladaria
- License: mit
- Created: 2016-06-30T21:50:41.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2023-06-15T17:25:20.000Z (over 1 year ago)
- Last Synced: 2025-01-09T07:04:28.688Z (10 days ago)
- Language: TypeScript
- Size: 777 KB
- Stars: 1,242
- Watchers: 18
- Forks: 200
- Open Issues: 66
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- awesome-github-star - reconnecting-websocket
README
# Reconnecting WebSocket
[](https://travis-ci.org/pladaria/reconnecting-websocket)
[](https://coveralls.io/github/pladaria/reconnecting-websocket?branch=master)
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
```bash
npm install --save reconnecting-websocket
```
## Usage
### Compatible with WebSocket Browser API
So this documentation should be valid:
[MDN WebSocket API](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket).
Ping me if you find any problems. Or, even better, write a test for your case and make a pull
request :)
### Simple usage
```javascript
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`
```javascript
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);
```
```javascript
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
```javascript
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
```typescript
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
```javascript
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
```typescript
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](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket)
```typescript
binaryType: string;
bufferedAmount: number;
extensions: string;
onclose: EventListener;
onerror: EventListener;
onmessage: EventListener;
onopen: EventListener;
protocol: string;
readyState: number;
url: string;
retryCount: number;
```
### Constants
```text
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](./CONTRIBUTING.md)
## License
MIT