Edit

Channel

Environment: server.

Beta — Telefunc Stream is in beta: breaking changes may occur in any version update.

The following low-level primitives enable all kinds of stream use case.

You can use them for one-way streams (aka streaming) as well as two-way streams (aka real-time):

  • Chat rooms
  • Live feeds (sports scores, stock tickers)
  • Collaborative editing
  • Multiplayer games
  • Live dashboards & metrics
  • Notifications & activity feeds

For short-lived callbacks (e.g. progress updates), function passing is usually simpler.

By default, channels and broadcasts use SSE and work without extra server setup. When WebSocket is enabled, the client starts on SSE and seamlessly upgrades to WebSocket in the background.

Needs a long-running server. A channel holds a connection open for its entire lifetime, so channels and broadcasts don't work on serverless platforms that enforce a short time limit on connections (e.g. Vercel, AWS Lambda). See Stream on Cloudflare for using channels on Cloudflare Workers, and Stream at Scale for running multiple server instances.

For channel configurations, see:

new Channel()

It creates a two-way message pipe between the server and the one client that called the telefunction.

Simple example:

// Clock.telefunc.js
// Environment: server
 
import { Channel } from 'telefunc'
 
export async function onClock() {
  const channel = new Channel()
  channel.onOpen(async () => {
    while (!channel.isClosed) {
      await channel.send(Date.now())
      await new Promise((resolve) => setTimeout(resolve, 1000))
    }
  })
  return { channel: channel.client }
}

The server returns channel.client: the client gets the same API but with message directions flipped.

// Clock.jsx
// Environment: client
 
import { onClock } from './Clock.telefunc'
 
const { channel } = await onClock()
channel.listen((time) => console.log(time)) // 1700000000000, 1700000001000, ...
// Clock.tsx
// Environment: client
 
import { onClock } from './Clock.telefunc'
 
const { channel } = await onClock()
channel.listen((time) => console.log(time)) // 1700000000000, 1700000001000, ...

The channel outlives the telefunction call: both ends can send() and listen() until either side closes it.

Two-way example:

// Echo.telefunc.js
// Environment: server
 
import { Channel } from 'telefunc'
 
export async function onEcho() {
  const channel = new Channel()
  channel.listen((text) => channel.send(`echo: ${text}`))
  return { channel: channel.client }
}
// Echo.jsx
// Environment: client
 
import { onEcho } from './Echo.telefunc'
 
const { channel } = await onEcho()
channel.listen((text) => console.log(text)) // 'echo: Hello!'
channel.send('Hello!')
// Echo.tsx
// Environment: client
 
import { onEcho } from './Echo.telefunc'
 
const { channel } = await onEcho()
channel.listen((text) => console.log(text)) // 'echo: Hello!'
channel.send('Hello!')

Channel methods

MethodDescription
send(data)Send a message. Await to apply backpressure.
send(data, { ack: true })Send and await acknowledgement.
sendBinary(data)Send binary data. Await to apply backpressure.
sendBinary(data, { ack: true })Send binary and await acknowledgement.
listen(cb)Receive messages. Return a value to ack. Returns an unlisten function.
listenBinary(cb)Receive binary. Return a value to ack. Returns an unlisten function.
openedPromise that resolves on open; rejects if the channel ends before opening.
closedPromise that resolves on clean close; rejects on failure.
messages({ signal })Iterate { type: 'text' | 'binary', data } messages; abort to stop.
onOpen(cb)Called when the channel opens.
onClose(cb)Called when the channel closes.
close()Close gracefully.
abort(value?)Terminate immediately.

listen(), listenBinary(), onOpen() and onClose() accept { signal } as their second argument. Aborting the signal removes that registration.

Message listeners are called in registration order. A listener aborted by an earlier listener still gets that message.

Receive messages in a loop

You can receive text and binary messages with an async loop:

// Clock.jsx
// Environment: client
 
import { onClock } from './Clock.telefunc'
 
const { channel } = await onClock()
const controller = new AbortController()
const { signal } = controller
 
try {
  for await (const m of channel.messages({ signal })) {
    console.log(m.type, m.data)
  }
} catch (err) {
  if (err !== signal.reason) throw err
}
// Clock.tsx
// Environment: client
 
import { onClock } from './Clock.telefunc'
 
const { channel } = await onClock()
const controller = new AbortController()
const { signal } = controller
 
try {
  for await (const m of channel.messages({ signal })) {
    console.log(m.type, m.data)
  }
} catch (err) {
  if (err !== signal.reason) throw err
}

