ws-rekanet

Simple WebSocket wrapper with reconnect logic

Motivation

The Websocket API although effective and simple doesn't provide any reconnection logic. This library aims to solve this shortcoming by providing a mechanism to shore up session_affinity between the client [a web browser] and the server. It also provides a simple queue implementation where data being sent while the connection is broken are stored, to be relayed when connection is restored.

Note that the library is just a wrapper for WebSocket class and re-exposes all it's API. It's also built on an event interface which allows it to emit native WebSocket events. Finally, it's properly tested using AVA.

installation

# yarn
yarn add ws-rekanet

# pnpm
pnpm install ws-rekanet

# npm
npm install ws-rekanet

Usage

import WSRekanet from "ws-rekanet";

const url = `ws://localhost:3001/`;
const protocols = [];
const options = {
  maxReconnectAttempts: 5,
  maxRetryAttempts: 3,
  useMessageQueue: true,
};

// initialize
const wsClient = new WSRekanet(url, protocols, options);

wsClient.on("open", () => {
  console.log("websocket connection established");
});
wsClient.on("message", (event: any) => {
  wsResponse = String(event.data);
});
wsClient.on("error", (error: any) => {
  console.log("websocket error", error);
});
wsClient.on("close", () => {
  console.log("websocket connection closed");
});

const payload = { message };
wsClient.send(JSON.stringify(payload));

API

url

Type: string

protocols

Type: string | string[] Default: []

Either a single protocol string or an array of protocol strings. These strings are used to indicate sub-protocols, so that a single server can implement multiple WebSocket sub-protocols (for example, you might want one server to be able to handle different types of interactions depending on the specified protocol). See more MDN, WhatWG#web-sockets

options

Type: object

maxReconnectAttempts

Type: number
Default: 5

Number of times it attempts to reconnect within a retry

maxRetryAttempts

Type: number
Default: 5

The maximum number of retries - how many attempts at reconnecting

useMessageQueue

Type: boolean
Default: true

Whether to store 'send' data when the connection is broken, which is to be relayed when connection is restored.

disableReconnect

Type: boolean
Default: false

Whether to disable reconnection

debugMode

Type: boolean
Default: false

Whether to run in debug mode which enables console.log output

Events

open, close, message, error

These are the same as native WebSocket events

reconnection_timeout

Indicates when reconnection attempts timeout.

reconnected

Emitted when reconnection attempt is successful - connection restored