🔌 WebSockets with TypeScript: Real-Time Communication

🎯 Introduction

Welcome to the real-time world of WebSockets! 🔌 If HTTP is like sending letters through the mail, then WebSockets are like having a direct phone line - instant, bidirectional communication that makes real-time features like chat, live updates, and collaborative editing possible!

Think of WebSockets as persistent tunnels 🚇 between your client and server. Once established, both sides can send messages instantly without the overhead of HTTP headers, request/response cycles, or polling. It’s the backbone of modern real-time web applications!

By the end of this tutorial, you’ll be a master of real-time communication, able to build chat applications, live dashboards, collaborative tools, and any other real-time feature your imagination can conjure. Let’s connect to the future! 🌐

📚 Understanding WebSockets

🤔 What Are WebSockets?

WebSockets provide full-duplex communication channels over a single TCP connection. They start with an HTTP handshake but then upgrade to a persistent connection that allows both client and server to send data at any time!

// 🌟 Basic WebSocket connection
// client.ts - Browser WebSocket client
class WebSocketClient {
  private socket: WebSocket | null = null;
  private reconnectAttempts = 0;
  private maxReconnectAttempts = 5;
  private reconnectDelay = 1000;

  constructor(private url: string) {}

  connect(): Promise<void> {
    return new Promise((resolve, reject) => {
      console.log('🔌 Connecting to WebSocket server...');
      
      this.socket = new WebSocket(this.url);

      this.socket.onopen = (event) => {
        console.log('✅ WebSocket connection established!');
        this.reconnectAttempts = 0;
        resolve();
      };

      this.socket.onmessage = (event) => {
        console.log('📨 Message received:', event.data);
        this.handleMessage(JSON.parse(event.data));
      };

      this.socket.onclose = (event) => {
        console.log('🔌 WebSocket connection closed:', event.code, event.reason);
        this.handleReconnect();
      };

      this.socket.onerror = (error) => {
        console.error('❌ WebSocket error:', error);
        reject(error);
      };
    });
  }

  send(message: any): void {
    if (this.socket?.readyState === WebSocket.OPEN) {
      this.socket.send(JSON.stringify(message));
    } else {
      console.warn('⚠️ WebSocket not connected. Message not sent:', message);
    }
  }

  private handleMessage(message: any): void {
    // Override in subclasses or provide callback
    console.log('📥 Handling message:', message);
  }

  private handleReconnect(): void {
    if (this.reconnectAttempts < this.maxReconnectAttempts) {
      this.reconnectAttempts++;
      console.log(`🔄 Attempting to reconnect (${this.reconnectAttempts}/${this.maxReconnectAttempts})...`);
      
      setTimeout(() => {
        this.connect().catch(console.error);
      }, this.reconnectDelay * this.reconnectAttempts);
    } else {
      console.error('💥 Max reconnection attempts reached');
    }
  }

  disconnect(): void {
    if (this.socket) {
      this.socket.close();
      this.socket = null;
    }
  }
}

💡 Key Characteristics

• 🔄 Bidirectional: Both client and server can send messages
• ⚡ Low Latency: No HTTP overhead for each message
• 📡 Real-Time: Instant message delivery
• 🔌 Persistent: Connection stays open until explicitly closed

// 🎨 Type-safe WebSocket message system
interface BaseMessage {
  type: string;
  timestamp: number;
  id: string;
}

interface ChatMessage extends BaseMessage {
  type: 'chat_message';
  content: string;
  userId: string;
  username: string;
}

interface UserJoinedMessage extends BaseMessage {
  type: 'user_joined';
  userId: string;
  username: string;
}

interface UserLeftMessage extends BaseMessage {
  type: 'user_left';
  userId: string;
  username: string;
}

interface TypingMessage extends BaseMessage {
  type: 'typing';
  userId: string;
  username: string;
  isTyping: boolean;
}

// 🎯 Union type for all possible messages
type WebSocketMessage = ChatMessage | UserJoinedMessage | UserLeftMessage | TypingMessage;

// 📦 Message factory for type safety
class MessageFactory {
  static createChatMessage(content: string, userId: string, username: string): ChatMessage {
    return {
      type: 'chat_message',
      content,
      userId,
      username,
      timestamp: Date.now(),
      id: crypto.randomUUID()
    };
  }

  static createUserJoinedMessage(userId: string, username: string): UserJoinedMessage {
    return {
      type: 'user_joined',
      userId,
      username,
      timestamp: Date.now(),
      id: crypto.randomUUID()
    };
  }

  static createTypingMessage(userId: string, username: string, isTyping: boolean): TypingMessage {
    return {
      type: 'typing',
      userId,
      username,
      isTyping,
      timestamp: Date.now(),
      id: crypto.randomUUID()
    };
  }
}

🆚 WebSockets vs Other Real-Time Technologies

// 🐌 HTTP Polling - inefficient, delayed updates
class HTTPPollingClient {
  private intervalId: number | null = null;

