📡 Server-Sent Events: One-Way Communication in TypeScript

🎯 Introduction

Welcome to the world of Server-Sent Events! 📡 If WebSockets are like having a phone conversation (two-way), then Server-Sent Events (SSE) are like listening to a live radio broadcast - perfect for when you need real-time updates flowing from server to client!

Think of SSE as a persistent connection 📻 where your server can push live updates, notifications, news feeds, stock prices, or any real-time data directly to your clients. It’s simpler than WebSockets when you only need one-way communication, and it comes with built-in browser support for automatic reconnection!

By the end of this tutorial, you’ll be a master of real-time streaming, able to build live dashboards, notification systems, chat feeds, and any application that needs instant server-to-client updates. Let’s start streaming! 🌊

📚 Understanding Server-Sent Events

🤔 What Are Server-Sent Events?

Server-Sent Events provide a simple way for servers to push data to web pages over HTTP. Unlike WebSockets, SSE is unidirectional - only the server can send data to the client. But that’s perfect for many real-time use cases!

// 🌟 Basic Server-Sent Events connection
// client.ts - Browser SSE client
class BasicSSEClient {
  private eventSource: EventSource | null = null;

  connect(url: string): void {
    console.log('📡 Connecting to SSE stream...');
    
    // 🔌 Create EventSource connection
    this.eventSource = new EventSource(url);

    // 🎧 Listen for incoming messages
    this.eventSource.onmessage = (event) => {
      console.log('📨 Message received:', event.data);
      this.handleMessage(JSON.parse(event.data));
    };

    // ✅ Connection opened successfully
    this.eventSource.onopen = () => {
      console.log('✅ SSE connection established!');
    };

    // ❌ Handle connection errors
    this.eventSource.onerror = (error) => {
      console.error('❌ SSE connection error:', error);
      
      // 🔍 Check connection state
      if (this.eventSource?.readyState === EventSource.CLOSED) {
        console.log('🔌 SSE connection closed');
      } else if (this.eventSource?.readyState === EventSource.CONNECTING) {
        console.log('🔄 SSE reconnecting...');
      }
    };
  }

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

  disconnect(): void {
    if (this.eventSource) {
      console.log('🔌 Closing SSE connection...');
      this.eventSource.close();
      this.eventSource = null;
    }
  }
}

// 🚀 Simple usage
const sseClient = new BasicSSEClient();
sseClient.connect('/api/events');

💡 Key Characteristics

• 📡 Server-to-Client Only: Unidirectional communication
• 🔄 Automatic Reconnection: Built-in reconnection on connection loss
• 📦 Text-Based Protocol: Simple HTTP-based streaming
• 🎯 Event-Driven: Native browser EventSource API support

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

interface NotificationMessage extends SSEMessage {
  type: 'notification';
  title: string;
  message: string;
  severity: 'info' | 'warning' | 'error' | 'success';
}

interface StockUpdateMessage extends SSEMessage {
  type: 'stock_update';
  symbol: string;
  price: number;
  change: number;
  changePercent: number;
}

interface SystemStatusMessage extends SSEMessage {
  type: 'system_status';
  service: string;
  status: 'online' | 'offline' | 'degraded';
  uptime: number;
}

interface ChatMessage extends SSEMessage {
  type: 'chat_message';
  username: string;
  content: string;
  roomId: string;
}

// 🎯 Union type for all possible SSE messages
type SSEEventMessage = NotificationMessage | StockUpdateMessage | SystemStatusMessage | ChatMessage;

// 📦 Message factory for type safety
class SSEMessageFactory {
  static createNotification(
    title: string, 
    message: string, 
    severity: NotificationMessage['severity']
  ): NotificationMessage {
    return {
      type: 'notification',
      title,
      message,
      severity,
      timestamp: Date.now(),
      id: crypto.randomUUID()
    };
  }

  static createStockUpdate(
    symbol: string, 
    price: number, 
    change: number
  ): StockUpdateMessage {
    return {
      type: 'stock_update',
      symbol,
      price,
      change,
      changePercent: (change / (price - change)) * 100,
      timestamp: Date.now(),
      id: crypto.randomUUID()
    };
  }

  static createSystemStatus(
    service: string, 
    status: SystemStatusMessage['status'], 
    uptime: number
  ): SystemStatusMessage {
    return {
      type: 'system_status',
      service,
      status,
      uptime,
      timestamp: Date.now(),
      id: crypto.randomUUID()
    };
  }
}

🆚 SSE vs Other Real-Time Technologies

// 📊 Comparison of real-time communication methods

// 🐌 HTTP Polling - inefficient, not real-time
class PollingClient {
  private intervalId: number | null = null;

  startPolling(url: string, interval = 5000): void {
    // ❌ Wasteful - constant HTTP requests
    this.intervalId = window.setInterval(async () => {
      try {
        const response = await fetch(url);
        const data = await response.json();
        console.log('📊 Polled data:', data);
      } catch (error) {
        console.error('Polling error:', error);
      }
    }, interval);
  }

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

// 📡 Server-Sent Events - efficient one-way streaming
class SSEClient {
  private eventSource: EventSource | null = null;

  connect(url: string): void {
    // ✅ Efficient persistent connection
    this.eventSource = new EventSource(url);
    
    this.eventSource.onmessage = (event) => {
      console.log('📡 Real-time update:', JSON.parse(event.data));
    };
  }

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

// 🔌 WebSocket - bidirectional communication
class WebSocketClient {
  private socket: WebSocket | null = null;

