@unless.com/wsmodule v1.3.3

WSModule

WSModule is a utility module designed for managing WebSocket (WS) connections. It's a robust module that includes features like automatic reconnection with exponential backoff, ping handling, and activity-based connection handling.

Features:

• Automatic reconnection on connection loss with exponential backoff.
• Heartbeat via the ping mechanism to ensure connection validity.
• Updates the WebSocket connection with specific identifiers.
• Tracks idle state to optimize resource usage.
• Streamlined error handling and callbacks.

Installation

npm -i @unless.com/wsmodule # npm

yarn add @unless.com/wsmodule # yarn

pnpm add @unless.com/wsmodule # pnpm

Importing:

import { WSModule } from "@unless.com/wsmodule";

Usage:

1. Initialization:

const wsModule = new WSModule({
  handleMessageCallback: yourMessageCallbackFunction,
  handleWSErrorCallback: yourErrorCallbackFunction,
  endpoint: new URL("wss://your-websocket-url.com"),
});

2. Connecting to WebSocket:

await wsModule.connect();

3. Disconnection from WebSocket:

wsModule.disconnect();

4. Sending a ping:

wsModule.ping();

5. Updating the connection with specific identifiers:

wsModule.updateConnection({
  visitorId: "someId",
  accountId: "accountId",
  websiteId: "websiteId",
  visitId: "visitId",
});

6. Handling Activity (useful to reset idle timeouts and possibly re-establish a ping cycle):

wsModule.onActivity();

Configuration:

You can configure the following properties when initializing WSModule:

• handleMessageCallback: A function that handles incoming WebSocket messages.
• handleWSErrorCallback: A function called when there's an error with the WebSocket.
• endpoint: The WebSocket URL you want to connect to.
• maxConnectionRetries (optional): Maximum number of reconnection attempts.
• initialConnectionRetryDelay (optional): Initial delay before trying to reconnect.
• pingTimeout (optional): Timeout for the ping operation.
• pingInterval (optional): Interval to send pings.
• idleDuration (optional): Duration to determine idleness.