Events & Channels

Use event primitives for decoupled communication inside a tab and across browser tabs.

import { event, on } from 'mates';

const userLoggedIn = event<{ userId: string }>('user:login');

// Prefer on() inside a component — auto-cleanup on unmount
on((data) => {
  console.log('logged in:', data.userId);
}, [userLoggedIn]);

// Or __subscribe — keep the unsubscribe yourself
const unsub = userLoggedIn.__subscribe((data) => {
  console.log('logged in:', data.userId);
});

userLoggedIn.trigger({ userId: 'abc123' });
unsub();

Overview

event<T>(name?) creates a typed in-process pub/sub channel. Call it at module level so senders and receivers share one instance. Fire with .trigger(data?); listen with on(fn, [myEvent]) (preferred in components) or .__subscribe(fn).

on(..., [event]) registers cleanup on the host so the handler is removed on unmount. Plain event().__subscribe does not auto-clean — keep the returned unsubscribe (or use onCleanup).

Optional name shows up in devtools traces. The generic T is TypeScript-only.

Not exported from mates: channel and cleanupEvent live under lib/Mutables/events/ but are not re-exported from lib/index.ts. Treat them as internal — use public event / xTabEvent instead.

event vs other communication

API	Scope	Notes
`event()`	In-process	Same JS context only — no browser API overhead. Public export.
`xTabEvent`	Cross-tab	Singleton bus — `trigger(type, data)` over one shared BroadcastChannel.
`atom`	Shared state	Prefer atoms when you need a current value, not a fire-and-forget signal.
`channel` / `cleanupEvent`	Internal	Exist in source but not exported from `mates`.

event — decoupled communication

Module-level channels, senders trigger, receivers __subscribe. Keep unsubs for long-lived mounts (or prefer on()).

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

const messageEvent = event('demo:message');

const counterEvent = event('demo:counter');

const Sender = () => {

const text = atom('');

const send = () => {

if (!text().trim()) return;

messageEvent.trigger(text());

counterEvent.trigger(1);

text.set('');

};

return () => html`

<h3 class="muted">Sender</h3>

<input

.value=${text()}

@input=${e => text.set(e.target.value)}

@keydown=${e => e.key === 'Enter' && send()}

placeholder="Type a message..."

class="m-flex-1"

</div>

};

const Receiver = () => {

const messages = atom([]);

const total = atom(0);

on() with an event dependency

Pass the event in the deps array. on() auto-unsubscribes when the component unmounts.

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

const ping = event('demo:ping');

const App = () => {

const log = atom([]);

// on() + event dep — auto-unsub on unmount via registerCleanup

on((msg) => {

log.set(prev => [`ping: ${msg}`, ...prev].slice(0, 5));

}, [ping]);

return () => html`

<button class="btn-primary" @click=${() => ping.trigger(Date.now())}>

Fire ping

</button>

${log().length === 0

? html`<div class="mono subtle">No pings yet…</div>`

: log().map(e => html`<div class="mono">${e}</div>`)

}

</div>

};

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

API — event

import { event, on } from 'mates'

Prop / Option	Type	Default	Description
`event<T>(name?)`	`EventType`	—	Creates a typed event channel. Optional name appears in devtools. Call at module level so it is shared across components.
`.trigger(data?)`	`void`	—	Fires all active subscribers synchronously. Can be called from handlers, effects, or async callbacks.
`.__subscribe(fn)`	`() => void`	—	Registers fn(data). Returns unsubscribe. Does not auto-clean on unmount — prefer on(fn, [event]) in components.
`.name`	`string`	—	Human-readable name (provided or generated) used in traces.
`on(fn, [event])`	`() => void`	—	Preferred component listener. Passes trigger args to fn; auto-unsubscribes on unmount.

Where to subscribe

Prop / Option	Type	Default	Description
`Outer (setup) function`	`required`	—	Subscribe once per mount so on() can auto-cleanup.
`Inner (template) function`	`forbidden`	—	Would register a new listener on every render (restricted-context guard).

Internal (not exported from mates)

Prop / Option	Type	Default	Description
`channel()`	`ChannelType — internal`	—	Many-to-many join/send/leave bus (sender excluded). Present in lib/Mutables/events/ but not re-exported from lib/index.ts.
`cleanupEvent()`	`CleanupEventType — internal`	—	Like event, but handlers may return a cleanup run before the next trigger. Not exported from mates.