controller.abort() makes the loop throw signal.reason. Aborting or breaking out of the loop leaves the channel open.

Listeners and active iterators each receive the incoming messages. An iterator starts listening at its first next() call.

Without { ack: true }, listener callbacks are called before the iterator's loop resumes. Their returned promises can still be pending.

With { ack: true }, callbacks and iterators are awaited in registration order. Advance past the message or stop iteration to let later listeners or iterators receive it.

To return an acknowledgement value, use listen() or listenBinary(). An iterator supplies undefined when you advance past the message or stop iteration.

TypeScript

new Channel<ClientToServer, ServerToClient>() takes two generic type parameters. Each is a function signature:

  • The argument is the message type.
  • The return type is the acknowledgement type (void if no ack).
// Room.telefunc.js
// Environment: server
 
import { Channel } from 'telefunc'
 
export async function onJoinRoom() {
  const channel = new Channel({ ack: true })
 
  channel.listen((message) => {
    if (message.type === 'join') {
      channel.send({ type: 'system', text: `Joined ${message.roomId}` })
      return { accepted: true }
    }
    channel.send({ type: 'chat', text: `echo: ${message.text}` })
    return { accepted: true }
  })
 
  return { channel: channel.client }
}
// Room.telefunc.ts
// Environment: server
 
import { Channel } from 'telefunc'
 
type ServerMessage =
  | { type: 'system'; text: string }
  | { type: 'chat'; text: string }
 
type ClientMessage =
  | { type: 'join'; roomId: string }
  | { type: 'chat'; text: string }
 
type ClientToServer = (message: ClientMessage) => { accepted: true }
type ServerToClient = (message: ServerMessage) => { delivered: true }
 
export async function onJoinRoom() {
  const channel = new Channel<ClientToServer, ServerToClient>({ ack: true })
 
  channel.listen((message) => {
    if (message.type === 'join') {
      channel.send({ type: 'system', text: `Joined ${message.roomId}` })
      return { accepted: true }
    }
    channel.send({ type: 'chat', text: `echo: ${message.text}` })
    return { accepted: true }
  })
 
  return { channel: channel.client }
}
// Room.jsx
// Environment: client
 
import { onJoinRoom } from './Room.telefunc'
 
const { channel } = await onJoinRoom()
 
const unlisten = channel.listen((message) => {
  console.log(message.text)
  return { delivered: true }
})
// unlisten() to stop receiving
 
const ack = await channel.send({ type: 'join', roomId: 'general' })
ack.accepted // true
// Room.tsx
// Environment: client
 
import { onJoinRoom } from './Room.telefunc'
 
const { channel } = await onJoinRoom()
 
const unlisten = channel.listen((message) => {
  console.log(message.text)
  return { delivered: true }
})
// unlisten() to stop receiving
 
const ack = await channel.send({ type: 'join', roomId: 'general' })
ack.accepted // true

On the server, send() sends ServerMessage. On the client, send() sends ClientMessage. The channel.client type flips the message types.

Acknowledgements

Exactly one listener may return an acknowledgement value. Other listeners can observe the message and return undefined; two answers reject the send.

Channel-wide

const channel = new Channel({ ack: true })
 
// Every send() returns a Promise with the listener's return value
const ack = await channel.send({ type: 'status', text: 'OK' })
const channel = new Channel<ClientToServer, ServerToClient>({ ack: true })
 
// Every send() returns a Promise with the listener's return value
const ack = await channel.send({ type: 'status', text: 'OK' })

Per-send

const channel = new Channel()
 
// Opt in for a single send
const ack = await channel.send(data, { ack: true })
 
// Opt out on an ack-default channel
await channel.send(data, { ack: false }) // Promise<void>, no ack value
 
// Binary acks work the same way
const binaryAck = await channel.sendBinary(frame, { ack: true })
const channel = new Channel<ClientToServer, ServerToClient>()
 
// Opt in for a single send
const ack = await channel.send(data, { ack: true })
 
// Opt out on an ack-default channel
await channel.send(data, { ack: false }) // Promise<void>, no ack value
 
// Binary acks work the same way
const binaryAck = await channel.sendBinary(frame, { ack: true })

A channel-wide { ack: true } only applies to send() — sendBinary() always opts in per call, so pass { ack: true } to each sendBinary() that needs an acknowledgement.

Binary data

Send and receive raw binary alongside structured messages:

