EventSource.readyState — Eigenschaft · JavaScript-Referenz

Signatur

EventSource.readyState

Beschreibung

Die Eigenschaft readyState einer EventSource-Instanz verrät, in welchem Zustand sich die Server-Sent-Events-Verbindung gerade befindet. Sie ist schreibgeschützt: Der Browser setzt sie selbst, sobald eine Verbindung aufgebaut, geöffnet, unterbrochen oder endgültig geschlossen wird.

Es gibt drei mögliche Werte, die auch als statische Konstanten am Konstruktor (und an jeder Instanz) verfügbar sind:

EventSource.CONNECTING (0): Die Verbindung wird aufgebaut oder nach einem Abbruch automatisch erneut versucht.
EventSource.OPEN (1): Die Verbindung steht, und Ereignisse werden empfangen.
EventSource.CLOSED (2): Die Verbindung ist geschlossen und wird nicht erneut aufgebaut – entweder durch close() oder durch einen schweren Fehler (z. B. falscher MIME-Typ, HTTP-Status außer 200).

Praktisch nützlich ist readyState vor allem im error-Handler: Dort lässt sich unterscheiden, ob der Browser selbst neu verbindet (CONNECTING) oder ob die Verbindung endgültig verloren ist (CLOSED) und die Anwendung selbst reagieren muss – etwa mit einer neuen Instanz oder einer Fehlermeldung für die Nutzer.

Rückgabewert

Typ

number

Beschreibung

0 (CONNECTING), 1 (OPEN) oder 2 (CLOSED).

Beispiele

Zustand direkt nach dem Erzeugen und nach dem Öffnen

const source = new EventSource('/api/stream');

// Direkt nach dem Erzeugen läuft der Verbindungsaufbau
console.log(source.readyState); // 0

source.addEventListener('open', () => {
  console.log(source.readyState === EventSource.OPEN); // true
});

source.addEventListener('message', (event) => {
  console.log('Daten:', event.data);
});

0 true

Im error-Handler zwischen Neuverbindung und endgültigem Abbruch unterscheiden

const statusEl = document.querySelector('#status');
const source = new EventSource('/api/notifications');

source.addEventListener('error', () => {
  switch (source.readyState) {
    case EventSource.CONNECTING:
      // Browser versucht automatisch, neu zu verbinden
      statusEl.textContent = 'Verbindung unterbrochen – verbinde neu …';
      break;
    case EventSource.CLOSED:
      // Keine automatische Neuverbindung mehr
      statusEl.textContent = 'Verbindung endgültig geschlossen.';
      break;
  }
});

Eigene Neuverbindung mit Backoff, wenn der Status CLOSED ist

const connect = (url, delay = 1000) => {
  const source = new EventSource(url);

  source.onopen = () => {
    delay = 1000; // Backoff zurücksetzen
    console.log('Verbunden, readyState =', source.readyState);
  };

  source.onerror = () => {
    if (source.readyState === EventSource.CLOSED) {
      const next = Math.min(delay * 2, 30000);
      console.warn(`Neuer Versuch in ${next} ms`);
      setTimeout(() => connect(url, next), next);
    }
  };

  return source;
};

connect('/api/live-feed');

Verbunden, readyState = 1

Nach close() ist der Zustand CLOSED

const source = new EventSource('/api/ticker');

setTimeout(() => {
  source.close();
  console.log(source.readyState);                        // 2
  console.log(source.readyState === EventSource.CLOSED); // true
}, 5000);

2 true

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung wie source.readyState = 2 wird still ignoriert (im Strict Mode wirft sie einen TypeError). Zum Beenden immer close() verwenden.
Konstanten statt Zahlen: EventSource.OPEN usw. machen den Code lesbarer als die Zahlen 0/1/2.
Fehler ≠ Abbruch: Ein error-Event bedeutet nicht automatisch das Ende der Verbindung. Ist readyState dabei CONNECTING, verbindet der Browser selbst neu (Intervall über das retry:-Feld des Servers steuerbar). Erst bei CLOSED muss die Anwendung eingreifen.
Endgültiges Schließen: Antwortet der Server mit einem anderen HTTP-Status als 200, einem falschen Content-Type (erwartet: text/event-stream) oder scheitert CORS, springt der Zustand auf CLOSED. Mit HTTP 204 kann der Server die Neuverbindung gezielt unterbinden.
Kein Polling: Statt readyState regelmäßig abzufragen, lieber auf die Events open und error reagieren.
Kompatibilität: In allen modernen Browsern verfügbar, nicht im Internet Explorer. In Node.js gibt es EventSource erst seit neueren Versionen (anfangs hinter --experimental-eventsource), sonst über Pakete wie eventsource.

Siehe auch

EventSource EventSource.prototype.close() EventSource.url WebSocket.readyState EventSource.withCredentials