  connect(url: string): void {
    // ✅ Bidirectional but more complex
    this.socket = new WebSocket(url);
    
    this.socket.onmessage = (event) => {
      console.log('🔌 WebSocket message:', JSON.parse(event.data));
    };

    // Can send messages back to server
    setTimeout(() => {
      this.send({ type: 'ping' });
    }, 1000);
  }

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

// 🎯 Use case comparison
const useCases = {
  // ✅ Use SSE for:
  sse: [
    '📊 Live dashboards and metrics',
    '🔔 Real-time notifications',
    '📰 News feeds and updates',
    '💹 Stock price feeds',
    '📝 Activity logs',
    '🎮 Live scoreboards',
    '📈 Analytics data streams'
  ],
  
  // ✅ Use WebSockets for:
  websockets: [
    '💬 Chat applications',
    '🎮 Real-time games',
    '✏️ Collaborative editing',
    '🎥 Video conferencing',
    '🎯 Any bidirectional communication'
  ],
  
  // ✅ Use Polling for:
  polling: [
    '🗂️ Infrequent updates',
    '📊 Non-critical data',
    '🔧 Simple implementations',
    '🌐 Limited browser support scenarios'
  ]
};

🏗️ Building a Type-Safe SSE Client

🎯 Advanced SSE Client Implementation

Let’s build a production-ready SSE client with TypeScript that handles all the edge cases:

// 🏗️ Advanced SSE client with full TypeScript support
interface SSEClientConfig {
  autoReconnect?: boolean;
  maxReconnectAttempts?: number;
  reconnectDelay?: number;
  withCredentials?: boolean;
  customHeaders?: Record<string, string>;
}

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

class TypeSafeSSEClient {
  private eventSource: EventSource | null = null;
  private reconnectAttempts = 0;
  private reconnectTimer: number | null = null;
  private eventListeners: Partial<SSEClientEvents> = {};
  private lastEventId: string | null = null;

  constructor(
    private url: string,
    private config: SSEClientConfig = {}
  ) {
    // 🎛️ Default configuration
    this.config = {
      autoReconnect: true,
      maxReconnectAttempts: 5,
      reconnectDelay: 1000,
      withCredentials: false,
      ...config
    };
  }

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

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

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

  // 🔌 Connection management
  connect(): void {
    console.log('📡 Initiating SSE connection...');
    
    try {
      // 🔧 Build URL with Last-Event-ID if available
      const urlWithParams = this.buildUrlWithParams();
      
      // 🏗️ Create EventSource with configuration
      this.eventSource = new EventSource(urlWithParams, {
        withCredentials: this.config.withCredentials
      });

      this.setupEventHandlers();
    } catch (error) {
      console.error('❌ Failed to create SSE connection:', error);
      this.emit('error', new Error('Failed to create SSE connection'));
    }
  }

  private buildUrlWithParams(): string {
    const url = new URL(this.url, window.location.origin);
    
    // 🔄 Add Last-Event-ID for reliable reconnection
    if (this.lastEventId) {
      url.searchParams.set('lastEventId', this.lastEventId);
    }

    return url.toString();
  }

  private setupEventHandlers(): void {
    if (!this.eventSource) return;

    // ✅ Connection opened
    this.eventSource.onopen = () => {
      console.log('✅ SSE connection established!');
      this.reconnectAttempts = 0;
      this.clearReconnectTimer();
      this.emit('connected');
    };

    // 📨 Message received
    this.eventSource.onmessage = (event) => {
      try {
        // 🔖 Store Last-Event-ID for reconnection
        if (event.lastEventId) {
          this.lastEventId = event.lastEventId;
        }

        const message: SSEEventMessage = JSON.parse(event.data);
        console.log('📨 SSE message received:', message.type);
        this.emit('message', message);
      } catch (error) {
        console.error('❌ Failed to parse SSE message:', error);
        this.emit('error', new Error('Failed to parse SSE message'));
      }
    };

    // ❌ Connection error or closed
    this.eventSource.onerror = (error) => {
      console.error('❌ SSE connection error:', error);
      
      const readyState = this.eventSource?.readyState;
      
      if (readyState === EventSource.CLOSED) {
        console.log('🔌 SSE connection closed');
        this.emit('disconnected', 'Connection closed');
        
        if (this.config.autoReconnect) {
          this.attemptReconnect();
        }
      } else if (readyState === EventSource.CONNECTING) {
        console.log('🔄 SSE reconnecting...');
      } else {
        this.emit('error', new Error('SSE connection error'));
      }
    };

    // 🎯 Custom event listeners for different message types
    this.setupCustomEventListeners();
  }

  private setupCustomEventListeners(): void {
    if (!this.eventSource) return;

    // 🔔 Notification events
    this.eventSource.addEventListener('notification', (event) => {
      try {
        const message: NotificationMessage = JSON.parse(event.data);
        this.emit('message', message);
      } catch (error) {
        console.error('❌ Failed to parse notification:', error);
      }
    });

    // 💹 Stock update events
    this.eventSource.addEventListener('stock_update', (event) => {
      try {
        const message: StockUpdateMessage = JSON.parse(event.data);
        this.emit('message', message);
      } catch (error) {
        console.error('❌ Failed to parse stock update:', error);
      }
    });

    // 🔧 System status events
    this.eventSource.addEventListener('system_status', (event) => {
      try {
        const message: SystemStatusMessage = JSON.parse(event.data);
        this.emit('message', message);
      } catch (error) {
        console.error('❌ Failed to parse system status:', error);
      }
    });
  }