// Server
await channel.sendBinary(new Uint8Array([1, 2, 3]))
const unlisten = channel.listenBinary((data) => {
  console.log(data.byteLength)
  return { processed: true } // ack value (optional)
})
unlisten() // stop listening
 
// Client — same API
await channel.sendBinary(new Uint8Array(buffer))
channel.listenBinary((data) => {
  console.log(data.byteLength)
})
 
// Binary acks
const ack = await channel.sendBinary(frame, { ack: true })

A message the client sends must be under 64 MiB (32 MiB on Cloudflare with the 'ws' transport). A larger send(), sendBinary(), publish() or publishBinary() throws, and the channel stays open.

Backpressure

Both send() and sendBinary() return a Promise that resolves when the receiver has capacity for more data. Await them in a loop to apply backpressure:

for (const frame of frames) {
  await channel.sendBinary(frame) // blocks until the receiver is ready
}

Fire-and-forget is also fine — a send goes out as soon as the connection has room, whether or not you await it:

channel.send({ type: 'ping' }) // no await needed

What happens to a server channel's sends, awaited or not:

  • While the client is connected, the server delivers sends within maxPendingBytes and maxPendingAcks (see API > channel (config)). Exceeding either budget closes the channel with ChannelOverflowError naming the setting.
  • While the client is offline, the server buffers them, up to bufferLimit/bufferLimitBinary (see API > channel (config)). An awaited send() resolves once the client is back and the message went out. From then on, these sends count toward maxPendingBytes and maxPendingAcks like any other.
  • Past that limit, the server drops the oldest buffered sends, and each dropped send() rejects with ChannelOverflowError. A single message larger than the limit is dropped even if you await it. Earlier buffered sends of the same kind (text or binary) are dropped too.

Telefunc logs a warning once per channel when the sends nobody awaits keep outrunning what the client takes, well before they exceed maxPendingBytes.

To fix it, await each send() before the next, as in the clock example above, or send slower.

Broadcast

Broadcast is a keyed pub/sub bus: a message published to a key reaches every subscriber of that key — server-side subscribers (via Broadcast.subscribe()) and clients bridged into the key (via new BroadcastChannel()). Publishers and subscribers are decoupled; all they share is the key string. It's the fan-out layer that new BroadcastChannel() is built on.

The static methods run purely on the server — no client, no handle, no lifecycle — and take the key as their first argument:

import { Broadcast } from 'telefunc'
 
// Publish to every subscriber of the key
Broadcast.publish('room:lobby', { text: 'Hello!' })
 
// Subscribe on the server
const unsub = Broadcast.subscribe('room:lobby', (msg, info) => {
  console.log(msg, info.seq)
})

publish() returns a receipt and subscribe() receives the same info:

info.key        // 'room:lobby' — the broadcast key
info.seq        // monotonic sequence number for this key
info.timestamp  // server timestamp (Unix epoch ms)

seq is monotonic per key, which is useful for ordering and gap detection. publish() resolves to info once the message is accepted.

publish() can't be awaited per subscriber, so the warning about sends that outrun their client doesn't apply to a BroadcastChannel. Instead, a client that falls far behind a broadcast has its connection cut and reconnects. Other channels on the connection also reconnect. The BroadcastChannel gets what it missed after reconnecting. If it missed more than the server's buffers hold, it closes (see errors).

A listener's async work isn't awaited: the next message arrives whether or not your subscribe() callback is done. So if your callback can fall behind, unfinished calls pile up on the page, and Telefunc doesn't limit them: your code has to. For example, a callback that does an await fetch() for each message should queue them, and drop or merge what it can't keep up with.

By default, broadcast is in-memory — messages only reach subscribers on the same server. This works out-of-the-box for single-server deployments.

For scaling horizontally, you must configure Broadcast to publish across all server instances — see Stream at Scale > Broadcast

new BroadcastChannel()

new BroadcastChannel({ key }) lets you broadcast from and to the client-side (whereas Broadcast is server-side only).

It creates a Channel to the one client that received it, and bridges that client onto a Broadcast key.

Return it from a telefunction and the receiving client can publish() / subscribe() on the key — every message reaches every member of the group (both client-side and server-side).

⚠️

Keys are capabilities — anyone who knows the key joins the group. Secure a broadcast in one of two ways:

  • Guard the key: derive it from authorized server-side context (e.g. the user ID from getContext()), never from client-side input.
  • Guard the payload: whatever you publish() reaches every subscriber, so broadcast only non-sensitive data. That's how @telefunc/tanstack-query stays safe — it broadcasts only a "refetch" signal, and each client loads the actual data through its own authorized telefunction.

