Handling Connection Events
1. Setting Event Handlers
| Property | Event | Payload |
|---|
onopen | open | Event |
onmessage | message | MessageEvent (.data) |
onerror | error | Event |
onclose | close | CloseEvent (.code, .reason, .wasClean) |
Example: Assign handlers
ws.onopen = () => console.log("open");
ws.onmessage = (e) => console.log("msg", e.data);
ws.onerror = (e) => console.error("err", e);
ws.onclose = (e) => console.log("close", e.code, e.reason);
2. Using addEventListener
Example: Multiple listeners
ws.addEventListener("message", logger);
ws.addEventListener("message", router);
ws.addEventListener("close", cleanup, { once: true });
| Option | Effect |
|---|
{ once: true } | Auto-remove after first call |
{ signal } | Remove via AbortController |
{ capture } | N/A for WebSocket (no bubbling) |
3. Handling Connection Open
Example: Initial sync on open
ws.addEventListener("open", () => {
ws.send(JSON.stringify({ type: "auth", token }));
ws.send(JSON.stringify({ type: "subscribe", channels: ["prices"] }));
});
| Action | Recommendation |
|---|
| Auth | Send first as message (if not via URL/cookie) |
| Resubscribe | Replay subscriptions after reconnect |
| Flush queue | Drain pending outbound messages |
4. Handling Message Events
| Property | Description |
|---|
data | String, Blob, or ArrayBuffer |
origin | Server origin |
lastEventId | Empty for WS |
5. Handling Connection Close
| Property | Description |
|---|
code | Numeric close code (1000-4999) |
reason | UTF-8 string (≤123 bytes) |
wasClean | true if proper close handshake |
6. Handling Connection Errors
Warning: The browser error event is intentionally information-poor (security). Use close.code/reason for diagnostics.
| Symptom | Likely Cause |
|---|
| Immediate error + close 1006 | DNS/TLS/handshake fail |
| Error after open | Network drop / proxy timeout |
| Error on send | Socket already closing |
7. Handling Page Unload
Example: Clean shutdown
window.addEventListener("beforeunload", () => {
if (ws.readyState === WebSocket.OPEN) ws.close(1000, "page-unload");
});
| Event | Use |
|---|
beforeunload | Close socket |
pagehide | BFCache-safe alternative |
visibilitychange | Pause heartbeat / reconnect |
8. Understanding Event Order
new WebSocket() → CONNECTING
↓
[handshake]
↓ success ↓ failure
open error → close (1006)
↓
message* (zero or more)
↓
close(code, reason, wasClean)
| Rule | Detail |
|---|
| close always last | Always fires exactly once |
| error before close | Error implies close will follow |
| no message after close | Late frames discarded |
9. Removing Event Listeners
Example: AbortController
const ctrl = new AbortController();
ws.addEventListener("message", onMsg, { signal: ctrl.signal });
// later
ctrl.abort();
| Method | Use |
|---|
removeEventListener | Named function reference required |
AbortController.signal | Batch-remove multiple listeners |
| Tool | Where |
|---|
| Network → WS tab | Inspect frames in/out |
| Messages filter | Filter by content |
| Console | ws.readyState, ws.bufferedAmount |
chrome://net-export | Full network log |