  startPolling(url: string, interval = 1000): void {
    // ❌ Wasteful - constantly hitting server even when no updates
    this.intervalId = window.setInterval(async () => {
      try {
        const response = await fetch(url);
        const data = await response.json();
        this.handleUpdate(data);
      } catch (error) {
        console.error('Polling error:', error);
      }
    }, interval);
  }

  private handleUpdate(data: any): void {
    console.log('📊 Polled update:', data);
  }

  stopPolling(): void {
    if (this.intervalId) {
      clearInterval(this.intervalId);
      this.intervalId = null;
    }
  }
}

// 🚀 Server-Sent Events - one-way real-time
class SSEClient {
  private eventSource: EventSource | null = null;

  connect(url: string): void {
    // ✅ Real-time but only server → client
    this.eventSource = new EventSource(url);

    this.eventSource.onmessage = (event) => {
      console.log('📡 SSE message:', JSON.parse(event.data));
    };

    this.eventSource.onerror = (error) => {
      console.error('❌ SSE error:', error);
    };
  }

  disconnect(): void {
    if (this.eventSource) {
      this.eventSource.close();
      this.eventSource = null;
    }
  }
}

// 🔌 WebSockets - full duplex real-time (BEST!)
class RealTimeClient {
  private socket: WebSocket | null = null;

  connect(url: string): void {
    // ✅ Bidirectional real-time with low overhead
    this.socket = new WebSocket(url);

    this.socket.onmessage = (event) => {
      console.log('⚡ Real-time message:', JSON.parse(event.data));
    };

    // Can send anytime!
    setTimeout(() => {
      this.send({ type: 'ping', message: 'Hello server!' });
    }, 1000);
  }

  send(data: any): void {
    if (this.socket?.readyState === WebSocket.OPEN) {
      this.socket.send(JSON.stringify(data));
    }
  }
}

🏗️ Building a Type-Safe WebSocket Client

🎯 Advanced WebSocket Client Implementation

Let’s build a production-ready WebSocket client with TypeScript that handles all the edge cases and provides a clean API:

// 🏗️ Advanced WebSocket client with full TypeScript support
interface WebSocketClientConfig {
  autoReconnect?: boolean;
  maxReconnectAttempts?: number;
  reconnectDelay?: number;
  heartbeatInterval?: number;
  connectionTimeout?: number;
}

interface WebSocketClientEvents {
  connected: () => void;
  disconnected: (reason: string) => void;
  message: (message: WebSocketMessage) => void;
  error: (error: Error) => void;
  reconnecting: (attempt: number) => void;
}

class TypeSafeWebSocketClient {
  private socket: WebSocket | null = null;
  private reconnectAttempts = 0;
  private heartbeatTimer: number | null = null;
  private connectionTimeoutTimer: number | null = null;
  private eventListeners: Partial<WebSocketClientEvents> = {};
  
  constructor(
    private url: string,
    private config: WebSocketClientConfig = {}
  ) {
    // 🎛️ Default configuration
    this.config = {
      autoReconnect: true,
      maxReconnectAttempts: 5,
      reconnectDelay: 1000,
      heartbeatInterval: 30000,
      connectionTimeout: 10000,
      ...config
    };
  }

  // 🎧 Event listener management
  on<K extends keyof WebSocketClientEvents>(
    event: K,
    listener: WebSocketClientEvents[K]
  ): void {
    this.eventListeners[event] = listener;
  }

  off<K extends keyof WebSocketClientEvents>(event: K): void {
    delete this.eventListeners[event];
  }

  private emit<K extends keyof WebSocketClientEvents>(
    event: K,
    ...args: Parameters<NonNullable<WebSocketClientEvents[K]>>
  ): void {
    const listener = this.eventListeners[event];
    if (listener) {
      (listener as any)(...args);
    }
  }

  // 🔌 Connection management
  async connect(): Promise<void> {
    return new Promise((resolve, reject) => {
      console.log('🔌 Initiating WebSocket connection...');
      
      // ⏰ Connection timeout
      this.connectionTimeoutTimer = window.setTimeout(() => {
        reject(new Error('Connection timeout'));
      }, this.config.connectionTimeout);

      try {
        this.socket = new WebSocket(this.url);
        this.setupEventHandlers(resolve, reject);
      } catch (error) {
        this.clearConnectionTimeout();
        reject(error);
      }
    });
  }

  private setupEventHandlers(
    resolve: () => void,
    reject: (error: Error) => void
  ): void {
    if (!this.socket) return;

    this.socket.onopen = () => {
      console.log('✅ WebSocket connected successfully!');
      this.clearConnectionTimeout();
      this.reconnectAttempts = 0;
      this.startHeartbeat();
      this.emit('connected');
      resolve();
    };

    this.socket.onmessage = (event) => {
      try {
        const message: WebSocketMessage = JSON.parse(event.data);
        
        // 💓 Handle heartbeat responses
        if (message.type === 'pong') {
          console.log('💓 Heartbeat response received');
          return;
        }

        console.log('📨 Message received:', message.type);
        this.emit('message', message);
      } catch (error) {
        console.error('❌ Failed to parse message:', error);
        this.emit('error', new Error('Failed to parse message'));
      }
    };

    this.socket.onclose = (event) => {
      console.log(`🔌 WebSocket closed: ${event.code} - ${event.reason}`);
      this.cleanup();
      this.emit('disconnected', event.reason);
      
      if (this.config.autoReconnect && event.code !== 1000) {
        this.attemptReconnect();
      }
    };

    this.socket.onerror = (error) => {
      console.error('❌ WebSocket error:', error);
      this.clearConnectionTimeout();
      this.emit('error', new Error('WebSocket connection error'));
      reject(new Error('WebSocket connection error'));
    };
  }