See also:

Chat example

// Chat.telefunc.js
// Environment: server
 
import { BroadcastChannel } from 'telefunc'
 
export async function onJoinChat(room, username) {
  const chat = new BroadcastChannel({ key: `chat:${room}` })
 
  chat.onOpen(() => {
    chat.publish({ user: 'system', text: `${username} joined` })
  })
 
  chat.onClose(() => {
    chat.publish({ user: 'system', text: `${username} left` })
  })
 
  return chat
}
// Chat.telefunc.ts
// Environment: server
 
import { BroadcastChannel } from 'telefunc'
 
type ChatMessage = { user: string; text: string }
 
export async function onJoinChat(room: string, username: string) {
  const chat = new BroadcastChannel<ChatMessage>({ key: `chat:${room}` })
 
  chat.onOpen(() => {
    chat.publish({ user: 'system', text: `${username} joined` })
  })
 
  chat.onClose(() => {
    chat.publish({ user: 'system', text: `${username} left` })
  })
 
  return chat
}

Unlike channels (new Channel()), no .client is needed: broadcast is symmetric — the same instance has the same message type on both ends (no directional flip).

// Chat.jsx
// Environment: client
 
import { onJoinChat } from './Chat.telefunc'
 
const chat = await onJoinChat('lobby', 'Alice')
 
// Receive messages published to the key, including this instance's own publishes
chat.subscribe((msg, info) => {
  console.log(`#${info.seq} ${msg.user}: ${msg.text}`)
})
 
// Publish to every subscriber of the key
chat.publish({ user: 'Alice', text: 'Hello!' })
// Chat.tsx
// Environment: client
 
import { onJoinChat } from './Chat.telefunc'
 
const chat = await onJoinChat('lobby', 'Alice')
 
// Receive messages published to the key, including this instance's own publishes
chat.subscribe((msg, info) => {
  console.log(`#${info.seq} ${msg.user}: ${msg.text}`)
})
 
// Publish to every subscriber of the key
chat.publish({ user: 'Alice', text: 'Hello!' })

Receive broadcast messages in a loop

// Chat.jsx
// Environment: client
 
const controller = new AbortController()
for await (const message of chat.messages({ signal: controller.signal })) {
  console.log(message.type, message.data, message.info.seq)
}
// Chat.tsx
// Environment: client
 
const controller = new AbortController()
for await (const message of chat.messages({ signal: controller.signal })) {
  console.log(message.type, message.data, message.info.seq)
}

messages() works on both server and client. Each message includes the same info as a subscription callback. The loop follows the channel loop's cancellation and close behavior.

A publish doesn't wait for a slow loop, so the loop holds what it falls behind by: up to config.channel.bufferLimit of text and bufferLimitBinary of binary on the server, and their defaults (512 KB and 2 MB) on the client. A loop that falls further behind throws ChannelOverflowError and stops receiving.

subscribe(), subscribeBinary(), onOpen() and onClose() accept { signal } after the callback. The static Broadcast.subscribe() and Broadcast.subscribeBinary() accept it too. Aborting removes that registration.

Notifications

A per-user key with a subscribe-only client — the server returns a BroadcastChannel keyed to the user, and the client only listens:

// Notifications.telefunc.js
// Environment: server
 
import { BroadcastChannel, getContext } from 'telefunc'
 
export async function onListenNotifications() {
  const context = getContext()
  const broadcast = new BroadcastChannel({ key: `notifications:${context.userId}` })
  // Send a toast to *all* clients matching the user id, i.e. on all the tabs of
  // all the user's devices.
  setTimeout(() => broadcast.publish('hello'), 1000)
  setTimeout(() => broadcast.publish('world'), 2000)
  return broadcast
}
// Notifications.telefunc.ts
// Environment: server
 
import { BroadcastChannel, getContext } from 'telefunc'
 
export async function onListenNotifications() {
  const context = getContext()
  const broadcast = new BroadcastChannel({ key: `notifications:${context.userId}` })
  // Send a toast to *all* clients matching the user id, i.e. on all the tabs of
  // all the user's devices.
  setTimeout(() => broadcast.publish('hello'), 1000)
  setTimeout(() => broadcast.publish('world'), 2000)
  return broadcast
}
// Notifications.jsx
// Environment: client
 
const broadcast = await onListenNotifications()
broadcast.subscribe((n) => showToast(n))
// Notifications.tsx
// Environment: client
 
