ClientWebSocketOptions

interface ClientWebSocketOptions {
  handle?: WebSocketHandleConstructor;
  beforeConnect?: (context: {
    attempt: number;
    signal: AbortSignal;
  }) => void | Promise<void>;
  heartbeat?: {
    intervalMs: number;
    isAck?: (message: unknown) => boolean;
    message?: <T = unknown>() => T | unknown;
    timeoutMs?: number;
  };
  protocols?: readonly string[];
  reconnect?: {
    attempts?: number;
    delayMs?: number;
    factor?: number;
    jitter?: number;
    maxDelayMs?: number;
    shouldReconnect?: (context: {
      attempt: number;
      cause?: unknown;
      code?: number;
      reason?: string;
      wasClean?: boolean;
    }) => boolean;
  };
}

• handle — WebSocket constructor; defaults to globalThis.WebSocket.
• beforeConnect — Runs before each connect and reconnect attempt.
• heartbeat — Sends message() every intervalMs. With timeoutMs and isAck, a missing acknowledgement marks the connection unhealthy. intervalMs and timeoutMs must be positive and at most 2147483647.
• protocols — Subprotocols passed to the constructor.
• reconnect — Opt-in. attempts defaults to 3; 0 disables retry, and omitting attempts is not unlimited. Other defaults: delayMs 1000, factor 2, jitter 0 (a 0-1 multiplicative factor), maxDelayMs 30000. shouldReconnect receives the close code, reason, and wasClean and can veto a retry.

The retry budget applies per outage. Successful open resets the budget, callback attempt, and backoff exponent; the next outage starts at retry 1. maxDelayMs caps the final delay after jitter and rounding, also bounded by 2_147_483_647 ms. See withWebSocketReconnect for validation rules and overflow behavior.

Set these with withWebSocketHandle, withWebSocketBeforeConnect, withWebSocketHeartbeat, withWebSocketProtocols, and withWebSocketReconnect. WebSocketExecuteOptions can override beforeConnect, heartbeat, protocols, and reconnect per call.