  // 💓 Heartbeat mechanism
  private startHeartbeat(): void {
    if (this.config.heartbeatInterval && this.config.heartbeatInterval > 0) {
      this.heartbeatTimer = window.setInterval(() => {
        if (this.isConnected()) {
          console.log('💓 Sending heartbeat...');
          this.send({
            type: 'ping',
            timestamp: Date.now(),
            id: crypto.randomUUID()
          } as any);
        }
      }, this.config.heartbeatInterval);
    }
  }

  private stopHeartbeat(): void {
    if (this.heartbeatTimer) {
      clearInterval(this.heartbeatTimer);
      this.heartbeatTimer = null;
    }
  }

  // 🔄 Reconnection logic
  private attemptReconnect(): void {
    if (this.reconnectAttempts >= (this.config.maxReconnectAttempts || 5)) {
      console.error('💥 Max reconnection attempts exceeded');
      return;
    }

    this.reconnectAttempts++;
    const delay = (this.config.reconnectDelay || 1000) * this.reconnectAttempts;
    
    console.log(`🔄 Reconnecting in ${delay}ms (attempt ${this.reconnectAttempts})...`);
    this.emit('reconnecting', this.reconnectAttempts);

    setTimeout(() => {
      this.connect().catch((error) => {
        console.error('❌ Reconnection failed:', error);
      });
    }, delay);
  }

  // 📤 Message sending with type safety
  send<T extends WebSocketMessage>(message: T): boolean {
    if (!this.isConnected()) {
      console.warn('⚠️ Cannot send message: WebSocket not connected');
      return false;
    }

    try {
      this.socket!.send(JSON.stringify(message));
      console.log('📤 Message sent:', message.type);
      return true;
    } catch (error) {
      console.error('❌ Failed to send message:', error);
      this.emit('error', new Error('Failed to send message'));
      return false;
    }
  }

  // 🔍 Connection state
  isConnected(): boolean {
    return this.socket?.readyState === WebSocket.OPEN;
  }

  getReadyState(): string {
    if (!this.socket) return 'DISCONNECTED';
    
    switch (this.socket.readyState) {
      case WebSocket.CONNECTING: return 'CONNECTING';
      case WebSocket.OPEN: return 'OPEN';
      case WebSocket.CLOSING: return 'CLOSING';
      case WebSocket.CLOSED: return 'CLOSED';
      default: return 'UNKNOWN';
    }
  }

  // 🧹 Cleanup
  private clearConnectionTimeout(): void {
    if (this.connectionTimeoutTimer) {
      clearTimeout(this.connectionTimeoutTimer);
      this.connectionTimeoutTimer = null;
    }
  }

  private cleanup(): void {
    this.stopHeartbeat();
    this.clearConnectionTimeout();
  }

  // 🔌 Disconnect
  disconnect(code = 1000, reason = 'Client disconnect'): void {
    if (this.socket) {
      console.log('🔌 Disconnecting WebSocket...');
      this.config.autoReconnect = false; // Prevent auto-reconnect
      this.socket.close(code, reason);
    }
    this.cleanup();
  }
}

🛠️ Real-World Chat Application

Let’s build a complete chat application that demonstrates real-world WebSocket usage:

// 💬 Chat application using our WebSocket client
interface User {
  id: string;
  username: string;
  avatar?: string;
  isOnline: boolean;
}

interface ChatRoom {
  id: string;
  name: string;
  users: User[];
  messageCount: number;
}

class ChatApplication {
  private client: TypeSafeWebSocketClient;
  private currentUser: User | null = null;
  private currentRoom: ChatRoom | null = null;
  private users = new Map<string, User>();
  private messageHistory: ChatMessage[] = [];
  private typingUsers = new Set<string>();
  private typingTimer: number | null = null;

  constructor(private websocketUrl: string) {
    this.client = new TypeSafeWebSocketClient(websocketUrl, {
      autoReconnect: true,
      maxReconnectAttempts: 10,
      heartbeatInterval: 30000
    });

    this.setupEventHandlers();
  }

