Documentation / @zerotal/broadcasting / TypedBroadcastManager

Class: TypedBroadcastManager<Channels>

Defined in: broadcasting/src/TypedBroadcastManager.ts:127

A BroadcastManager variant that enforces payload types against a channel map.

All BroadcastManager APIs (WebSocket lifecycle, auth, presence) are inherited unchanged. Only to() and toChannel() gain type constraints.

Example

const manager = new TypedBroadcastManager<Channels>();

// Static channel
manager.to('posts', 'PostCreated', { id: 1, title: 'Hello' });

// Parameterised channel
manager.toChannel('private-orders.[orderId]', { orderId: 42 }, 'OrderShipped', {
  orderId: 42, trackingCode: 'UPS-123',
});

Extends

BroadcastManager

Type Parameters

Channels

Channels extends BroadcastChannelMap

Constructors

Constructor

new TypedBroadcastManager<Channels>(): TypedBroadcastManager<Channels>

Returns

TypedBroadcastManager<Channels>

Inherited from

BroadcastManager.constructor

Properties

_conns

protected _conns: Map<string, WS>

Defined in: broadcasting/src/BroadcastManager.ts:32

connectionId → live WebSocket

Inherited from

BroadcastManager._conns

_subs

protected _subs: Map<string, Set<string>>

Defined in: broadcasting/src/BroadcastManager.ts:34

channelName → Set

Inherited from

BroadcastManager._subs

_members

protected _members: Map<string, Map<string, PresenceMember>>

Defined in: broadcasting/src/BroadcastManager.ts:36

presence channelName → Map<connectionId, PresenceMember>

Inherited from

BroadcastManager._members

_authSecret

protected _authSecret: string | undefined = undefined

Defined in: broadcasting/src/BroadcastManager.ts:42