  // 🔄 Reconnection logic
  private attemptReconnect(): void {
    if (this.reconnectAttempts >= (this.config.maxReconnectAttempts || 5)) {
      console.error('💥 Max reconnection attempts exceeded');
      this.emit('error', new 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);

    this.reconnectTimer = window.setTimeout(() => {
      this.connect();
    }, delay);
  }

  private clearReconnectTimer(): void {
    if (this.reconnectTimer) {
      clearTimeout(this.reconnectTimer);
      this.reconnectTimer = null;
    }
  }

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

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

  // 🔌 Disconnect
  disconnect(): void {
    console.log('🔌 Disconnecting SSE...');
    
    this.config.autoReconnect = false; // Prevent auto-reconnect
    this.clearReconnectTimer();
    
    if (this.eventSource) {
      this.eventSource.close();
      this.eventSource = null;
    }
    
    this.lastEventId = null;
    this.reconnectAttempts = 0;
  }
}

🛠️ Real-World Notification System

Let’s build a complete notification system using SSE:

// 🔔 Real-time notification system using SSE
interface NotificationOptions {
  autoClose?: boolean;
  autoCloseDelay?: number;
  showTimestamp?: boolean;
  allowDismiss?: boolean;
}

interface DisplayedNotification extends NotificationMessage {
  displayId: string;
  createdAt: Date;
  dismissed: boolean;
}

class RealTimeNotificationSystem {
  private sseClient: TypeSafeSSEClient;
  private notifications: Map<string, DisplayedNotification> = new Map();
  private notificationContainer: HTMLElement;
  private maxNotifications = 5;

  constructor(private sseUrl: string) {
    this.sseClient = new TypeSafeSSEClient(sseUrl, {
      autoReconnect: true,
      maxReconnectAttempts: 10,
      reconnectDelay: 2000
    });

    this.setupNotificationContainer();
    this.setupSSEEventHandlers();
  }

  private setupNotificationContainer(): void {
    // 🎨 Create notification container if it doesn't exist
    this.notificationContainer = document.getElementById('notifications') 
      || this.createNotificationContainer();
  }

  private createNotificationContainer(): HTMLElement {
    const container = document.createElement('div');
    container.id = 'notifications';
    container.className = 'notification-container';
    container.style.cssText = `
      position: fixed;
      top: 20px;
      right: 20px;
      z-index: 10000;
      max-width: 400px;
      pointer-events: none;
    `;
    
    document.body.appendChild(container);
    return container;
  }

