onSocket

Component-scoped WebSocket hook with auto-cleanup.

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

const Chat = () => {
  const messages = atom([]);

  const sock = ws('wss://example.com/chat', {
    reconnect: true,
    reconnectDelay: 1000,
  });

  onSocket((msg) => {
    messages.update(d => { d.push(msg); });
  }, [sock]);

  return () => html`
    <ul>${messages().map(m => html`<li>${m}</li>`)}</ul>
    <button @click=${() => sock.send({ type: 'ping' })}>Ping</button>
  `;
};

Overview

ws(url, config?) creates a managed WebSocket with optional auto-reconnect. It must be called in a component's outer function so cleanup (socket, timers, handlers) is registered on the host.

onSocket(handler, sockets) subscribes to one or more connections and unsubscribes on unmount. Prefer this over connection.__subscribe inside components.

ws vs onSocket

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

Simulated WebSocket message stream

In a real app, ws() connects to your WebSocket server and onSocket() delivers messages reactively. This demo simulates the same message-stream pattern with onInterval so no server is required.

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

// Real usage: import { ws, onSocket } from 'mates';

// const sock = ws('wss://example.com/chat', { reconnect: true });

// onSocket((data) => { ... }, [sock]);

// This demo simulates WebSocket messages with onInterval

const MOCK_MESSAGES = [

'Server: Connection established',

'Server: Heartbeat OK',

'Server: User #42 joined',

'Server: Data update received',

'Server: Processing complete',

];

const App = () => {

const messages = atom([]);

const connected = atom(true);

let i = 0;

onInterval(() => {

if (!connected()) return;

messages.set(prev => [

...prev.slice(-7),

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

]);

i++;

}, 1500);

return () => html`

${connected() ? '● Connected' : '○ Disconnected'}

</span>

<button class="btn-ghost" @click=${() => connected.set(v => !v)}>

${connected() ? 'Disconnect' : 'Reconnect'}

API — ws & onSocket

import { ws, onSocket } from 'mates'

Prop / Option	Type	Default	Description
`ws(url, config?)`*	`WsConnection`	—	Create a managed WebSocket connection with automatic reconnect. Must be called in the component outer function. Returns a connection handle passed to onSocket.
`onSocket(fn, sockets)`	`void`	—	Subscribe to messages from one or more WebSocket connections. fn receives the parsed message data. The subscription is automatically torn down when the component unmounts.

ws() config

Prop / Option	Type	Default	Description
`reconnect`	`boolean`	`true`	Automatically reconnect after an unexpected close. Set to false to disable auto-reconnect.
`reconnectDelay`	`number`	`1000`	Base milliseconds to wait before the first reconnect attempt.
`reconnectMaxDelay`	`number`	`30000`	Maximum delay cap for exponential backoff.
`reconnectMaxAttempts`	`number`	`Infinity`	Maximum number of reconnect attempts.
`protocols`	`string \| string[]`	—	Optional WebSocket subprotocol(s) to negotiate with the server.
`auth`	`() => Record`	—	Called lazily on each (re)connect to produce extra query-string params (e.g. token).
`autoConnect`	`boolean`	`true`	If false, call connection.connect() manually when ready.

WsConnection handle

Prop / Option	Type	Default	Description
`connection.send(data)`	`void`	—	Send a message. Strings are sent as-is; objects are JSON-serialized automatically.
`connection.connect()`	`void`	—	Open or re-open the connection. Called automatically unless autoConnect is false.
`connection.disconnect()`	`void`	—	Close the connection and stop all reconnect attempts.
`connection.status()`	`'connecting' \| 'connected' \| 'disconnected' \| 'error'`	—	Reactive atom reflecting the current connection status.