kinetex - v1.0.0-rc.1
    Preparing search index...

    Interface WSClientConfig

    Configuration for creating a WSClient instance. Controls connection parameters, reconnection strategy, ping/pong heartbeats, backpressure limits, and lifecycle callbacks.

    interface WSClientConfig {
        url: string;
        protocols?: string | string[];
        headers?: Record<string, string>;
        maxReconnects?: number;
        reconnectBaseMs?: number;
        reconnectMaxMs?: number;
        reconnectJitter?: number;
        pingIntervalMs?: number;
        pingPayload?: string;
        pongMatcher?: string | RegExp;
        pongTimeoutMs?: number;
        connectTimeoutMs?: number;
        bufferMessages?: boolean;
        maxBufferSize?: number;
        signal?: AbortSignal;
        highWaterMark?: number;
        lowWaterMark?: number;
        maxSendRate?: number;
        rooms?: string[];
        keepRooms?: boolean;
        onBackpressure?: (
            isBackpressured: boolean,
            info: WSBackpressureInfo,
        ) => void;
        onOpen?: (reconnectCount: number) => void;
        onMessage?: (msg: WSMessage) => void;
        onClose?: (code: number, reason: string, willReconnect: boolean) => void;
        onError?: (err: Error) => void;
        onReconnect?: (attempt: number, delayMs: number) => void;
        onGiveUp?: (totalAttempts: number) => void;
    }
    Index

    Properties

    url protocols? headers? maxReconnects? reconnectBaseMs? reconnectMaxMs? reconnectJitter? pingIntervalMs? pingPayload? pongMatcher? pongTimeoutMs? connectTimeoutMs? bufferMessages? maxBufferSize? signal? highWaterMark? lowWaterMark? maxSendRate? rooms? keepRooms? onBackpressure? onOpen? onMessage? onClose? onError? onReconnect? onGiveUp?

    Properties

    url: string

    WebSocket URL (ws:// or wss://).

    protocols?: string | string[]

    Subprotocols to negotiate during the handshake.

    headers?: Record<string, string>

    Headers to inject. On Deno/Bun/Node 22 these become real HTTP Upgrade request headers. On browsers the WS API does not allow custom headers; they are appended as URL query parameters instead.

    maxReconnects?: number

    Maximum reconnect attempts before giving up. 0 = unlimited. Default: 10

    reconnectBaseMs?: number

    Base delay ms for exponential back-off. Default: 1000

    reconnectMaxMs?: number

    Maximum back-off cap ms. Default: 30_000

    reconnectJitter?: number

    Jitter factor 0–1. Applied multiplicatively to the capped delay so that each client re-connects at a slightly different time. delay = min(base * 2^n, max) * (1 + jitter * random) Default: 0.3

    pingIntervalMs?: number

    Application-level ping interval ms. Every this many ms the client sends pingPayload over the socket. 0 = disabled. Default: 30_000

    pingPayload?: string

    Payload sent as application-level ping. Default: "ping"

    pongMatcher?: string | RegExp

    String or RegExp that identifies a pong reply to an application-level ping. When a matching message arrives, the pong-timeout timer is reset and the message is NOT dispatched to listeners. Default: undefined (pong checking disabled)

    pongTimeoutMs?: number

    How long ms to wait for a pong after a ping before treating the connection as dead and triggering reconnect. 0 = disabled. Default: 10_000

    connectTimeoutMs?: number

    Maximum ms to wait for the WebSocket handshake to complete. connect() rejects with WSConnectTimeoutError if this elapses. 0 = no limit. Default: 30_000

    bufferMessages?: boolean

    Buffer outgoing messages sent while RECONNECTING. Default: true

    maxBufferSize?: number

    Maximum number of messages to buffer (oldest dropped when full). Default: 100

    signal?: AbortSignal

    AbortSignal — aborted closes permanently (code 1000, no reconnect).

    highWaterMark?: number

    Backpressure high-water mark in bytes. When the outgoing buffer exceeds this threshold backpressure returns true and send() will buffer rather than transmit. Default: 65536 (64 KB)

    lowWaterMark?: number

    Low-water mark in bytes for backpressure release. The drain() promise resolves when buffered bytes fall below this value. Must be <= highWaterMark. Default: 16384 (16 KB)

    maxSendRate?: number

    Maximum outbound message rate (messages per second). 0 = unlimited. Default: 0

    rooms?: string[]

    Rooms to automatically join after connecting (and re-joining after reconnect). Each entry is a room name string.

    keepRooms?: boolean

    Automatically re-join subscribed rooms after a reconnect. Default: true

    onBackpressure?: (isBackpressured: boolean, info: WSBackpressureInfo) => void

    Called when backpressure state changes. isBackpressured=true when the outgoing buffer exceeds highWaterMark.

    onOpen?: (reconnectCount: number) => void

    Called when the socket transitions to OPEN

    onMessage?: (msg: WSMessage) => void

    Called when a message is received

    onClose?: (code: number, reason: string, willReconnect: boolean) => void

    Called when the socket closes

    onError?: (err: Error) => void

    Called on WebSocket error

    onReconnect?: (attempt: number, delayMs: number) => void

    Called before each reconnect attempt

    onGiveUp?: (totalAttempts: number) => void

    Called when reconnection is permanently abandoned

    Settings

    Member Visibility

    On This Page

    Properties