  private setupEventHandlers(): void {
    // 🎧 WebSocket event handlers
    this.client.on('connected', () => {
      console.log('🎉 Connected to chat server!');
      this.authenticateUser();
    });

    this.client.on('disconnected', (reason) => {
      console.log('😞 Disconnected from chat server:', reason);
      this.handleDisconnection();
    });

    this.client.on('message', (message) => {
      this.handleIncomingMessage(message);
    });

    this.client.on('error', (error) => {
      console.error('💥 Chat client error:', error);
      this.handleError(error);
    });

    this.client.on('reconnecting', (attempt) => {
      console.log(`🔄 Reconnecting to chat server (attempt ${attempt})...`);
    });
  }

  // 🚀 Initialize chat application
  async initialize(username: string): Promise<void> {
    this.currentUser = {
      id: crypto.randomUUID(),
      username,
      isOnline: true
    };

    try {
      await this.client.connect();
      console.log('✅ Chat application initialized!');
    } catch (error) {
      console.error('❌ Failed to initialize chat:', error);
      throw error;
    }
  }

  private authenticateUser(): void {
    if (!this.currentUser) return;

    const authMessage = MessageFactory.createAuthMessage(
      this.currentUser.id,
      this.currentUser.username
    );

    this.client.send(authMessage);
  }

  // 💬 Send chat message
  sendMessage(content: string): void {
    if (!this.currentUser || !this.currentRoom) {
      console.warn('⚠️ Cannot send message: User not authenticated or not in room');
      return;
    }

    const message = MessageFactory.createChatMessage(
      content,
      this.currentUser.id,
      this.currentUser.username
    );

    const success = this.client.send(message);
    if (success) {
      // Add to local history immediately for responsiveness
      this.messageHistory.push(message);
      this.notifyMessageSent(message);
    }
  }

  // 📝 Handle typing indicators
  startTyping(): void {
    if (!this.currentUser) return;

    const typingMessage = MessageFactory.createTypingMessage(
      this.currentUser.id,
      this.currentUser.username,
      true
    );

    this.client.send(typingMessage);

    // 🕐 Auto-stop typing after 3 seconds
    if (this.typingTimer) {
      clearTimeout(this.typingTimer);
    }

    this.typingTimer = window.setTimeout(() => {
      this.stopTyping();
    }, 3000);
  }

  stopTyping(): void {
    if (!this.currentUser) return;

    if (this.typingTimer) {
      clearTimeout(this.typingTimer);
      this.typingTimer = null;
    }

    const typingMessage = MessageFactory.createTypingMessage(
      this.currentUser.id,
      this.currentUser.username,
      false
    );

    this.client.send(typingMessage);
  }

  // 🏠 Room management
  joinRoom(roomId: string): void {
    if (!this.currentUser) return;

    const joinMessage: JoinRoomMessage = {
      type: 'join_room',
      roomId,
      userId: this.currentUser.id,
      timestamp: Date.now(),
      id: crypto.randomUUID()
    };

    this.client.send(joinMessage);
  }

  leaveRoom(): void {
    if (!this.currentUser || !this.currentRoom) return;

    const leaveMessage: LeaveRoomMessage = {
      type: 'leave_room',
      roomId: this.currentRoom.id,
      userId: this.currentUser.id,
      timestamp: Date.now(),
      id: crypto.randomUUID()
    };

    this.client.send(leaveMessage);
    this.currentRoom = null;
    this.messageHistory = [];
    this.users.clear();
  }

  // 📨 Handle incoming messages
  private handleIncomingMessage(message: WebSocketMessage): void {
    switch (message.type) {
      case 'chat_message':
        this.handleChatMessage(message);
        break;
      
      case 'user_joined':
        this.handleUserJoined(message);
        break;
      
      case 'user_left':
        this.handleUserLeft(message);
        break;
      
      case 'typing':
        this.handleTypingIndicator(message);
        break;
      
      case 'room_joined':
        this.handleRoomJoined(message as RoomJoinedMessage);
        break;
      
      case 'user_list':
        this.handleUserList(message as UserListMessage);
        break;
      
      default:
        console.warn('🤷 Unknown message type:', (message as any).type);
    }
  }

  private handleChatMessage(message: ChatMessage): void {
    console.log(`💬 ${message.username}: ${message.content}`);
    
    // Avoid duplicates (message might already be in history if sent by us)
    const exists = this.messageHistory.some(m => m.id === message.id);
    if (!exists) {
      this.messageHistory.push(message);
    }
    
    this.notifyNewMessage(message);
  }

  private handleUserJoined(message: UserJoinedMessage): void {
    console.log(`👋 ${message.username} joined the chat`);
    
    const user: User = {
      id: message.userId,
      username: message.username,
      isOnline: true
    };
    
    this.users.set(user.id, user);
    this.notifyUserJoined(user);
  }

  private handleUserLeft(message: UserLeftMessage): void {
    console.log(`👋 ${message.username} left the chat`);
    
    const user = this.users.get(message.userId);
    if (user) {
      user.isOnline = false;
      this.notifyUserLeft(user);
    }
  }

  private handleTypingIndicator(message: TypingMessage): void {
    if (message.userId === this.currentUser?.id) return; // Ignore our own typing

    if (message.isTyping) {
      this.typingUsers.add(message.username);
      console.log(`✏️ ${message.username} is typing...`);
    } else {
      this.typingUsers.delete(message.username);
    }
    
    this.notifyTypingUpdate();
  }