  private setupSSEEventHandlers(): void {
    // 🎧 Handle SSE connection events
    this.sseClient.on('connected', () => {
      console.log('🎉 Notification system connected!');
      this.showSystemNotification('Connected to notification service', 'success');
    });

    this.sseClient.on('disconnected', (reason) => {
      console.log('😞 Notification system disconnected:', reason);
      this.showSystemNotification('Disconnected from notification service', 'warning');
    });

    this.sseClient.on('reconnecting', (attempt) => {
      console.log(`🔄 Reconnecting to notification service (attempt ${attempt})...`);
    });

    this.sseClient.on('error', (error) => {
      console.error('💥 Notification system error:', error);
      this.showSystemNotification('Notification service error', 'error');
    });

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

  // 🚀 Initialize the notification system
  async initialize(): Promise<void> {
    try {
      this.sseClient.connect();
      console.log('✅ Notification system initialized!');
    } catch (error) {
      console.error('❌ Failed to initialize notification system:', error);
      throw error;
    }
  }

  // 📨 Handle incoming SSE messages
  private handleIncomingMessage(message: SSEEventMessage): void {
    switch (message.type) {
      case 'notification':
        this.handleNotification(message);
        break;
      
      case 'stock_update':
        this.handleStockUpdate(message);
        break;
      
      case 'system_status':
        this.handleSystemStatus(message);
        break;
      
      case 'chat_message':
        this.handleChatMessage(message);
        break;
      
      default:
        console.warn('🤷 Unknown message type:', (message as any).type);
    }
  }

  private handleNotification(notification: NotificationMessage): void {
    console.log(`🔔 Notification: ${notification.title}`);
    
    this.displayNotification(notification, {
      autoClose: notification.severity !== 'error',
      autoCloseDelay: 5000,
      showTimestamp: true,
      allowDismiss: true
    });
  }

  private handleStockUpdate(stockUpdate: StockUpdateMessage): void {
    console.log(`💹 Stock Update: ${stockUpdate.symbol} - $${stockUpdate.price}`);
    
    // 📊 Create notification for significant price changes
    if (Math.abs(stockUpdate.changePercent) > 5) {
      const notification = SSEMessageFactory.createNotification(
        `${stockUpdate.symbol} Alert`,
        `Price ${stockUpdate.change > 0 ? 'increased' : 'decreased'} by ${stockUpdate.changePercent.toFixed(2)}%`,
        stockUpdate.change > 0 ? 'success' : 'warning'
      );
      
      this.displayNotification(notification, {
        autoClose: true,
        autoCloseDelay: 8000
      });
    }
  }

  private handleSystemStatus(status: SystemStatusMessage): void {
    console.log(`🔧 System Status: ${status.service} - ${status.status}`);
    
    // 🚨 Show notifications for service issues
    if (status.status !== 'online') {
      const notification = SSEMessageFactory.createNotification(
        'Service Alert',
        `${status.service} is currently ${status.status}`,
        status.status === 'offline' ? 'error' : 'warning'
      );
      
      this.displayNotification(notification, {
        autoClose: status.status === 'degraded',
        autoCloseDelay: 10000
      });
    }
  }

  private handleChatMessage(chatMessage: ChatMessage): void {
    console.log(`💬 Chat: ${chatMessage.username}: ${chatMessage.content}`);
    
    // 🔔 Show notification for chat messages (if not in focus)
    if (document.hidden) {
      const notification = SSEMessageFactory.createNotification(
        `New message from ${chatMessage.username}`,
        chatMessage.content,
        'info'
      );
      
      this.displayNotification(notification, {
        autoClose: true,
        autoCloseDelay: 4000
      });
    }
  }

  // 🎨 Display notification in UI
  private displayNotification(
    notification: NotificationMessage, 
    options: NotificationOptions = {}
  ): void {
    const displayNotification: DisplayedNotification = {
      ...notification,
      displayId: `notif-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`,
      createdAt: new Date(),
      dismissed: false
    };

    // 🧹 Remove oldest notifications if at limit
    this.enforceNotificationLimit();

    // 📦 Store notification
    this.notifications.set(displayNotification.displayId, displayNotification);

    // 🎨 Create and display notification element
    const notificationElement = this.createNotificationElement(displayNotification, options);
    this.notificationContainer.appendChild(notificationElement);

    // ⏰ Auto-close if configured
    if (options.autoClose) {
      setTimeout(() => {
        this.dismissNotification(displayNotification.displayId);
      }, options.autoCloseDelay || 5000);
    }

    // 📢 Trigger browser notification if page is not visible
    this.triggerBrowserNotification(notification);
  }

  private createNotificationElement(
    notification: DisplayedNotification, 
    options: NotificationOptions
  ): HTMLElement {
    const element = document.createElement('div');
    element.id = notification.displayId;
    element.className = `notification notification-${notification.severity}`;
    element.style.cssText = `
      background: white;
      border-radius: 8px;
      box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
      margin-bottom: 12px;
      padding: 16px;
      border-left: 4px solid ${this.getSeverityColor(notification.severity)};
      opacity: 0;
      transform: translateX(100%);
      transition: all 0.3s ease;
      pointer-events: auto;
      max-width: 100%;
      word-wrap: break-word;
    `;

    // 📝 Create notification content
    const content = `
      <div style="display: flex; justify-content: space-between; align-items: flex-start;">
        <div style="flex: 1;">
          <h4 style="margin: 0 0 8px 0; font-weight: 600; color: #333;">
            ${this.getSeverityIcon(notification.severity)} ${notification.title}
          </h4>
          <p style="margin: 0; color: #666; line-height: 1.4;">
            ${notification.message}
          </p>
          ${options.showTimestamp ? `
            <small style="color: #999; font-size: 0.8em; margin-top: 8px; display: block;">
              ${notification.createdAt.toLocaleTimeString()}
            </small>
          ` : ''}
        </div>
        ${options.allowDismiss ? `
          <button 
            onclick="notificationSystem.dismissNotification('${notification.displayId}')"
            style="
              background: none; 
              border: none; 
              font-size: 18px; 
              cursor: pointer; 
              color: #999;
              padding: 0;
              margin-left: 12px;
            "
          >×</button>
        ` : ''}
      </div>
    `;

    element.innerHTML = content;

    // 🎭 Animate in
    setTimeout(() => {
      element.style.opacity = '1';
      element.style.transform = 'translateX(0)';
    }, 10);

    return element;
  }

  private getSeverityColor(severity: NotificationMessage['severity']): string {
    const colors = {
      success: '#10B981',
      info: '#3B82F6',
      warning: '#F59E0B',
      error: '#EF4444'
    };
    return colors[severity];
  }

  private getSeverityIcon(severity: NotificationMessage['severity']): string {
    const icons = {
      success: '✅',
      info: 'ℹ️',
      warning: '⚠️',
      error: '❌'
    };
    return icons[severity];
  }

  // 🗑️ Dismiss notification
  dismissNotification(displayId: string): void {
    const notification = this.notifications.get(displayId);
    if (!notification || notification.dismissed) return;

    const element = document.getElementById(displayId);
    if (element) {
      // 🎭 Animate out
      element.style.opacity = '0';
      element.style.transform = 'translateX(100%)';
      
      setTimeout(() => {
        element.remove();
      }, 300);
    }

    // 🧹 Mark as dismissed
    notification.dismissed = true;
    this.notifications.delete(displayId);
  }

  private enforceNotificationLimit(): void {
    const activeNotifications = Array.from(this.notifications.values())
      .filter(n => !n.dismissed)
      .sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime());

    // 🗑️ Remove oldest notifications if over limit
    while (activeNotifications.length >= this.maxNotifications) {
      const oldest = activeNotifications.shift();
      if (oldest) {
        this.dismissNotification(oldest.displayId);
      }
    }
  }

  // 📢 Trigger browser notification
  private async triggerBrowserNotification(notification: NotificationMessage): Promise<void> {
    if (!('Notification' in window) || document.visibilityState === 'visible') {
      return;
    }

    // 🔔 Request permission if needed
    if (Notification.permission === 'default') {
      await Notification.requestPermission();
    }

    if (Notification.permission === 'granted') {
      new Notification(notification.title, {
        body: notification.message,
        icon: '/favicon.ico',
        tag: notification.id,
        requireInteraction: notification.severity === 'error'
      });
    }
  }

  // 📊 Show system notification
  private showSystemNotification(message: string, severity: NotificationMessage['severity']): void {
    const notification = SSEMessageFactory.createNotification(
      'System',
      message,
      severity
    );
    
    this.displayNotification(notification, {
      autoClose: true,
      autoCloseDelay: 3000,
      showTimestamp: false
    });
  }

