The EventSource API

Technical Deep Dive & Specifications

The EventSource Interface & IDL Specification

According to the WHATWG HTML Living Standard, the EventSource interface inherits from EventTarget:

[Exposed=(Window,Worker)]
interface EventSource : EventTarget {
  constructor(USVString url, optional EventSourceInit eventSourceInitDict = {});

  readonly attribute USVString url;
  readonly attribute boolean withCredentials;

  // Ready-state codes
  const unsigned short CONNECTING = 0;
  const unsigned short OPEN = 1;
  const unsigned short CLOSED = 2;
  readonly attribute unsigned short readyState;

  // Lifecycle Event Handlers
  attribute EventHandler onopen;
  attribute EventHandler onmessage;
  attribute EventHandler onerror;

  undefined close();
};

dictionary EventSourceInit {
  boolean withCredentials = false;
};

Connection State Machine (readyState)

The readyState attribute indicates the exact state of the HTTP streaming connection:

                  +--------------------------+
                  |  new EventSource(url)    |
                  +--------------------------+
                               |
                               v
               +-------------------------------+
               |    0: EventSource.CONNECTING   |<---------------+
               +-------------------------------+                 |
                               |                                 |
              HTTP 200 OK &    |                Network Error /  |
        Content-Type: text/... |                Transient Drop   |
                               v                                 |
               +-------------------------------+                 |
               |       1: EventSource.OPEN     |-----------------+
               +-------------------------------+
                               |
                     Call .close() or
                     HTTP 204 No Content
                               |
                               v
               +-------------------------------+
               |      2: EventSource.CLOSED    |
               +-------------------------------+

Inspecting Incoming MessageEvent

When the server pushes an un-named or standard data: chunk, the onmessage callback receives a standard DOM MessageEvent:

eventSource.onmessage = function(event) {
  console.log('Payload data string:', event.data);
  console.log('Last Event ID:', event.lastEventId);
  console.log('Server Origin:', event.origin);
  
  // Parse JSON if server emits structured payloads
  try {
    const data = JSON.parse(event.data);
    console.log('Parsed Object:', data);
  } catch (e) {
    console.warn('Payload was raw text, not JSON');
  }
};

Key Differences: EventSource vs. fetch() Streaming

💻 Interactive Code Playground

Below is a complete, interactive EventSource dashboard simulator. It allows you to create, observe, disconnect, and simulate server-side events and error drops while inspecting readyState transitions in real time.

Starter Code

Line-by-Line Code Breakdown

• Lines 105–144: Implements a standard WHATWG compliant emulator tracking the 3 exact integer states: 0 (CONNECTING), 1 (OPEN), and 2 (CLOSED).
• Lines 149–153: new MockEventSource('/api/live-feed') initializes the connection in state 0 (CONNECTING).
• Lines 159–162 (onopen): Triggered as soon as the HTTP 200 OK header with text/event-stream arrives. State transitions to 1 (OPEN).
• Lines 165–167 (onmessage): Fires every time a data packet arrives from the server. Extracts event.data and event.lastEventId.
• Lines 170–173 (onerror): Fires when the socket drops. Unlike traditional fetch calls that fail permanently, EventSource transitions back to 0 (CONNECTING) and automatically attempts to reconnect.
• Lines 191–197 (close()): Permanently terminates the connection, setting readyState = 2 (CLOSED) and preventing any further reconnection attempts.

Expected Browser Render Output

⚡ Native EventSource API Lifecycle
Connection State: [ 1: OPEN (Green Pill) ]

[ 1. Initialize (Disabled) ] [ 2. Simulate Server Push ] [ 3. Simulate Drop ] [ 4. close() Stream ]

Terminal Output:
[10:14:02 PM] Creating new EventSource("/api/live-feed")...
[10:14:02 PM] ✓ onopen fired! readyState is now OPEN (1)
[10:14:05 PM] 📥 onmessage received [ID: 1]: {"metric":"CPU_LOAD","value":"42.8%"}
[10:14:08 PM] ⚠️ onerror fired! Connection lost. readyState is now CONNECTING (0). Auto-reconnecting...
[10:14:10 PM] ✓ onopen fired! readyState is now OPEN (1)
[10:14:15 PM] 🛑 eventSource.close() executed! Connection permanently terminated.