  private handleRoomJoined(message: RoomJoinedMessage): void {
    this.currentRoom = {
      id: message.roomId,
      name: message.roomName,
      users: [],
      messageCount: 0
    };
    
    console.log(`🏠 Joined room: ${message.roomName}`);
    this.notifyRoomJoined(this.currentRoom);
  }

  private handleUserList(message: UserListMessage): void {
    this.users.clear();
    
    message.users.forEach(userData => {
      const user: User = {
        id: userData.id,
        username: userData.username,
        isOnline: true
      };
      this.users.set(user.id, user);
    });
    
    if (this.currentRoom) {
      this.currentRoom.users = Array.from(this.users.values());
    }
    
    this.notifyUserListUpdate();
  }

  private handleDisconnection(): void {
    // Mark all users as offline
    this.users.forEach(user => {
      user.isOnline = false;
    });
    
    this.typingUsers.clear();
    this.notifyDisconnection();
  }

  private handleError(error: Error): void {
    this.notifyError(error);
  }

  // 🔔 Event notifications (override these in your UI layer)
  protected notifyNewMessage(message: ChatMessage): void {
    console.log('🔔 New message notification');
  }

  protected notifyMessageSent(message: ChatMessage): void {
    console.log('✅ Message sent confirmation');
  }

  protected notifyUserJoined(user: User): void {
    console.log('🔔 User joined notification');
  }

  protected notifyUserLeft(user: User): void {
    console.log('🔔 User left notification');
  }

  protected notifyTypingUpdate(): void {
    const typingList = Array.from(this.typingUsers);
    console.log('✏️ Typing users:', typingList);
  }

  protected notifyRoomJoined(room: ChatRoom): void {
    console.log('🏠 Room joined notification');
  }

  protected notifyUserListUpdate(): void {
    console.log('👥 User list updated');
  }

  protected notifyDisconnection(): void {
    console.log('🔌 Disconnection notification');
  }

  protected notifyError(error: Error): void {
    console.error('❌ Error notification:', error);
  }

  // 📊 Getters for current state
  get onlineUsers(): User[] {
    return Array.from(this.users.values()).filter(u => u.isOnline);
  }

  get messages(): ChatMessage[] {
    return [...this.messageHistory];
  }

  get currentTypingUsers(): string[] {
    return Array.from(this.typingUsers);
  }

  get isConnected(): boolean {
    return this.client.isConnected();
  }

  get connectionState(): string {
    return this.client.getReadyState();
  }

  // 🔌 Cleanup
  disconnect(): void {
    this.stopTyping();
    this.client.disconnect();
  }
}

// 📝 Additional message types for complete chat functionality
interface AuthMessage extends BaseMessage {
  type: 'auth';
  userId: string;
  username: string;
}

interface JoinRoomMessage extends BaseMessage {
  type: 'join_room';
  roomId: string;
  userId: string;
}

interface LeaveRoomMessage extends BaseMessage {
  type: 'leave_room';
  roomId: string;
  userId: string;
}

interface RoomJoinedMessage extends BaseMessage {
  type: 'room_joined';
  roomId: string;
  roomName: string;
}

interface UserListMessage extends BaseMessage {
  type: 'user_list';
  users: Array<{
    id: string;
    username: string;
  }>;
}

// 🏭 Extended message factory
class ExtendedMessageFactory extends MessageFactory {
  static createAuthMessage(userId: string, username: string): AuthMessage {
    return {
      type: 'auth',
      userId,
      username,
      timestamp: Date.now(),
      id: crypto.randomUUID()
    };
  }
}

🛠️ Server-Side WebSocket Implementation

🏗️ Node.js WebSocket Server with TypeScript

Let’s create a robust WebSocket server using Node.js and the ws library:

// 🖥️ Server-side WebSocket implementation
import WebSocket from 'ws';
import { createServer } from 'http';
import { v4 as uuidv4 } from 'uuid';

interface ConnectedClient {
  id: string;
  socket: WebSocket;
  user?: {
    id: string;
    username: string;
  };
  room?: string;
  isAlive: boolean;
  lastPong: number;
}

interface ChatRoom {
  id: string;
  name: string;
  clients: Set<string>;
  messageHistory: ChatMessage[];
  createdAt: number;
}

class WebSocketChatServer {
  private wss: WebSocket.Server;
  private clients = new Map<string, ConnectedClient>();
  private rooms = new Map<string, ChatRoom>();
  private heartbeatInterval: NodeJS.Timeout;

  constructor(port = 8080) {
    // 🏗️ Create HTTP server and WebSocket server
    const server = createServer();
    this.wss = new WebSocket.Server({ server });

    // 🎧 Setup WebSocket event handlers
    this.wss.on('connection', (socket, request) => {
      this.handleConnection(socket, request);
    });

    // 💓 Setup heartbeat mechanism
    this.heartbeatInterval = setInterval(() => {
      this.performHeartbeat();
    }, 30000);

    // 🚀 Start server
    server.listen(port, () => {
      console.log(`🚀 WebSocket server running on port ${port}`);
    });

    // 🧹 Cleanup on shutdown
    process.on('SIGTERM', () => this.shutdown());
    process.on('SIGINT', () => this.shutdown());
  }

