@solncebro/websocket-engine

Reliable WebSocket client for Node.js with automatic reconnection, ping/pong heartbeat, typed messages, optional authentication phase, and request/response pattern.

Installation

yarn add @solncebro/websocket-engine

npm install @solncebro/websocket-engine

Features

• Automatic reconnection — exponential backoff with jitter; fast reconnect for specific close codes (1001, 1006, 1011–1014)
• Heartbeat — TCP ping/pong by default; or application-level JSON ping (e.g. Bybit { op: 'ping' })
• Connection timeout — handshake timeout with retry
• Auth phase — optional onOpen async callback for authentication before the connection is considered ready
• Send — ws.sendToConnectedSocket(data) for outbound messages
• Request/response — ws.waitForMessage(predicate, timeout) to await a specific incoming message by any criteria (e.g. reqId)
• Typed messages — optional parseMessage for type-safe payloads
• Notifications — onNotify callback for alerts on connection issues and max retries exceeded

Requirements

• Node.js 16+
• TypeScript 5.x (optional, for types)

Usage

Basic (no auth)

import { ReliableWebSocket } from "@solncebro/websocket-engine";

interface StreamMessage {
  type: string;
  data: unknown;
}

const ws = new ReliableWebSocket<StreamMessage>({
  url: "wss://stream.example.com",
  label: "market-stream",
  logger: pinoLogger,
  parseMessage: (rawData) => JSON.parse(rawData.toString()) as StreamMessage,
  onMessage: (message) => {
    console.log(message.type, message.data);
  },
  onNotify: async (message) => {
    await sendTelegramAlert(message);
  },
});

ws.close();

With authentication (e.g. Bybit trading WebSocket)

import crypto from "crypto";
import {
  ReliableWebSocket,
  WebSocketOpenContext,
} from "@solncebro/websocket-engine";

interface BybitMessage {
  op?: string;
  retCode?: number;
  retMsg?: string;
  reqId?: string;
  data?: unknown;
}

const ws = new ReliableWebSocket<BybitMessage>({
  url: "wss://stream.bybit.com/v5/trade",
  label: "bybit-trade",
  logger: pinoLogger,
  parseMessage: (rawData) => JSON.parse(rawData.toString()) as BybitMessage,

  onOpen: async ({ send, waitForMessage }: WebSocketOpenContext<BybitMessage>) => {
    const expires = Date.now() + 10000;
    const signature = crypto
      .createHmac("sha256", SECRET)
      .update(`GET/realtime${expires}`)
      .digest("hex");

    send({ op: "auth", args: [API_KEY, expires, signature] });

    const response = await waitForMessage((message) => message.op === "auth", 10000);

    if (response.retMsg !== "OK") {
      throw new Error(`Auth failed: ${response.retMsg}`);
    }
  },

  heartbeat: {
    buildPayload: () => ({ op: "ping" }),
    isResponse: (msg) => msg.op === "pong",
  },

  onMessage: (message) => {
    if (message.op === "order.create") {
      // handle order response
    }
  },

  onReconnectSuccess: () => {
    console.log("Reconnected and re-authenticated");
  },

  onNotify: async (message) => {
    await sendTelegramAlert(message);
  },
});

// Send an order and await its specific response by reqId
const sendOrder = async (orderParams: Record<string, unknown>) => {
  const reqId = `req_${Date.now()}`;

  ws.sendToConnectedSocket({
    reqId,
    op: "order.create",
    args: [orderParams],
  });

  return ws.waitForMessage((message) => message.reqId === reqId, 30000);
};

API

new ReliableWebSocket<TMessage>(args)

Creates a ReliableWebSocket<TMessage> instance. Connection starts immediately on construction.

Arguments

Instance Methods

WebSocketStatus

• CONNECTING — initial connection attempt
• CONNECTED — connected (and auth passed if onOpen was provided)
• DISCONNECTED — disrupted, reconnect scheduled
• RECONNECTING — reconnect in progress (includes onOpen phase)
• FAILED — closed by user or max retries exceeded

WebSocketOpenContext

Passed to onOpen:

WebSocketHeartbeatOptions

Configuration (configuration)

Behaviour

• On close or error, reconnection is scheduled with exponential backoff.
• If onOpen throws, the connection is terminated and reconnect is triggered (with the same backoff logic). Retry counters are only reset after onOpen resolves successfully.
• After maxRetryAttempts failed attempts, onNotify is awaited with a critical message and status becomes FAILED. The process is not terminated — the caller can check getStatus() and decide how to handle the failure.
• waitForMessage pending promises are rejected when the connection is disrupted or close() is called.
• Heartbeat response messages and waitForMessage-intercepted messages are never passed to onMessage.

License

ISC