const broadcast = await onListenNotifications()
broadcast.subscribe((n) => showToast(n))

BroadcastChannel methods

MethodDescription
openedPromise that resolves on open; rejects if the channel ends before opening.
closedPromise that resolves on clean close; rejects on failure.
messages({ signal }?)Receive text and binary messages with publish info in an async loop.
publish(data)Publish to every subscriber of the key. Returns a receipt.
subscribe(cb, { signal }?)Receive (data, info). Returns an unsubscribe function.
publishBinary(data)Publish raw binary to every subscriber. Returns a receipt.
subscribeBinary(cb, { signal }?)Receive (data, info) for binary messages. Returns an unsubscribe function.
onOpen(cb)Called when the channel opens.
onClose(cb)Called when the channel closes.
close()Close gracefully.
abort(abortValue?)Terminate immediately.

The instance is bound to its key, so publish(data) / subscribe(cb) take no key. The static Broadcast.publish(key, data) / Broadcast.subscribe(key, cb) have no onOpen / onClose / close / abort since there's no instance to manage.

new BroadcastChannel() VS new Channel()

Fundamentally

The difference is what a message is addressed to: a channel message is addressed to someone, a broadcast message is addressed to a topic (the key).

A channel is a conversation, like a phone call: two fixed ends (the server and the one client that received the channel), private to them, ending when either side hangs up.

A broadcast is an announcement, like a radio frequency: whoever tunes in to the key receives everything published to it, members come and go, and the key belongs to no one.

Only the two ends of a channel can use it, while anything that knows a broadcast's key can join it. A channel ends when either side closes it, while a broadcast outlives any single member.

Technically

new BroadcastChannel() is essentially new Channel() combined with the static Broadcast.publish() / Broadcast.subscribe(): the server holds a private channel to the one client that received it, then bridges that client into the keyed broadcast group.

Comparison

new Channel()new BroadcastChannel()
TopologyOne server ↔ one clientAll members sharing a key (server and client)
Methodssend() / listen()publish() / subscribe()
DeliveryThe other endEvery subscriber of the key, including the publisher
Message typeAsymmetric:
  • Two different types: Channel<ClientMessageType, ServerMessageType>
  • The server uses the new Channel() instance, and returns channel.client to the client
Symmetric:
  • Same type for every member: BroadcastChannel<MessageType>
  • The server uses and returns the same BroadcastChannel instance
Message returnThe other end's reply (if { ack: true })A receipt: { key, seq, timestamp }
close()Closes the channel for both endsDetaches this member; the group lives on
Multi-serverSticky sessionsBroadcast transport

Errors

Telefunc silently handles rejected promises from send(), sendBinary(), publish() and publishBinary(). To observe a failure, await the call or use .catch().

Channels and broadcasts signal failure through four errors:

ErrorWhenChannel stateRecovery
AbortEither side called abort(value), or a callback threw AbortClosedInspect err.abortValue
NetworkError (isChannel: true)Offline longer than reconnectTimeout, or missed more messages than the replay buffer holdsClosedAuto-closed — recreate if needed
ChannelClosedErrorsend() on a closed channelClosedRecreate the channel
ChannelOverflowErrorA server channel's sends overfilled bufferLimit/bufferLimitBinary while its client was offline; the dropped ones rejectOpenawait your sends, and raise bufferLimit/bufferLimitBinary above your largest message
ChannelOverflowError (send budget)A connected channel exceeded maxPendingBytes/maxPendingAcksClosedawait the server's sends or raise the named setting, then recreate the channel
ChannelOverflowError (BroadcastChannel)More was published to its key while the client was offline than bufferLimit/bufferLimitBinary holdsClosedCall its telefunction again to rejoin
ChannelOverflowError (publish())With no Redis or other transport installed, a subscribe() callback published more than maxPendingBytes before its first awaitOpenPublish less from the callback, or raise the named setting

A graceful close() isn't an error (onClose(err) receives undefined).

See also:

Reconnection

If the connection drops, Telefunc reconnects automatically and resumes existing channels and broadcasts:

  • Messages sent while offline are buffered and delivered in order on reconnect.
  • Messages lost in the disconnect are resent after reconnect, if the client is back within reconnectTimeout and the replay buffer still holds them.
  • Otherwise, the channel closes with NetworkError. When the replay buffer dropped them, the error message names the setting to raise (see API > channel (config)).
  • onOpen() fires only on initial open, onClose() only on permanent close.

Reconnection is automatic — you don't need to handle it in your application code.

See also