  // 📊 Get notification statistics
  getStats(): any {
    const all = Array.from(this.notifications.values());
    const active = all.filter(n => !n.dismissed);
    
    return {
      total: all.length,
      active: active.length,
      dismissed: all.length - active.length,
      byseverity: {
        success: all.filter(n => n.severity === 'success').length,
        info: all.filter(n => n.severity === 'info').length,
        warning: all.filter(n => n.severity === 'warning').length,
        error: all.filter(n => n.severity === 'error').length
      },
      connectionState: this.sseClient.getReadyState()
    };
  }

  // 🔌 Disconnect from SSE
  disconnect(): void {
    this.sseClient.disconnect();
    
    // 🧹 Clear all notifications
    this.notifications.forEach((_, displayId) => {
      this.dismissNotification(displayId);
    });
  }
}

// 🌍 Global instance for use in HTML onclick handlers
let notificationSystem: RealTimeNotificationSystem;

// 🚀 Initialize notification system
async function initializeNotificationSystem(): Promise<void> {
  notificationSystem = new RealTimeNotificationSystem('/api/sse');
  await notificationSystem.initialize();
}

🛠️ Server-Side SSE Implementation

🏗️ Node.js SSE Server with TypeScript

Let’s create a robust SSE server using Node.js and Express:

// 🖥️ Server-side SSE implementation with Node.js and Express
import express from 'express';
import cors from 'cors';
import { v4 as uuidv4 } from 'uuid';

interface SSEConnection {
  id: string;
  response: express.Response;
  userId?: string;
  lastEventId?: string;
  connectedAt: Date;
  isAlive: boolean;
}

interface SSEChannel {
  name: string;
  connections: Map<string, SSEConnection>;
  messageHistory: Array<{ id: string; data: any; type?: string; timestamp: Date }>;
  maxHistorySize: number;
}

class SSEServer {
  private app: express.Application;
  private connections = new Map<string, SSEConnection>();
  private channels = new Map<string, SSEChannel>();
  private heartbeatInterval: NodeJS.Timeout;

  constructor(private port = 3000) {
    this.app = express();
    this.setupMiddleware();
    this.setupRoutes();
    this.setupHeartbeat();
    
    // 🏗️ Create default channels
    this.createChannel('notifications', 100);
    this.createChannel('stock-updates', 50);
    this.createChannel('system-status', 20);
    this.createChannel('chat', 200);
  }

  private setupMiddleware(): void {
    // 🌐 CORS configuration for SSE
    this.app.use(cors({
      origin: true,
      credentials: true
    }));

    this.app.use(express.json());
    this.app.use(express.static('public'));

    // 📝 Request logging
    this.app.use((req, res, next) => {
      console.log(`${new Date().toISOString()} - ${req.method} ${req.path}`);
      next();
    });
  }

  private setupRoutes(): void {
    // 📡 Main SSE endpoint
    this.app.get('/api/sse', (req, res) => {
      this.handleSSEConnection(req, res);
    });

    // 📡 Channel-specific SSE endpoints
    this.app.get('/api/sse/:channel', (req, res) => {
      this.handleSSEConnection(req, res, req.params.channel);
    });

    // 📤 Send notification endpoint
    this.app.post('/api/send-notification', (req, res) => {
      this.sendNotification(req.body);
      res.json({ success: true });
    });

    // 📊 Send stock update endpoint
    this.app.post('/api/send-stock-update', (req, res) => {
      this.sendStockUpdate(req.body);
      res.json({ success: true });
    });

    // 🔧 Send system status endpoint
    this.app.post('/api/send-system-status', (req, res) => {
      this.sendSystemStatus(req.body);
      res.json({ success: true });
    });

    // 📊 Server statistics endpoint
    this.app.get('/api/sse-stats', (req, res) => {
      res.json(this.getServerStats());
    });

    // 🏠 Demo page
    this.app.get('/', (req, res) => {
      res.send(this.generateDemoPage());
    });
  }

  private handleSSEConnection(
    req: express.Request, 
    res: express.Response, 
    channelName = 'general'
  ): void {
    const connectionId = uuidv4();
    const lastEventId = req.headers['last-event-id'] as string || req.query.lastEventId as string;

    console.log(`📡 New SSE connection: ${connectionId} to channel: ${channelName}`);

    // 🔧 Setup SSE headers
    res.writeHead(200, {
      'Content-Type': 'text/event-stream',
      'Cache-Control': 'no-cache',
      'Connection': 'keep-alive',
      'Access-Control-Allow-Origin': '*',
      'Access-Control-Allow-Headers': 'Cache-Control, Last-Event-ID',
      'Access-Control-Allow-Credentials': 'true'
    });

    // 📦 Create connection object
    const connection: SSEConnection = {
      id: connectionId,
      response: res,
      userId: req.query.userId as string,
      lastEventId,
      connectedAt: new Date(),
      isAlive: true
    };

    // 🗂️ Store connection
    this.connections.set(connectionId, connection);

    // 📡 Add to channel
    this.addConnectionToChannel(connection, channelName);

    // 👋 Send welcome message
    this.sendToConnection(connection, {
      type: 'connected',
      message: `Connected to SSE channel: ${channelName}`,
      connectionId,
      timestamp: Date.now()
    });

    // 📜 Send missed messages if Last-Event-ID provided
    if (lastEventId) {
      this.sendMissedMessages(connection, channelName, lastEventId);
    }

    // 🎧 Handle connection close
    req.on('close', () => {
      console.log(`🔌 SSE connection closed: ${connectionId}`);
      this.removeConnection(connectionId, channelName);
    });

    req.on('error', (error) => {
      console.error(`❌ SSE connection error: ${connectionId}`, error);
      this.removeConnection(connectionId, channelName);
    });
  }