Secret for per-subscription HMAC signatures (the app's APP_KEY).

Inherited from

BroadcastManager._authSecret

Accessors

wsHandlers

Get Signature

get wsHandlers(): object

Defined in: broadcasting/src/BroadcastManager.ts:246

Returns

object

open

open: (ws) => void

Parameters

ws

WS

Returns

void

message

message: (ws, msg) => undefined

Parameters

ws

WS

msg

string | Uint8Array<ArrayBufferLike>

Returns

undefined

close

close: (ws) => void

Parameters

ws

WS

Returns

void

Inherited from

BroadcastManager.wsHandlers

Methods

setAuthSecret()

setAuthSecret(secret): void

Defined in: broadcasting/src/BroadcastManager.ts:51

Set the secret used to sign/verify per-subscription auth tokens. Wired from the app's APP_KEY by BroadcastProvider. Without it the signed-auth path is disabled and the server falls back to the connection-level authorize callbacks.

Parameters

secret

string

Returns

void

Inherited from

BroadcastManager.setAuthSecret

signAuth()

signAuth(socketId, channel, channelData?): string

Defined in: broadcasting/src/BroadcastManager.ts:59

Sign a socket_id / channel pair (and, for presence, its channelData) — the token POST /broadcasting/auth hands back to the client, which echoes it in subscribe.

Parameters

socketId

string

channel

string

channelData?

string

Returns

string

Inherited from

BroadcastManager.signAuth

verifyAuth()

verifyAuth(socketId, channel, auth, channelData?): boolean

Defined in: broadcasting/src/BroadcastManager.ts:74

Constant-time check that auth is a valid signature for this socket/channel(/data).

Parameters

socketId

string

channel

string

auth

string

channelData?

string

Returns

boolean

Inherited from

BroadcastManager.verifyAuth

authorizeWith()

authorizeWith(fn): void

Defined in: broadcasting/src/BroadcastManager.ts:95

Parameters

fn

ChannelAuthFn

Returns

void

Example

broadcast.authorizeWith(async (channel, ws) => {
  if (!ws.data.userId) return false;
  if (channel.startsWith('private-orders.')) {
    const id = channel.split('.')[1];
    return await Order.findOwner(id) === ws.data.userId;
  }
  return true;
});

Inherited from

BroadcastManager.authorizeWith

authorizePresenceWith()

authorizePresenceWith(fn): void

Defined in: broadcasting/src/BroadcastManager.ts:111

Register a presence channel auth callback. Return a PresenceMember object to grant access and track the member, or false to deny.

Parameters

fn

PresenceAuthFn

Returns

void

Example

manager.authorizePresenceWith(async (channel, ws) => {
  const user = await User.find(ws.data.userId);
  if (!user) return false;
  return { id: user.id, info: { name: user.name, avatar: user.avatar } };
});

Inherited from

BroadcastManager.authorizePresenceWith

getMembers()

getMembers(channel): PresenceMember[]

Defined in: broadcasting/src/BroadcastManager.ts:122

Return all members currently subscribed to a presence channel.

Parameters

channel

string

Returns

PresenceMember[]

Example

const members = manager.getMembers('presence-chat.room');
// [{ id: 1, info: { name: 'Alice' } }, ...]

Inherited from

BroadcastManager.getMembers

handleOpen()

handleOpen(ws): void

Defined in: broadcasting/src/BroadcastManager.ts:128

Parameters

ws

WS

Returns

void

Inherited from

BroadcastManager.handleOpen

handleMessage()

handleMessage(ws, raw): Promise<void>

Defined in: broadcasting/src/BroadcastManager.ts:133

Parameters

ws

WS

raw

string | Uint8Array<ArrayBufferLike>

Returns

Promise<void>

Inherited from

BroadcastManager.handleMessage

handleClose()

handleClose(ws): void

Defined in: broadcasting/src/BroadcastManager.ts:166

Parameters

ws

WS

Returns

void

Inherited from

BroadcastManager.handleClose

subscriptionsFor()

subscriptionsFor(connectionId): string[]

Defined in: broadcasting/src/BroadcastManager.ts:226

Returns the list of channels a connection is subscribed to.

Parameters

connectionId

string

Returns

string[]

Inherited from

BroadcastManager.subscriptionsFor

subscriberCount()

subscriberCount(channel): number

Defined in: broadcasting/src/BroadcastManager.ts:235

Returns the number of subscribers on a channel.

Parameters

channel

string

Returns

number

Inherited from

BroadcastManager.subscriberCount

connectionCount()

connectionCount(): number

Defined in: broadcasting/src/BroadcastManager.ts:240

Total open connections.

Returns

number

Inherited from

BroadcastManager.connectionCount

_onHandlerError()

protected _onHandlerError(ws, error): void

Defined in: broadcasting/src/BroadcastManager.ts:267

Last-resort handler for a rejection escaping handleMessage.

Logs and, where possible, tells the offending client. Never rethrows: the whole point is that one client's bad frame must not terminate the process serving everyone else.

Parameters

ws

WS

error

unknown

Returns

void

Inherited from

BroadcastManager._onHandlerError

upgradeData()

upgradeData(req): Record<string, unknown>

Defined in: broadcasting/src/BroadcastManager.ts:278

Factory for upgradeData passed to app.withWebSocket().

Parameters

req

Request

Returns

Record<string, unknown>

Inherited from

BroadcastManager.upgradeData

to()

Call Signature

to<Ch, Ev>(channel, event, data, opts?): void

Defined in: broadcasting/src/TypedBroadcastManager.ts:135

Typed broadcast to a static channel (no [param] placeholders).

TypeScript will enforce that event and data match the channel map entry. Falls back to the untyped base method for any string channel (e.g. if you need to broadcast on a dynamically constructed name).

Type Parameters

Ch

Ch extends string

Ev

Ev extends string

Parameters

channel

Ch

event

Ev

data

PayloadOf<Channels, Ch, Ev>

opts?

exceptSocketId?

string

Returns

void

Overrides

BroadcastManager.to

Call Signature

to(channel, event, data?, opts?): void

Defined in: broadcasting/src/TypedBroadcastManager.ts:142

Untyped fallback — preserves compatibility with the base class signature.

Parameters

channel

string

event

string

data?

unknown

opts?

exceptSocketId?

string

Returns

void

Overrides

BroadcastManager.to

toChannel()

toChannel<Pattern, Ev>(pattern, params, event, data): void

Defined in: broadcasting/src/TypedBroadcastManager.ts:162

Typed broadcast to a parameterised channel pattern.

The pattern is interpolated with params at runtime. TypeScript enforces that the pattern key exists in the channel map and that event and data match its declared event types.

Type Parameters

Pattern

Pattern extends string

Ev

Ev extends string

Parameters

pattern

Pattern

params

ChannelParamRecord<Pattern>

event

Ev

data

PayloadOf<Channels, Pattern, Ev>

Returns

void

Example

manager.toChannel('private-orders.[orderId]', { orderId: 42 }, 'OrderShipped', {
  orderId: 42, trackingCode: 'UPS-123',
});

send()

send(event): void

Defined in: broadcasting/src/TypedBroadcastManager.ts:182

Dispatch a typed broadcast event.

Accepts both TypedBroadcastEvent (with map-matched payload types) and the untyped BroadcastEvent interface, so this is a drop-in replacement for the base send().

Parameters

event

BroadcastEvent | TypedBroadcastEvent<Channels, keyof Channels & string, EventsOf<Channels, keyof Channels & string>>

Returns

void

Overrides

BroadcastManager.send