  private handleConnection(socket: WebSocket, request: any): void {
    const clientId = uuidv4();
    const client: ConnectedClient = {
      id: clientId,
      socket,
      isAlive: true,
      lastPong: Date.now()
    };

    this.clients.set(clientId, client);

    console.log(`🔌 New client connected: ${clientId}`);
    console.log(`👥 Total clients: ${this.clients.size}`);

    // 🎧 Setup client event handlers
    socket.on('message', (data) => {
      this.handleMessage(clientId, data);
    });

    socket.on('close', (code, reason) => {
      this.handleDisconnection(clientId, code, reason.toString());
    });

    socket.on('error', (error) => {
      console.error(`❌ Client ${clientId} error:`, error);
    });

    socket.on('pong', () => {
      const client = this.clients.get(clientId);
      if (client) {
        client.isAlive = true;
        client.lastPong = Date.now();
      }
    });

    // 👋 Send welcome message
    this.sendToClient(clientId, {
      type: 'server_message',
      content: 'Welcome to the chat server!',
      timestamp: Date.now(),
      id: uuidv4()
    } as any);
  }

  private handleMessage(clientId: string, data: WebSocket.Data): void {
    const client = this.clients.get(clientId);
    if (!client) return;

    try {
      const message: WebSocketMessage = JSON.parse(data.toString());
      console.log(`📨 Message from ${clientId}:`, message.type);

      switch (message.type) {
        case 'auth':
          this.handleAuth(clientId, message as AuthMessage);
          break;
        
        case 'join_room':
          this.handleJoinRoom(clientId, message as JoinRoomMessage);
          break;
        
        case 'leave_room':
          this.handleLeaveRoom(clientId, message as LeaveRoomMessage);
          break;
        
        case 'chat_message':
          this.handleChatMessage(clientId, message as ChatMessage);
          break;
        
        case 'typing':
          this.handleTyping(clientId, message as TypingMessage);
          break;
        
        case 'ping':
          this.handlePing(clientId);
          break;
        
        default:
          console.warn(`🤷 Unknown message type: ${(message as any).type}`);
      }
    } catch (error) {
      console.error(`❌ Failed to parse message from ${clientId}:`, error);
      this.sendToClient(clientId, {
        type: 'error',
        message: 'Invalid message format',
        timestamp: Date.now(),
        id: uuidv4()
      } as any);
    }
  }

  private handleAuth(clientId: string, message: AuthMessage): void {
    const client = this.clients.get(clientId);
    if (!client) return;

    // 🔐 Set user information
    client.user = {
      id: message.userId,
      username: message.username
    };

    console.log(`✅ Client ${clientId} authenticated as ${message.username}`);

    // 📝 Send authentication confirmation
    this.sendToClient(clientId, {
      type: 'auth_success',
      userId: message.userId,
      username: message.username,
      timestamp: Date.now(),
      id: uuidv4()
    } as any);

    // 🏠 Send available rooms
    this.sendRoomList(clientId);
  }

  private handleJoinRoom(clientId: string, message: JoinRoomMessage): void {
    const client = this.clients.get(clientId);
    if (!client || !client.user) return;

    const roomId = message.roomId;
    
    // 🏠 Create room if it doesn't exist
    if (!this.rooms.has(roomId)) {
      this.rooms.set(roomId, {
        id: roomId,
        name: `Room ${roomId}`,
        clients: new Set(),
        messageHistory: [],
        createdAt: Date.now()
      });
      console.log(`🏠 Created new room: ${roomId}`);
    }

    const room = this.rooms.get(roomId)!;

    // 🚪 Leave current room if in one
    if (client.room) {
      this.leaveClientFromRoom(clientId);
    }

    // 🏠 Join new room
    client.room = roomId;
    room.clients.add(clientId);

    console.log(`🏠 ${client.user.username} joined room ${roomId}`);

    // 📝 Send room joined confirmation
    this.sendToClient(clientId, {
      type: 'room_joined',
      roomId,
      roomName: room.name,
      timestamp: Date.now(),
      id: uuidv4()
    } as any);

    // 📜 Send message history
    room.messageHistory.forEach(msg => {
      this.sendToClient(clientId, msg);
    });

    // 👥 Send user list
    this.sendUserListToRoom(roomId);

    // 📢 Announce user joined to room
    const joinMessage: UserJoinedMessage = {
      type: 'user_joined',
      userId: client.user.id,
      username: client.user.username,
      timestamp: Date.now(),
      id: uuidv4()
    };

    this.broadcastToRoom(roomId, joinMessage, clientId);
  }

  private handleLeaveRoom(clientId: string, message: LeaveRoomMessage): void {
    this.leaveClientFromRoom(clientId);
  }

