WebSocket

Reactive WebSocket client with auto-reconnect, typed messages, and component-scoped handlers.

import { html, atom, ws, onSocket } from 'mates';

const ChatWindow = () => {
  // ws() MUST be created in a component outer function (not module level)
  const chat = ws<{ author: string; text: string }>('wss://api.example.com/chat', {
    reconnect: true,
    reconnectDelay: 2000,
    protocols: ['json'],
  });

  const messages = atom<{ author: string; text: string }[]>([]);
  const input = atom('');

  // Component-scoped handler — auto-removed on unmount
  onSocket((msg) => {
    messages.update((list) => { list.push(msg); });
  }, [chat]);

  const send = () => {
    if (!input().trim()) return;
    chat.send({ author: 'me', text: input() });
    input.set('');
  };

  return () => html`
    <div>
      <p>Status: ${chat.status()}</p>
      <!-- "connecting" | "connected" | "disconnected" | "error" -->
      <ul>
        ${messages().map(m => html`<li>${m.author}: ${m.text}</li>`)}
      </ul>
      <input .value=${input()} @input=${(e) => input.set(e.target.value)} />
      <button @click=${send}>Send</button>
    </div>
  `;
};

Overview

ws(url, config?) creates a typed WebSocket connection with a reactive status atom, send, connect, and disconnect.

Subscribe to messages with onSocket(handler, [socket]) inside a component — handlers are removed automatically on unmount. Prefer the dedicated onSocket hook page for the subscribe-only API.

ws vs onSocket

API	Role	Notes
`ws(url, config?)`	Connection	Returns WsConnection — send, status, connect/disconnect.
`onSocket(fn, sockets)`	Subscribe	Component-scoped message handler; auto-cleanup.

WsConfig quick reference

import { ws } from 'mates';
import type { WsConfig } from 'mates';

const config: WsConfig = {
  reconnect: true,           // default true
  reconnectDelay: 1000,      // ms before first retry
  reconnectMaxDelay: 30_000, // backoff cap
  reconnectMaxAttempts: Infinity,
  protocols: ['json'],
  auth: () => ({ token: '…' }), // lazy query params each connect
  autoConnect: true,         // false → call connect() yourself
};

// Inside a component outer function only:
const socket = ws('wss://api.example.com/ws', config);
socket.send({ type: 'ping' });
socket.status(); // reactive atom
socket.disconnect();

Simulated message stream (offline)

Docs sandbox has no WebSocket server. This mirrors onSocket + status with onInterval.

import { html, atom, onInterval, renderApp } from 'mates';

// Offline demo — no WebSocket server in the docs sandbox.

// Real app: ws(url, config) + onSocket(handler, [sock]) in the outer function.

const LINES = [

'Server: connected',

'Server: heartbeat',

'Server: user joined',

'Server: payload ok',

];

const App = () => {

const messages = atom([]);

const status = atom('connected');

let i = 0;

onInterval(() => {

if (status() !== 'connected') return;

messages.set((prev) => [

...prev.slice(-5),

{ text: LINES[i % LINES.length], t: new Date().toLocaleTimeString() },

]);

i++;

}, 1200);

return () => html`

${status()}

</span>

status.set(status() === 'connected' ? 'disconnected' : 'connected')}>

Toggle

</button>

</div>

Status atom pattern

chat.status() cycles connecting → connected → disconnected → error in a real connection.

import { html, atom, renderApp } from 'mates';

// Mirrors chat.status() — the only built-in reactive field on WsConnection.

// Accumulate messages yourself with onSocket + an atom.

const App = () => {

const status = atom('connecting');

const cycle = () => {

const order = ['connecting', 'connected', 'disconnected', 'error'];

const i = order.indexOf(status());

status.set(order[(i + 1) % order.length]);

};

return () => html`

<p class="muted m-t-5">status=${status()}</p>

<button class="btn-primary" @click=${cycle}>Next status</button>

<p class="hint">Real: chat.status() is an atom updated by ws().</p>

</div>

};

renderApp(App, document.getElementById('app'));

API — ws & onSocket

import { ws, onSocket } from 'mates'

Prop / Option	Type	Default	Description
`ws(url, config?)`	`WsConnection`	—	Create a WebSocket connection. Must be called from a component outer function so cleanup is registered.
`onSocket(handler, sockets)`	`void`	—	Subscribe handler to one or more connections; auto-unsubscribes on unmount.

WsConfig

Prop / Option	Type	Default	Description
`reconnect`	`boolean`	`true`	Auto-reconnect on close/error.
`reconnectDelay`	`number`	`1000`	Base delay (ms) before first retry.
`reconnectMaxDelay`	`number`	`30000`	Exponential backoff cap (ms).
`reconnectMaxAttempts`	`number`	`Infinity`	Stop reconnecting after this many attempts.
`protocols`	`string \| string[]`	—	WebSocket sub-protocols.
`auth`	`() => Record`	—	Lazy query params on each (re)connect — e.g. token refresh.
`autoConnect`	`boolean`	`true`	If false, call connection.connect() yourself.

WsConnection<T>

Prop / Option	Type	Default	Description
`.status()`	`Atom<"connecting"\|"connected"\|"disconnected"\|"error">`	—	Reactive connection status — only built-in reactive field.
`.send(data)`	`void`	—	Send a value; objects are JSON-serialised.
`.connect() / .disconnect()`	`void`	—	Open or close. connect() is automatic unless autoConnect: false.
`.__subscribe(fn)`	`() => void`	—	Low-level subscribe; prefer onSocket inside components for auto-cleanup.