README.md

Boomerang Socket

Boomerang Socket is a small JavaScript library that extends the native WebSocket API to allow automatic reconnection if a client is disconnected.

Features

• Fully mirrors the native WebSocket API.
• Automatic reconnection is RFC compliant.
• Only 7kb when minified.
• Compatible with IE11 and upwards.
• Fully tested.
• No external dependencies.

Installation

npm install boomerang-socket

Tests

npm run test

Usage

It can be used in exactly the same way as a native WebSocket, with exactly the same API.

// ES2015
import BoomerangSocket from "boomerang-socket";

// Or CommonJS
const BoomerangSocket = require("boomerang-socket");

const socket = new BoomerangSocket("wss://localhost:5000");

socket.addEventListener("open", (event) => {
  socket.send("Hello server!");
});

socket.onmessage = (event) =>  {
  console.log("Message from server: ", event.data);
};

The only difference is that the BoomerangSocket constructor accepts an additional third argument: an options config object which customises the auto-reconnect behaviour.

const socket = new BoomerangSocket("wss://localhost:8080", undefined, {
  reconnectAttempts: 25,
  reconnectDelay: 5000,
});

Options

name	type	default	description
connectTimeout	number	250	millisecond timeout before a new connection must return open
reconnect	boolean	true	enables or disables auto-reconnection
reconnectAttempts	number	Infinity	maximum number of reconnection attempts
reconnectDelay	number	3000	millisecond delay until first reconnection attempt
reconnectDelayExponent	number	1.05	exponent applied to reconnectDelay between each reconnection attempt

Contribute

We actively welcome any contributions. You can open a Pull Request here.