Features

• Lightweight & Standalone: No dependencies, 2.5 kB minified & gzipped.
• Browser-native: Utilizes native WebSocket API, offers direct access to the underlying connection.
• Smart Reconnect: Optional auto-reconnect and message buffering.
• Easy Setup: Optional builder class for quick initialization.
• Well-Tested: High test coverage, well-documented for extensibility.
• Module Support: Supports CommonJS and ES6 modules.

Installation

Install websocket-ts with npm:

npm install websocket-ts

Quickstart

This example creates a WebSocket with message buffering and automatic reconnection. The created websocket will echo back any received messages. It will buffer messages when disconnected and attempt to reconnect every 1 second.

import {
  ArrayQueue,
  ConstantBackoff,
  Websocket,
  WebsocketBuilder,
  WebsocketEvent,
} from "websocket-ts";

// Initialize WebSocket with buffering and 1s reconnection delay
const ws = new WebsocketBuilder("ws://localhost:8080")
  .withBuffer(new ArrayQueue())           // buffer messages when disconnected
  .withBackoff(new ConstantBackoff(1000)) // retry every 1s
  .build();

// Function to output & echo received messages
const echoOnMessage = (i: Websocket, ev: MessageEvent) => {
  console.log(`received message: ${ev.data}`);
  i.send(`echo: ${ev.data}`);
};

// Add event listeners
ws.addEventListener(WebsocketEvent.open, () => console.log("opened!"));
ws.addEventListener(WebsocketEvent.close, () => console.log("closed!"));
ws.addEventListener(WebsocketEvent.message, echoOnMessage);

Usage

This section demonstrates how to use websocket-ts in your project using the provided WebsocketBuilder class.

For a more detailed description of the API, please refer to the API Documentation.

Initialization

Create a new instance with the WebsocketBuilder:

const ws = new WebsocketBuilder("ws://localhost:42421").build();

Events

There are six events you can listen for:

| Event | Description | |---|---| | open | Connection opened | | close | Connection closed | | error | An error occurred | | message | Message received | | retry | Reconnect attempt | | reconnect | Successful reconnect |

You can use either WebsocketEvent.open or the string "open" when registering listeners.

Add Event Listeners

Event listeners receive the websocket instance (i) and the triggering event (ev) as arguments.

const ws = new WebsocketBuilder("ws://localhost:42421")
  .onOpen((i, ev) => console.log("opened"))
  .onClose((i, ev) => console.log("closed"))
  .onError((i, ev) => console.log("error"))
  .onMessage((i, ev) => console.log("message"))
  .onRetry((i, ev) => console.log("retry"))
  .onReconnect((i, ev) => console.log("reconnect"))
  .build();

Remove Event Listeners

To unregister a specific event listener, use removeEventListener:

let ws: Websocket
/* ... */
ws.removeEventListener(WebsocketEvent.open, openEventListener);

Send Message

Use the send method to send a message to the server:

let ws: Websocket;
/* ... */
ws.send("Hello World!");

Reconnect & Backoff (Optional)

To automatically reconnect after a disconnection, provide a Backoff strategy. This controls the delay between reconnection attempts. There are three built-in Backoff implementations, or you can create your own by implementing the Backoff interface. If no backoff is provided, the websocket will not attempt to reconnect.

ConstantBackoff

ConstantBackoff uses a fixed delay between each reconnection attempt. To set a constant 1-second wait time, use:

const ws = new WebsocketBuilder("ws://localhost:42421")
  .withBackoff(new ConstantBackoff(1000)) // 1000ms = 1s
  .build();

LinearBackoff

LinearBackoff increases the delay between reconnection attempts linearly, up to an optional maximum. For example, to start with a 0-second delay and increase by 10 seconds for each retry, capping at 60 seconds, use:

const ws = new WebsocketBuilder("ws://localhost:42421")
  .withBackoff(new LinearBackoff(0, 10000, 60000)) // 0ms, 10s, 20s, 30s, 40s, 50s, 60s
  .build();

ExponentialBackoff

ExponentialBackoff doubles the delay between each reconnection attempt, up to a specified maximum. This approach is inspired by the binary exponential backoff algorithm commonly used in networking. For example, to use a base of 1000ms with a maximum exponent of 6:

const ws = new WebsocketBuilder("ws://localhost:42421")
  .withBackoff(new ExponentialBackoff(1000, 6)) // 1s, 2s, 4s, 8s, 16s, 32s, 64s
  .build();

Buffer (Optional)

To buffer outgoing messages when the websocket is disconnected, provide a Queue. The queue temporarily stores messages and sends them in order when the websocket (re)connects. Two built-in Queue implementations are available, or you can create your own by implementing the Queue interface. If no queue is provided, messages won't be buffered.

RingQueue

RingQueue is a fixed-capacity, first-in-first-out (FIFO) queue. When it reaches capacity, the oldest element is removed to make room for new ones. For instance, to set up a RingQueue with a 100-element capacity:

const ws = new WebsocketBuilder("ws://localhost:42421")
  .withBuffer(new RingQueue(100))
  .build();

ArrayQueue

ArrayQueue is an unbounded first-in-first-out (FIFO) queue. To use an ArrayQueue:

const ws = new WebsocketBuilder("ws://localhost:42421")
  .withBuffer(new ArrayQueue())
  .build();

URL Provider (Optional)

By default, the URL is a static string. To use a different URL between connection attempts, provide a function instead. The function is called on each connection attempt, including the initial one and any retries. This enables use cases like load balancing, auth token rotation, and failover.

const ws = new WebsocketBuilder(() => `ws://localhost:42421?token=${getToken()}`)
  .withBackoff(new ConstantBackoff(1000))
  .build();

Build & Tests

To compile the project, run npm run build.

To run tests, use npm run test.