@solncebro/websocket-engine

@solncebro/websocket-engine

Reliable, environment-agnostic WebSocket client with automatic reconnection, application-level heartbeat plus idle (stale) detection, typed messages, optional authentication phase, and request/response pattern. Built on the global WebSocket, so it runs unchanged in Node.js 22+, browsers, and React Native — no ws dependency.

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 — application-level JSON ping (e.g. Bybit { op: 'ping' }, Binance { method: 'LIST_SUBSCRIPTIONS' }) paired with idle detection: the socket reconnects if no message arrives within staleThreshold. No TCP control frames are used, so it works on any WHATWG WebSocket.
• 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 22+ (built-in global WebSocket), or any environment with a WHATWG WebSocket (browsers, React Native)
• 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

Property	Type	Required	Description
url	string	Yes	WebSocket URL
label	string	Yes	Identifier for logs and notifications
logger	WebSocketLogger	Yes	Logger with debug, info, warn, error, fatal
onMessage	(message: TMessage) => void	Yes	Called for each incoming message (not intercepted by waitForMessage or heartbeat)
parseMessage	(rawData: RawData) => TMessage	No	Parse raw data to TMessage; default: pass-through
onOpen	(context: WebSocketOpenContext<TMessage>) => Promise<void>	No	Async setup phase after connect (e.g. auth). Connection is not considered ready until this resolves.
onReconnectSuccess	() => void	No	Called after a successful reconnection (not on first connect)
onClose	(context: WebSocketCloseContext) => void	No	Called on every disruption, before the reconnect is scheduled, with the close/error details
onNotify	(message: string) => void | Promise<void>	No	Called on connection issues and when max retries exceeded
heartbeat	WebSocketHeartbeatOptions<TMessage>	No	Application-level heartbeat (JSON ping/pong). When provided, an active ping is sent every pingInterval and idle detection is enabled. Without it, the socket relies on close/error events.
configuration	Partial<WebSocketConfiguration>	No	Override default timeouts and retry behaviour

Instance Methods

Method	Description
close()	Stops reconnection, clears timers, rejects pending waiters, closes the socket
getStatus()	Returns current WebSocketStatus
getUrl()	Returns the WebSocket URL
sendToConnectedSocket(data)	Send data; string is sent as-is, anything else is JSON.stringify-ed. Throws if not connected.
waitForMessage(predicate, timeoutMilliseconds)	Returns a Promise<TMessage> that resolves with the first incoming message matching predicate. The message is not passed to onMessage. Rejects on timeout, connection close, or if predicate throws.

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:

Property	Description
send	Send to the open socket (for use during onOpen)
waitForMessage	Same as instance waitForMessage

WebSocketHeartbeatOptions

Property	Description
buildPayload	Returns the JSON object to send as a ping
isResponse	Returns true if the message is a pong. Matching messages are not passed to onMessage.

WebSocketCloseContext

Passed to onClose:

Property	Type	Description
closeCode	number | undefined	Close code, when the disruption came from a close event
errorMessage	string | undefined	Error text, when the disruption came from an error event
consecutiveFailures	number	Consecutive failed attempts so far
missedPongCount	number	Consecutive stale checks with no incoming message
isPongTimeout	boolean	true when missedPongCount has reached missedPongThreshold

Configuration (configuration)

Option	Default	Description
maxRetryAttempts	15	Max reconnection attempts before entering FAILED status
initialRetryDelay	1000	Initial delay (ms) for exponential backoff
maxRetryDelay	30000	Cap (ms) for backoff delay
retryDelayMultiplier	1.8	Backoff multiplier
connectionTimeout	30000	Handshake timeout (ms)
pingInterval	15000	Active heartbeat ping interval (ms); only sent when heartbeat is set
pongTimeout	10000	Pong wait timeout (ms)
heartbeatGracePeriod	3000	Delay before first ping (ms)
staleThreshold	60000	Reconnect if no incoming message (including ping responses) for this long (ms); requires heartbeat
staleCheckInterval	5000	How often idle is checked (ms)
fastReconnectCodes	[1001, 1006, 1011, 1012, 1013, 1014]	Close codes that use short reconnect delay
missedPongThreshold	3	Consecutive stale checks reflected in isPongTimeout of the close context

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.
• With a heartbeat, the connection is also reconnected if no incoming message (including ping responses) arrives within staleThreshold. This catches a silently dead connection without relying on TCP-level control frames, which the global WebSocket cannot send from code.

License

ISC