WebSocket.readyState — Eigenschaft · JavaScript-Referenz

Signatur

WebSocket.readyState

Beschreibung

Die Eigenschaft readyState einer WebSocket-Instanz zeigt, in welchem Abschnitt ihres Lebenszyklus die Verbindung gerade ist. Der Wert ist eine Ganzzahl. Zu jedem Wert gibt es eine statische Konstante, die sowohl am Konstruktor (WebSocket.OPEN) als auch an jeder Instanz (socket.OPEN) verfügbar ist:

0 – CONNECTING: Das Objekt wurde erzeugt, aber die Verbindung ist noch nicht aufgebaut.
1 – OPEN: Die Verbindung steht, Daten können mit send() gesendet werden.
2 – CLOSING: Die Verbindung wird gerade geschlossen, etwa nach einem Aufruf von close().
3 – CLOSED: Die Verbindung ist geschlossen oder ließ sich gar nicht erst öffnen.

In der Praxis prüft man readyState vor allem, bevor man mit send() Daten sendet. Ein Aufruf im Zustand CONNECTING wirft eine InvalidStateError-DOMException. In den Zuständen CLOSING und CLOSED werden die Daten dagegen stillschweigend verworfen. Die Eigenschaft hilft außerdem bei Verbindungsanzeigen in der Oberfläche und bei Logik zum automatischen Neuverbinden.

Der Zustand ändert sich immer nur in eine Richtung (0 → 1 → 2 → 3). Ein geschlossener Socket lässt sich nicht wieder öffnen: Für eine neue Verbindung braucht man eine neue WebSocket-Instanz. Die Eigenschaft ist schreibgeschützt. Eine Zuweisung wird im nicht-strikten Modus ignoriert und löst im Strict Mode einen TypeError aus.

Rückgabewert

Typ

number

Beschreibung

Eine der Zahlen 0 (CONNECTING), 1 (OPEN), 2 (CLOSING) oder 3 (CLOSED).

Beispiele

Zustand im Lebenszyklus beobachten

const socket = new WebSocket('wss://echo.websocket.org');
console.log('Direkt nach Erzeugung:', socket.readyState);

socket.addEventListener('open', () => {
  console.log('Nach open:', socket.readyState);
  socket.close();
  console.log('Nach close():', socket.readyState);
});

socket.addEventListener('close', () => {
  console.log('Nach close-Event:', socket.readyState);
});

Direkt nach Erzeugung: 0 Nach open: 1 Nach close(): 2 Nach close-Event: 3

Sicheres Senden mit Warteschlange

const socket = new WebSocket('wss://example.com/chat');
const queue = [];

const safeSend = (data) => {
  if (socket.readyState === WebSocket.OPEN) {
    socket.send(data);
  } else if (socket.readyState === WebSocket.CONNECTING) {
    queue.push(data); // später senden
  } else {
    console.warn('Verbindung geschlossen – Nachricht verworfen:', data);
  }
};

socket.addEventListener('open', () => {
  while (queue.length) socket.send(queue.shift());
});

safeSend(JSON.stringify({ type: 'hello', user: 'anna' }));

Zustand lesbar anzeigen und automatisch neu verbinden

const STATE_NAMES = ['CONNECTING', 'OPEN', 'CLOSING', 'CLOSED'];
let socket;

const connect = () => {
  socket = new WebSocket('wss://example.com/live');
  socket.addEventListener('close', () => {
    console.log('Status:', STATE_NAMES[socket.readyState]);
    setTimeout(connect, 2000); // neue Instanz nötig
  });
};

connect();

setInterval(() => {
  console.log('Aktueller Status:', STATE_NAMES[socket.readyState]);
}, 5000);

Aktueller Status: OPEN

// Wichtig · Fallstricke

Vergleiche mit Konstanten statt mit Zahlen: socket.readyState === WebSocket.OPEN liest sich besser als === 1. Achtung: In Node.js mit der Bibliothek ws sind die Konstanten ebenfalls vorhanden, bei eigenen Mock-Objekten in Tests aber nicht immer.
Senden im Zustand CONNECTING wirft einen InvalidStateError. Warte daher auf das open-Event oder puffere die Nachrichten.
Senden im Zustand CLOSING oder CLOSED wirft keinen Fehler, die Daten gehen aber verloren. bufferedAmount wächst dabei weiter.
Der Wert OPEN garantiert nicht, dass die Gegenstelle noch erreichbar ist. Ein Netzabbruch fällt oft erst verzögert auf. Für belastbare Verbindungen braucht man Heartbeats (Ping/Pong auf Anwendungsebene).
Nach CLOSED gibt es keinen Weg zurück, fürs Neuverbinden ist immer new WebSocket() nötig.
Die Eigenschaft wird in allen modernen Browsern unterstützt, ebenso nativ in Node.js ab Version 22 (globales WebSocket).

Siehe auch

WebSocket WebSocket.prototype.send() WebSocket.prototype.close() WebSocket.bufferedAmount HTMLTrackElement.readyState