  private createChannel(name: string, maxHistorySize = 100): void {
    const channel: SSEChannel = {
      name,
      connections: new Map(),
      messageHistory: [],
      maxHistorySize
    };

    this.channels.set(name, channel);
    console.log(`📺 Created SSE channel: ${name}`);
  }

  private addConnectionToChannel(connection: SSEConnection, channelName: string): void {
    const channel = this.channels.get(channelName);
    if (!channel) {
      console.warn(`⚠️ Channel not found: ${channelName}`);
      return;
    }

    channel.connections.set(connection.id, connection);
  }

  private removeConnection(connectionId: string, channelName: string): void {
    // 🗑️ Remove from global connections
    this.connections.delete(connectionId);

    // 🗑️ Remove from channel
    const channel = this.channels.get(channelName);
    if (channel) {
      channel.connections.delete(connectionId);
    }

    console.log(`🗑️ Removed connection: ${connectionId}`);
  }

  // 📤 Send message to specific connection
  private sendToConnection(connection: SSEConnection, data: any, eventType?: string): void {
    if (!connection.isAlive) return;

    try {
      const eventId = uuidv4();
      const formattedData = JSON.stringify(data);

      let message = `id: ${eventId}\n`;
      if (eventType) {
        message += `event: ${eventType}\n`;
      }
      message += `data: ${formattedData}\n\n`;

      connection.response.write(message);
      console.log(`📤 Sent to ${connection.id}: ${eventType || 'message'}`);
    } catch (error) {
      console.error(`❌ Failed to send to ${connection.id}:`, error);
      connection.isAlive = false;
    }
  }

  // 📢 Broadcast to all connections in channel
  private broadcastToChannel(channelName: string, data: any, eventType?: string): void {
    const channel = this.channels.get(channelName);
    if (!channel) return;

    const message = {
      id: uuidv4(),
      data,
      type: eventType,
      timestamp: new Date()
    };

    // 💾 Store in channel history
    channel.messageHistory.push(message);
    if (channel.messageHistory.length > channel.maxHistorySize) {
      channel.messageHistory = channel.messageHistory.slice(-channel.maxHistorySize);
    }

    // 📡 Send to all connections
    let sentCount = 0;
    channel.connections.forEach((connection) => {
      this.sendToConnection(connection, data, eventType);
      sentCount++;
    });

    console.log(`📢 Broadcast to ${channelName}: ${sentCount} connections`);
  }

  // 📜 Send missed messages since Last-Event-ID
  private sendMissedMessages(connection: SSEConnection, channelName: string, lastEventId: string): void {
    const channel = this.channels.get(channelName);
    if (!channel) return;

    // 🔍 Find messages after lastEventId
    const lastIndex = channel.messageHistory.findIndex(msg => msg.id === lastEventId);
    if (lastIndex === -1) {
      // Send all recent messages if lastEventId not found
      channel.messageHistory.slice(-10).forEach(msg => {
        this.sendToConnection(connection, msg.data, msg.type);
      });
      return;
    }

    // 📤 Send messages after the last received one
    const missedMessages = channel.messageHistory.slice(lastIndex + 1);
    missedMessages.forEach(msg => {
      this.sendToConnection(connection, msg.data, msg.type);
    });

    console.log(`📜 Sent ${missedMessages.length} missed messages to ${connection.id}`);
  }

  // 💓 Heartbeat to detect dead connections
  private setupHeartbeat(): void {
    this.heartbeatInterval = setInterval(() => {
      this.performHeartbeat();
    }, 30000); // Every 30 seconds
  }

  private performHeartbeat(): void {
    console.log('💓 Performing SSE heartbeat...');
    
    this.connections.forEach((connection, connectionId) => {
      try {
        // 💓 Send heartbeat ping
        this.sendToConnection(connection, {
          type: 'heartbeat',
          timestamp: Date.now()
        }, 'heartbeat');
      } catch (error) {
        console.log(`💀 Removing dead connection: ${connectionId}`);
        connection.isAlive = false;
        this.connections.delete(connectionId);
      }
    });

    // 🧹 Clean up dead connections from channels
    this.channels.forEach((channel) => {
      const deadConnections: string[] = [];
      channel.connections.forEach((connection, connectionId) => {
        if (!connection.isAlive) {
          deadConnections.push(connectionId);
        }
      });
      
      deadConnections.forEach(connectionId => {
        channel.connections.delete(connectionId);
      });
    });
  }

  // 🔔 Send notification
  sendNotification(notification: NotificationMessage): void {
    console.log(`🔔 Sending notification: ${notification.title}`);
    this.broadcastToChannel('notifications', notification, 'notification');
  }

  // 💹 Send stock update
  sendStockUpdate(stockUpdate: StockUpdateMessage): void {
    console.log(`💹 Sending stock update: ${stockUpdate.symbol}`);
    this.broadcastToChannel('stock-updates', stockUpdate, 'stock_update');
  }

  // 🔧 Send system status
  sendSystemStatus(status: SystemStatusMessage): void {
    console.log(`🔧 Sending system status: ${status.service}`);
    this.broadcastToChannel('system-status', status, 'system_status');
  }

  // 📊 Get server statistics
  private getServerStats(): any {
    const totalConnections = this.connections.size;
    const channelStats = Array.from(this.channels.entries()).map(([name, channel]) => ({
      name,
      connections: channel.connections.size,
      messageHistory: channel.messageHistory.length
    }));

    return {
      totalConnections,
      channels: channelStats,
      uptime: process.uptime(),
      memoryUsage: process.memoryUsage()
    };
  }

