Docs/Core concepts/Channels

Channels

Channels are named streams you subscribe to. Their prefix determines the authorization and delivery behavior.

Concept· 6 min read

The channel model

A channel is a named stream. Clients subscribe to channels; servers publish events to them. The channel's prefix decides how it is authorized and delivered. Channel names are automatically scoped to your application after the connection token returns the application ID, so tenants never share a channel.

Channel types

Example	Type	Channel auth	Behavior
news	Public	No	Visible to any authenticated connection for the app
private-account.42	Private	Yes	Callback must return a truthy value
presence-room.lobby	Presence	Yes	Callback returns `{ id, info }`; member set + join/leave
cache-prices	Public cache	No	Public plus the latest retained event on subscribe
private-cache-account.42	Private cache	Yes	Private plus the latest retained event
presence-cache-room.lobby	Presence cache	Yes	Presence plus the latest retained event
private-encrypted-account.42	Private encrypted	Yes	Authorized subscriber receives a per-channel decryption key

"Public" means no per-channel authorization request. It does not mean the SDK can connect without an end-user Bearer token — every connection needs a connection token first.

Call subscribe() with the external channel name. Public and public-cache channels subscribe immediately; authenticated channels first call /channel-auth (see Authentication).

subscribe.ts

const channel = await emitwave.subscribe('news')
channel.bind('article.created', (article) => {
  console.log(article)
})

// Catch every event on the channel
channel.bindAll((event, data) => console.log(event, data))

Binding to events

Use bind(event, handler) for a single event name or bindAll(handler) to receive every event published on the channel. Reserved SDK events such as cache_miss and decryption_error are not passed to bindAll().

Cache channels

A cache channel delivers the latest retained event to a new subscriber on its first subscription — useful for rehydrating state. If nothing is retained yet, the SDK emits cache_miss so you can fetch initial state yourself.

cache.ts

const prices = await emitwave.subscribe('cache-prices')

prices.bind('price.updated', render)

prices.bind('cache_miss', () => {
  // No retained event yet — fetch initial state from your HTTP API
})

Cleanup

cleanup.ts

channel.unbind('article.created', handler)
emitwave.unsubscribe('news')
emitwave.disconnect()

← Previous

Authentication

Events