  private leaveClientFromRoom(clientId: string): void {
    const client = this.clients.get(clientId);
    if (!client || !client.room || !client.user) return;

    const room = this.rooms.get(client.room);
    if (!room) return;

    // 🚪 Remove from room
    room.clients.delete(clientId);
    console.log(`🚪 ${client.user.username} left room ${client.room}`);

    // 📢 Announce user left to room
    const leftMessage: UserLeftMessage = {
      type: 'user_left',
      userId: client.user.id,
      username: client.user.username,
      timestamp: Date.now(),
      id: uuidv4()
    };

    this.broadcastToRoom(client.room, leftMessage, clientId);

    // 👥 Update user list for remaining clients
    this.sendUserListToRoom(client.room);

    // 🧹 Clean up empty rooms
    if (room.clients.size === 0) {
      this.rooms.delete(client.room);
      console.log(`🗑️ Removed empty room: ${client.room}`);
    }

    client.room = undefined;
  }

  private handleChatMessage(clientId: string, message: ChatMessage): void {
    const client = this.clients.get(clientId);
    if (!client || !client.room || !client.user) {
      console.warn(`⚠️ Unauthorized chat message from ${clientId}`);
      return;
    }

    const room = this.rooms.get(client.room);
    if (!room) return;

    // 💾 Store message in room history
    room.messageHistory.push(message);

    // 📝 Limit history size (keep last 100 messages)
    if (room.messageHistory.length > 100) {
      room.messageHistory = room.messageHistory.slice(-100);
    }

    console.log(`💬 ${client.user.username} in ${client.room}: ${message.content}`);

    // 📢 Broadcast message to all room members
    this.broadcastToRoom(client.room, message);
  }

  private handleTyping(clientId: string, message: TypingMessage): void {
    const client = this.clients.get(clientId);
    if (!client || !client.room) return;

    // 📢 Broadcast typing indicator to room (except sender)
    this.broadcastToRoom(client.room, message, clientId);
  }

  private handlePing(clientId: string): void {
    // 💓 Respond with pong
    this.sendToClient(clientId, {
      type: 'pong',
      timestamp: Date.now(),
      id: uuidv4()
    } as any);
  }

  private handleDisconnection(clientId: string, code: number, reason: string): void {
    const client = this.clients.get(clientId);
    
    console.log(`🔌 Client ${clientId} disconnected: ${code} - ${reason}`);
    
    if (client && client.room) {
      this.leaveClientFromRoom(clientId);
    }

    this.clients.delete(clientId);
    console.log(`👥 Total clients: ${this.clients.size}`);
  }

  // 💓 Heartbeat mechanism
  private performHeartbeat(): void {
    const now = Date.now();
    
    this.clients.forEach((client, clientId) => {
      if (!client.isAlive || (now - client.lastPong) > 60000) {
        // 💀 Client is dead, terminate connection
        console.log(`💀 Terminating dead client: ${clientId}`);
        client.socket.terminate();
        return;
      }

      client.isAlive = false;
      client.socket.ping();
    });
  }

  // 📤 Send message to specific client
  private sendToClient(clientId: string, message: any): void {
    const client = this.clients.get(clientId);
    if (!client || client.socket.readyState !== WebSocket.OPEN) return;

    try {
      client.socket.send(JSON.stringify(message));
    } catch (error) {
      console.error(`❌ Failed to send message to ${clientId}:`, error);
    }
  }

  // 📢 Broadcast message to all clients in a room
  private broadcastToRoom(roomId: string, message: any, excludeClientId?: string): void {
    const room = this.rooms.get(roomId);
    if (!room) return;

    room.clients.forEach(clientId => {
      if (clientId !== excludeClientId) {
        this.sendToClient(clientId, message);
      }
    });
  }

  // 🏠 Send room list to client
  private sendRoomList(clientId: string): void {
    const roomList = Array.from(this.rooms.values()).map(room => ({
      id: room.id,
      name: room.name,
      userCount: room.clients.size
    }));

    this.sendToClient(clientId, {
      type: 'room_list',
      rooms: roomList,
      timestamp: Date.now(),
      id: uuidv4()
    });
  }

  // 👥 Send user list to all clients in room
  private sendUserListToRoom(roomId: string): void {
    const room = this.rooms.get(roomId);
    if (!room) return;

    const users = Array.from(room.clients)
      .map(clientId => {
        const client = this.clients.get(clientId);
        return client?.user ? {
          id: client.user.id,
          username: client.user.username
        } : null;
      })
      .filter(user => user !== null);

    const userListMessage = {
      type: 'user_list',
      users,
      timestamp: Date.now(),
      id: uuidv4()
    };

    this.broadcastToRoom(roomId, userListMessage);
  }

  // 📊 Server statistics
  getStats(): any {
    return {
      totalClients: this.clients.size,
      totalRooms: this.rooms.size,
      authenticatedClients: Array.from(this.clients.values()).filter(c => c.user).length,
      roomsWithClients: Array.from(this.rooms.values()).filter(r => r.clients.size > 0).length
    };
  }