  // 🎭 Generate demo page
  private generateDemoPage(): string {
    return `
    <!DOCTYPE html>
    <html lang="en">
    <head>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <title>SSE Demo - Real-Time Notifications</title>
        <style>
            body { font-family: Arial, sans-serif; margin: 20px; background: #f5f5f5; }
            .container { max-width: 1200px; margin: 0 auto; }
            .controls { background: white; padding: 20px; border-radius: 8px; margin-bottom: 20px; }
            .status { padding: 10px; border-radius: 4px; margin-bottom: 10px; }
            .connected { background: #d4edda; color: #155724; }
            .disconnected { background: #f8d7da; color: #721c24; }
            button { padding: 10px 20px; margin: 5px; border: none; border-radius: 4px; cursor: pointer; }
            .btn-primary { background: #007bff; color: white; }
            .btn-success { background: #28a745; color: white; }
            .btn-warning { background: #ffc107; color: black; }
            .btn-danger { background: #dc3545; color: white; }
            #notifications { position: fixed; top: 20px; right: 20px; width: 300px; z-index: 1000; }
        </style>
    </head>
    <body>
        <div class="container">
            <h1>📡 Server-Sent Events Demo</h1>
            
            <div class="controls">
                <h2>Connection Control</h2>
                <div id="status" class="status disconnected">Disconnected</div>
                <button class="btn-primary" onclick="connect()">Connect</button>
                <button class="btn-danger" onclick="disconnect()">Disconnect</button>
            </div>

            <div class="controls">
                <h2>Send Test Messages</h2>
                <button class="btn-success" onclick="sendNotification('success')">Success Notification</button>
                <button class="btn-warning" onclick="sendNotification('warning')">Warning Notification</button>
                <button class="btn-danger" onclick="sendNotification('error')">Error Notification</button>
                <button class="btn-primary" onclick="sendStockUpdate()">Stock Update</button>
                <button class="btn-primary" onclick="sendSystemStatus()">System Status</button>
            </div>

            <div class="controls">
                <h2>Message Log</h2>
                <div id="messageLog" style="height: 300px; overflow-y: auto; background: #f8f9fa; padding: 10px; border-radius: 4px;"></div>
            </div>
        </div>

        <div id="notifications"></div>

        <script>
            let eventSource = null;
            let messageCount = 0;

            function connect() {
                if (eventSource) return;

                eventSource = new EventSource('/api/sse');
                
                eventSource.onopen = () => {
                    updateStatus('Connected', true);
                    logMessage('✅ Connected to SSE stream');
                };

                eventSource.onmessage = (event) => {
                    const data = JSON.parse(event.data);
                    logMessage('📨 Message: ' + JSON.stringify(data, null, 2));
                };

                eventSource.onerror = (error) => {
                    updateStatus('Error/Reconnecting', false);
                    logMessage('❌ Connection error');
                };
            }

            function disconnect() {
                if (eventSource) {
                    eventSource.close();
                    eventSource = null;
                    updateStatus('Disconnected', false);
                    logMessage('🔌 Disconnected from SSE stream');
                }
            }

            function updateStatus(message, connected) {
                const status = document.getElementById('status');
                status.textContent = message;
                status.className = 'status ' + (connected ? 'connected' : 'disconnected');
            }

            function logMessage(message) {
                const log = document.getElementById('messageLog');
                const time = new Date().toLocaleTimeString();
                log.innerHTML += '<div>' + time + ' - ' + message + '</div>';
                log.scrollTop = log.scrollHeight;
            }

            async function sendNotification(severity) {
                await fetch('/api/send-notification', {
                    method: 'POST',
                    headers: { 'Content-Type': 'application/json' },
                    body: JSON.stringify({
                        type: 'notification',
                        title: 'Test Notification',
                        message: 'This is a test ' + severity + ' notification',
                        severity: severity,
                        timestamp: Date.now(),
                        id: 'test-' + Date.now()
                    })
                });
            }

            async function sendStockUpdate() {
                await fetch('/api/send-stock-update', {
                    method: 'POST',
                    headers: { 'Content-Type': 'application/json' },
                    body: JSON.stringify({
                        type: 'stock_update',
                        symbol: 'AAPL',
                        price: 150 + Math.random() * 20,
                        change: (Math.random() - 0.5) * 10,
                        timestamp: Date.now(),
                        id: 'stock-' + Date.now()
                    })
                });
            }

            async function sendSystemStatus() {
                const statuses = ['online', 'offline', 'degraded'];
                const services = ['API', 'Database', 'Cache', 'Queue'];
                
                await fetch('/api/send-system-status', {
                    method: 'POST',
                    headers: { 'Content-Type': 'application/json' },
                    body: JSON.stringify({
                        type: 'system_status',
                        service: services[Math.floor(Math.random() * services.length)],
                        status: statuses[Math.floor(Math.random() * statuses.length)],
                        uptime: Math.random() * 1000000,
                        timestamp: Date.now(),
                        id: 'status-' + Date.now()
                    })
                });
            }

            // Auto-connect on page load
            window.addEventListener('load', () => {
                connect();
            });

            // Handle page unload
            window.addEventListener('beforeunload', () => {
                disconnect();
            });
        </script>
    </body>
    </html>
    `;
  }

