# reconnecting-websocket

> Reconnecting WebSocket

Latest version **4.4.0** (published 2020-02-07) · MIT license · 0 weekly downloads

## Install

```sh
npm install reconnecting-websocket
pnpm add reconnecting-websocket
yarn add reconnecting-websocket
bun add reconnecting-websocket
```

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 4.4.0 |
| Published | 2020-02-07 |
| First published | 2016-06-28 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 152 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1314 |
| Author | Pedro Ladaria |
| Maintainers | pladaria |
| Keywords | websocket, client, reconnecting, reconnection, reconnect, forever, persistent, forever, automatic |

## Links

- npm: https://www.npmjs.com/package/reconnecting-websocket
- Repository: https://github.com/pladaria/reconnecting-websocket
- Homepage: https://github.com/pladaria/reconnecting-websocket#readme
- Issues: https://github.com/pladaria/reconnecting-websocket/issues
- npm.io page: https://npm.io/package/reconnecting-websocket

## Alternatives

- [@opentelemetry/exporter-zipkin](https://npm.io/package/@opentelemetry/exporter-zipkin.md) — 14.8M weekly downloads
- [pusher-js](https://npm.io/package/pusher-js.md) — 2.0M weekly downloads
- [browserify](https://npm.io/package/browserify.md) — 1.7M weekly downloads
- [sqs-consumer](https://npm.io/package/sqs-consumer.md) — 1.7M weekly downloads
- [@sanity/eventsource](https://npm.io/package/@sanity/eventsource.md) — 930.8K weekly downloads

## Recent versions

- 4.4.0 (latest) — 2020-02-07
- 3.0.1 (beta) — 2016-10-18
- 4.3.0 — 2020-01-31
- 4.2.0 — 2019-08-29
- 4.1.10 — 2018-10-19
- 4.1.9 — 2018-10-16
- 4.1.8 — 2018-10-13
- 4.1.7 — 2018-10-12
- 4.1.6 — 2018-10-12
- 4.1.5 — 2018-10-06
- 4.1.4 — 2018-10-06
- 4.1.3 — 2018-10-05
- 4.1.2 — 2018-10-04
- 4.1.1 — 2018-10-01
- 4.1.0 — 2018-09-29
- … 27 more at https://npm.io/package/reconnecting-websocket/versions

## README

# Reconnecting WebSocket

[![Build Status](https://travis-ci.org/pladaria/reconnecting-websocket.svg?branch=master)](https://travis-ci.org/pladaria/reconnecting-websocket)
[![Coverage Status](https://coveralls.io/repos/github/pladaria/reconnecting-websocket/badge.svg?branch=master&v=1)](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<string>`

```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

---
_Source: https://npm.io/package/reconnecting-websocket · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._