Socket Connection

/**
 * Creates a new Phoenix Socket instance
 * @param endPoint - WebSocket endpoint URL (e.g., "/socket" or "ws://localhost:4000/socket")
 * @param opts - Socket configuration options
 */
constructor(endPoint: string, opts?: Partial<SocketConnectOption>);

interface SocketConnectOption {
  /** WebSocket binary data type */
  binaryType: BinaryType;
  /** Connection parameters (static object or dynamic function) */
  params: object | (() => object);
  /** WebSocket transport constructor */
  transport: new(endpoint: string) => object;
  /** Default timeout for operations in milliseconds */
  timeout: number;
  /** Heartbeat interval in milliseconds */
  heartbeatIntervalMs: number;
  /** Milliseconds before falling back to long polling */
  longPollFallbackMs: number;
  /** Long polling timeout in milliseconds */
  longpollerTimeout: number;
  /** Message encoding function */
  encode: (payload: object, callback: (encoded: any) => void | Promise<void>) => void;
  /** Message decoding function */
  decode: (payload: string, callback: (decoded: any) => void | Promise<void>) => void;
  /** Logging function for debug output */
  logger: (kind: string, message: string, data: any) => void;
  /** Reconnection backoff calculation function */
  reconnectAfterMs: (tries: number) => number;
  /** Channel rejoin backoff calculation function */
  rejoinAfterMs: (tries: number) => number;
  /** Protocol version string */
  vsn: string;
  /** Enable debug logging */
  debug: boolean;
  /** Session storage implementation */
  sessionStorage: object;
}

type BinaryType = "arraybuffer" | "blob";

import { Socket } from "phoenix";

// Basic socket connection
const socket = new Socket("/socket", {
  params: { userToken: "abc123" },
  heartbeatIntervalMs: 30000,
  debug: true
});

// Advanced configuration with custom transport
const advancedSocket = new Socket("/socket", {
  params: () => ({ token: getAuthToken() }), // Dynamic params
  reconnectAfterMs: (tries) => [1000, 2000, 5000][tries - 1] || 10000,
  rejoinAfterMs: (tries) => [500, 1000, 2000][tries - 1] || 5000,
  logger: (kind, msg, data) => console.log(`Phoenix ${kind}:`, msg, data),
  binaryType: "arraybuffer",
  vsn: "2.0.0"
});

/**
 * Establish WebSocket connection
 * @param params - Optional connection parameters (overrides constructor params)
 */
connect(params?: any): void;

/**
 * Close WebSocket connection
 * @param callback - Optional callback to execute after disconnect
 * @param code - WebSocket close code
 * @param reason - Reason for disconnection
 */
disconnect(callback?: () => void | Promise<void>, code?: number, reason?: string): void;

/**
 * Get current connection state
 * @returns Current ConnectionState
 */
connectionState(): ConnectionState;

/**
 * Check if socket is currently connected
 * @returns True if connected, false otherwise
 */
isConnected(): boolean;

type ConnectionState = "connecting" | "open" | "closing" | "closed";

// Connect with optional params
socket.connect({ room: "lobby" });

// Check connection status
if (socket.isConnected()) {
  console.log("Socket is connected");
}

// Monitor connection state
const state = socket.connectionState();
console.log("Connection state:", state);

// Graceful disconnect
socket.disconnect(() => {
  console.log("Disconnected gracefully");
}, 1000, "User logout");

/**
 * Register callback for socket open events
 * @param callback - Function to call when socket opens
 * @returns Message reference for removing handler
 */
onOpen(callback: () => void | Promise<void>): MessageRef;

/**
 * Register callback for socket close events
 * @param callback - Function to call when socket closes
 * @returns Message reference for removing handler
 */
onClose(callback: (event: CloseEvent) => void | Promise<void>): MessageRef;

/**
 * Register callback for socket error events
 * @param callback - Function to call when errors occur
 * @returns Message reference for removing handler
 */
onError(callback: (
  error: Event | string | number,
  transport: new(endpoint: string) => object,
  establishedConnections: number
) => void | Promise<void>): MessageRef;

/**
 * Register callback for all socket messages
 * @param callback - Function to call for each message
 * @returns Message reference for removing handler
 */
onMessage(callback: (message: object) => void | Promise<void>): MessageRef;

/**
 * Remove event handlers by reference
 * @param refs - Array of message references to remove
 */
off(refs: MessageRef[]): void;

type MessageRef = string;

// Register event handlers
const openRef = socket.onOpen(() => {
  console.log("Socket opened");
});

const closeRef = socket.onClose((event) => {
  console.log("Socket closed:", event.code, event.reason);
});

const errorRef = socket.onError((error, transport, connections) => {
  console.error("Socket error:", error);
  console.log("Failed transport:", transport);
  console.log("Established connections:", connections);
});

const messageRef = socket.onMessage((message) => {
  console.log("Raw message:", message);
});

// Remove all handlers when done
socket.off([openRef, closeRef, errorRef, messageRef]);

/**
 * Create a channel for the given topic
 * @param topic - Channel topic string (e.g., "room:lobby")
 * @param chanParams - Channel-specific parameters
 * @returns New Channel instance
 */
channel(topic: string, chanParams?: object): Channel;

/**
 * Remove channel from socket
 * @param channel - Channel instance to remove
 */
remove(channel: Channel): void;

// Create channels
const lobbyChannel = socket.channel("room:lobby", { user_id: 123 });
const userChannel = socket.channel("user:456", { permissions: ["read", "write"] });

// Remove channel when done
socket.remove(lobbyChannel);

/**
 * Get protocol being used
 * @returns Protocol string ("ws" or "wss")
 */
protocol(): string;

/**
 * Get formatted endpoint URL
 * @returns Complete WebSocket URL
 */
endPointURL(): string;

/**
 * Replace the socket's transport mechanism
 * @param transport - New transport constructor
 */
replaceTransport(transport: new(endpoint: string) => object): void;

/**
 * Send raw data through socket
 * @param data - Data object to send
 */
push(data: object): void;

/**
 * Log message using configured logger
 * @param kind - Log level/kind
 * @param message - Log message
 * @param data - Additional data to log
 */
log(kind: string, message: string, data: any): void;

/**
 * Check if logger is configured
 * @returns True if logger is available
 */
hasLogger(): boolean;

/**
 * Generate unique message reference
 * @returns Unique string reference
 */
makeRef(): MessageRef;

/**
 * Ping server and measure latency
 * @param callback - Function to receive latency measurement
 * @returns True if ping was sent successfully
 */
ping: (callback: (latency: number) => void) => boolean;

// Get connection info
console.log("Protocol:", socket.protocol());
console.log("Endpoint:", socket.endPointURL());

// Generate unique reference
const ref = socket.makeRef();
console.log("Generated ref:", ref);

// Measure latency
socket.ping((latency) => {
  console.log("Latency:", latency, "ms");
});

// Send raw data
socket.push({ event: "heartbeat", ref: socket.makeRef() });

// Check logging capability
if (socket.hasLogger()) {
  socket.log("info", "Custom log message", { custom: "data" });
}