  // 🚀 Start the server
  start(): void {
    this.app.listen(this.port, () => {
      console.log(`🚀 SSE Server running on port ${this.port}`);
      console.log(`📡 SSE endpoint: http://localhost:${this.port}/api/sse`);
      console.log(`🎭 Demo page: http://localhost:${this.port}`);
    });

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

  private shutdown(): void {
    console.log('🛑 Shutting down SSE server...');
    
    if (this.heartbeatInterval) {
      clearInterval(this.heartbeatInterval);
    }

    // 👋 Close all SSE connections
    this.connections.forEach((connection) => {
      connection.response.end();
    });

    console.log('✅ SSE server shutdown complete');
    process.exit(0);
  }
}

// 🚀 Start the SSE server
const sseServer = new SSEServer(3000);
sseServer.start();

// 🎯 Demo data generators for testing
setInterval(() => {
  // 📊 Send random stock updates
  const symbols = ['AAPL', 'GOOGL', 'MSFT', 'AMZN', 'TSLA'];
  const symbol = symbols[Math.floor(Math.random() * symbols.length)];
  const price = 100 + Math.random() * 200;
  const change = (Math.random() - 0.5) * 20;

  sseServer.sendStockUpdate({
    type: 'stock_update',
    symbol,
    price: Math.round(price * 100) / 100,
    change: Math.round(change * 100) / 100,
    changePercent: (change / (price - change)) * 100,
    timestamp: Date.now(),
    id: `stock-${Date.now()}`
  });
}, 5000);

setInterval(() => {
  // 🔧 Send random system status updates
  const services = ['API Gateway', 'Database', 'Cache Layer', 'Message Queue'];
  const statuses: SystemStatusMessage['status'][] = ['online', 'degraded'];
  
  sseServer.sendSystemStatus({
    type: 'system_status',
    service: services[Math.floor(Math.random() * services.length)],
    status: statuses[Math.floor(Math.random() * statuses.length)],
    uptime: Math.random() * 1000000,
    timestamp: Date.now(),
    id: `status-${Date.now()}`
  });
}, 15000);

🎨 Advanced SSE Patterns

🔄 SSE with Authentication and Channels

// 🔐 Advanced SSE with authentication and channel management
interface AuthenticatedSSEClient extends TypeSafeSSEClient {
  authenticate(token: string): Promise<void>;
  subscribeToChannel(channel: string): void;
  unsubscribeFromChannel(channel: string): void;
}

class ChannelBasedSSEClient extends TypeSafeSSEClient {
  private authToken: string | null = null;
  private subscribedChannels = new Set<string>();
  private channelEventHandlers = new Map<string, Set<(message: any) => void>>();

  constructor(baseUrl: string, config?: SSEClientConfig) {
    super(baseUrl, config);
  }

  // 🔐 Authenticate with server
  async authenticate(token: string): Promise<void> {
    this.authToken = token;
    
    // 🔄 Reconnect with authentication
    if (this.isConnected()) {
      this.disconnect();
    }
    
    // 🔗 Build authenticated URL
    const authUrl = `${this.url}?token=${encodeURIComponent(token)}`;
    this.url = authUrl;
    this.connect();
  }

  // 📺 Subscribe to specific channel
  subscribeToChannel(channel: string): void {
    if (this.subscribedChannels.has(channel)) {
      console.warn(`⚠️ Already subscribed to channel: ${channel}`);
      return;
    }

    console.log(`📺 Subscribing to channel: ${channel}`);
    this.subscribedChannels.add(channel);

    // 📤 Send subscription request (if connection supports it)
    if (this.isConnected()) {
      this.sendChannelCommand('subscribe', channel);
    }
  }

  // 📺 Unsubscribe from channel
  unsubscribeFromChannel(channel: string): void {
    if (!this.subscribedChannels.has(channel)) {
      console.warn(`⚠️ Not subscribed to channel: ${channel}`);
      return;
    }

    console.log(`📺 Unsubscribing from channel: ${channel}`);
    this.subscribedChannels.delete(channel);
    this.channelEventHandlers.delete(channel);

    // 📤 Send unsubscription request
    if (this.isConnected()) {
      this.sendChannelCommand('unsubscribe', channel);
    }
  }

  // 🎧 Add channel-specific event handler
  onChannelMessage(channel: string, handler: (message: any) => void): void {
    if (!this.channelEventHandlers.has(channel)) {
      this.channelEventHandlers.set(channel, new Set());
    }
    
    this.channelEventHandlers.get(channel)!.add(handler);
  }

  // 🗑️ Remove channel-specific event handler
  offChannelMessage(channel: string, handler: (message: any) => void): void {
    const handlers = this.channelEventHandlers.get(channel);
    if (handlers) {
      handlers.delete(handler);
    }
  }

  private sendChannelCommand(action: 'subscribe' | 'unsubscribe', channel: string): void {
    // Note: This would require a bidirectional connection or separate HTTP endpoint
    // For SSE, you might use a separate HTTP POST to manage subscriptions
    fetch(`${this.url.split('?')[0]}/channels/${action}`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${this.authToken}`
      },
      body: JSON.stringify({ channel })
    }).catch(error => {
      console.error(`❌ Failed to ${action} channel ${channel}:`, error);
    });
  }

  // 🎧 Override message handling to route to channels
  protected handleMessage(message: SSEEventMessage): void {
    // 📡 Handle channel-specific messages
    if ((message as any).channel) {
      const channel = (message as any).channel;
      const handlers = this.channelEventHandlers.get(channel);
      
      if (handlers) {
        handlers.forEach(handler => {
          try {
            handler(message);
          } catch (error) {
            console.error(`❌ Error in channel handler for ${channel}:`, error);
          }
        });
      }
    }

    // 🎯 Call parent handler for general messages
    super.emit('message', message);
  }

  // 📊 Get subscription status
  getSubscriptions(): string[] {
    return Array.from(this.subscribedChannels);
  }

  // 🔌 Override disconnect to cleanup subscriptions
  disconnect(): void {
    this.subscribedChannels.clear();
    this.channelEventHandlers.clear();
    super.disconnect();
  }
}