  // 🔌 Shutdown server gracefully
  private shutdown(): void {
    console.log('🛑 Shutting down WebSocket server...');
    
    clearInterval(this.heartbeatInterval);
    
    // 👋 Send goodbye message to all clients
    this.clients.forEach((client, clientId) => {
      this.sendToClient(clientId, {
        type: 'server_shutdown',
        message: 'Server is shutting down',
        timestamp: Date.now(),
        id: uuidv4()
      });
      
      setTimeout(() => {
        client.socket.close(1001, 'Server shutdown');
      }, 1000);
    });

    // 🔌 Close WebSocket server
    setTimeout(() => {
      this.wss.close(() => {
        console.log('✅ WebSocket server closed');
        process.exit(0);
      });
    }, 2000);
  }
}

// 🚀 Start the server
const chatServer = new WebSocketChatServer(8080);

// 📊 Log stats every 30 seconds
setInterval(() => {
  const stats = chatServer.getStats();
  console.log('📊 Server stats:', stats);
}, 30000);

🎨 Advanced WebSocket Patterns

🔄 Connection Pool Management

For applications that need to manage multiple WebSocket connections:

// 🏊 WebSocket connection pool for managing multiple connections
interface ConnectionConfig {
  url: string;
  protocols?: string[];
  autoReconnect?: boolean;
  maxReconnectAttempts?: number;
}

class WebSocketConnectionPool {
  private connections = new Map<string, TypeSafeWebSocketClient>();
  private connectionConfigs = new Map<string, ConnectionConfig>();

  async addConnection(
    name: string,
    config: ConnectionConfig
  ): Promise<TypeSafeWebSocketClient> {
    if (this.connections.has(name)) {
      throw new Error(`Connection '${name}' already exists`);
    }

    console.log(`🔌 Adding connection: ${name}`);
    
    const client = new TypeSafeWebSocketClient(config.url, {
      autoReconnect: config.autoReconnect ?? true,
      maxReconnectAttempts: config.maxReconnectAttempts ?? 5
    });

    // 🎧 Setup common event handlers
    client.on('connected', () => {
      console.log(`✅ Connection '${name}' established`);
    });

    client.on('disconnected', (reason) => {
      console.log(`🔌 Connection '${name}' disconnected: ${reason}`);
    });

    client.on('error', (error) => {
      console.error(`❌ Connection '${name}' error:`, error);
    });

    try {
      await client.connect();
      this.connections.set(name, client);
      this.connectionConfigs.set(name, config);
      return client;
    } catch (error) {
      console.error(`❌ Failed to add connection '${name}':`, error);
      throw error;
    }
  }

  getConnection(name: string): TypeSafeWebSocketClient | undefined {
    return this.connections.get(name);
  }

  async removeConnection(name: string): Promise<void> {
    const connection = this.connections.get(name);
    if (!connection) {
      console.warn(`⚠️ Connection '${name}' not found`);
      return;
    }

    console.log(`🗑️ Removing connection: ${name}`);
    connection.disconnect();
    this.connections.delete(name);
    this.connectionConfigs.delete(name);
  }

  // 📢 Broadcast message to all connections
  broadcastToAll(message: any): void {
    this.connections.forEach((connection, name) => {
      if (connection.isConnected()) {
        connection.send(message);
      } else {
        console.warn(`⚠️ Connection '${name}' not connected, skipping broadcast`);
      }
    });
  }

  // 📢 Broadcast to specific connections
  broadcastToConnections(connectionNames: string[], message: any): void {
    connectionNames.forEach(name => {
      const connection = this.connections.get(name);
      if (connection?.isConnected()) {
        connection.send(message);
      } else {
        console.warn(`⚠️ Connection '${name}' not found or not connected`);
      }
    });
  }

  // 📊 Get pool status
  getStatus(): Array<{ name: string; connected: boolean; state: string }> {
    return Array.from(this.connections.entries()).map(([name, connection]) => ({
      name,
      connected: connection.isConnected(),
      state: connection.getReadyState()
    }));
  }

  // 🔄 Reconnect all disconnected connections
  async reconnectAll(): Promise<void> {
    const reconnectPromises = Array.from(this.connections.entries())
      .filter(([, connection]) => !connection.isConnected())
      .map(async ([name, connection]) => {
        try {
          console.log(`🔄 Reconnecting '${name}'...`);
          await connection.connect();
          console.log(`✅ '${name}' reconnected`);
        } catch (error) {
          console.error(`❌ Failed to reconnect '${name}':`, error);
        }
      });

    await Promise.allSettled(reconnectPromises);
  }

  // 🧹 Cleanup all connections
  async cleanup(): Promise<void> {
    console.log('🧹 Cleaning up WebSocket connection pool...');
    
    const cleanupPromises = Array.from(this.connections.keys()).map(name =>
      this.removeConnection(name)
    );

    await Promise.allSettled(cleanupPromises);
    console.log('✅ Connection pool cleanup complete');
  }
}