Class Room

A group of peers that exchange signaling messages with one another.

Remarks

A room is created lazily by SignalingServer when its first peer joins and, unless kept alive, closes automatically when its last peer leaves. It relays directed signals (Room.relay), fans out broadcasts (Room.broadcast / Room.broadcastExcept), tracks per-peer roles and metadata, and enforces optional capacity, idle-timeout, and max-duration limits. Its lifecycle is modeled by RoomState.

Rooms extend the core EventEmitter and emit RoomEvent values as peers join, leave, error, or are kicked, and when the room closes. You typically obtain a room from SignalingServer.getRoom or the ServerEvent.RoomCreated event rather than constructing it directly.

Hierarchy (View Summary)

EventEmitter<RoomEvents>
- Room

Index

Constructors

constructor

Properties

Accessors

state

Constructors

constructor

new Room(
    id: string,
    opts?: {
        idleTimeoutMs?: number;
        keepAliveOnEmpty?: boolean;
        maxDurationMs?: number;
        maxPeers?: number;
    },
): Room
Creates a room. Normally called by SignalingServer; construct directly only in tests or custom hosts.
Parameters
- id: string
  The room's stable identifier.
- opts: {
      idleTimeoutMs?: number;
      keepAliveOnEmpty?: boolean;
      maxDurationMs?: number;
      maxPeers?: number;
  } = {}
  Optional limits.
  - OptionalidleTimeoutMs?: number
    Idle window; the room force-closes if there is no relay/broadcast activity for this long while RoomState.Active.
  - OptionalkeepAliveOnEmpty?: boolean
    When true, the room stays open after the last peer leaves instead of closing.
  - OptionalmaxDurationMs?: number
    Hard lifetime; the room force-closes after this many milliseconds regardless of activity.
  - OptionalmaxPeers?: number
    Maximum concurrent peers; further joins are rejected with CloseReason.RoomFull.
Returns Room
Default Value
false
Overrides EventEmitter.constructor
- Defined in signaling/src/Room.ts:63

Properties

`Readonly`id

id: string

Stable identifier of this room, taken from the joining peers' auth payloads.

Accessors

state

get state(): RoomState
The room's current lifecycle state. See RoomState.

Returns RoomState
- Defined in signaling/src/Room.ts:85

Methods

addPeer

addPeer(peer: Peer, iceServers?: IceServerConfig[]): boolean
Adds a peer to the room and sends it the initial room-joined message.
Parameters
- peer: Peer
  The peer to add.
- OptionaliceServers: IceServerConfig[]
  ICE servers to include in the peer's room-joined message, typically from SignalingServerOptions.iceServersHook.
Returns boolean
true if the peer was admitted; false if the room was full.

Remarks
If a peer with the same id is already present, the existing connection is disconnected with CloseReason.ReplacedByReconnection and replaced (reconnection semantics). If the room is at capacity, the incoming peer is disconnected with CloseReason.RoomFull and false is returned. On a genuinely new peer, the room notifies the others with peer-joined and presence-online, transitions to RoomState.Active, and emits RoomEvent.PeerJoined.

Throws
If sending the initial room-joined message fails; the peer is rolled back out of the room before the error propagates.
- Defined in signaling/src/Room.ts:146

broadcast

broadcast(
    msg:
        | {
            iceServers?: {
                credential?: string;
                urls: string
                | string[];
                username?: string;
            }[];
            localRole?: string;
            peerId: string;
            peerMetadata?: Record<string, Record<string, string>>;
            peerRoles?: Record<string, string>;
            peers: string[];
            roomId: string;
            type: "room-joined";
            v?: number;
        }
        | {
            metadata?: Record<string, string>;
            peerId: string;
            role?: string;
            type: "peer-joined";
        }
        | { peerId: string; type: "peer-left" }
        | { peerId: string; type: "presence-online" }
        | { peerId: string; type: "presence-offline" }
        | { peerId: string; reason?: string; type: "kicked" }
        | { data: unknown; from: string; type: "signal" }
        | {
            channel: string;
            data?: unknown;
            from: string;
            ts: number;
            type: "broadcast";
        }
        | { code: string; message: string; type: "error" }
        | { type: "ping" }
        | { peerId: string; role: string; type: "role-changed" },
): string[]
Sends a message to every peer in the room.
Parameters
- msg:
      | {
          iceServers?: {
              credential?: string;
              urls: string
              | string[];
              username?: string;
          }[];
          localRole?: string;
          peerId: string;
          peerMetadata?: Record<string, Record<string, string>>;
          peerRoles?: Record<string, string>;
          peers: string[];
          roomId: string;
          type: "room-joined";
          v?: number;
      }
      | {
          metadata?: Record<string, string>;
          peerId: string;
          role?: string;
          type: "peer-joined";
      }
      | { peerId: string; type: "peer-left" }
      | { peerId: string; type: "presence-online" }
      | { peerId: string; type: "presence-offline" }
      | { peerId: string; reason?: string; type: "kicked" }
      | { data: unknown; from: string; type: "signal" }
      | {
          channel: string;
          data?: unknown;
          from: string;
          ts: number;
          type: "broadcast";
      }
      | { code: string; message: string; type: "error" }
      | { type: "ping" }
      | { peerId: string; role: string; type: "role-changed" }
  The server message to fan out.
  - {
        iceServers?: {
            credential?: string;
            urls: string | string[];
            username?: string;
        }[];
        localRole?: string;
        peerId: string;
        peerMetadata?: Record<string, Record<string, string>>;
        peerRoles?: Record<string, string>;
        peers: string[];
        roomId: string;
        type: "room-joined";
        v?: number;
    }
    OptionaliceServers?: { credential?: string; urls: string | string[]; username?: string }[]
    OptionallocalRole?: string
    peerId: string
    OptionalpeerMetadata?: Record<string, Record<string, string>>
    OptionalpeerRoles?: Record<string, string>
    peers: string[]
    roomId: string
    type: "room-joined"
    Optionalv?: number
    Server's signaling protocol version; see PROTOCOL_VERSION. Optional for back-compat.
  - {
        metadata?: Record<string, string>;
        peerId: string;
        role?: string;
        type: "peer-joined";
    }
  - { peerId: string; type: "peer-left" }
  - { peerId: string; type: "presence-online" }
  - { peerId: string; type: "presence-offline" }
  - { peerId: string; reason?: string; type: "kicked" }
  - { data: unknown; from: string; type: "signal" }
  - { channel: string; data?: unknown; from: string; ts: number; type: "broadcast" }
  - { code: string; message: string; type: "error" }
  - { type: "ping" }
  - { peerId: string; role: string; type: "role-changed" }
Returns string[]
Ids of peers whose send failed (each also emits RoomEvent.PeerError); empty when all sends succeeded.
- Defined in signaling/src/Room.ts:305

broadcastExcept

broadcastExcept(
    excludeId: string,
    msg:
        | {
            iceServers?: {
                credential?: string;
                urls: string
                | string[];
                username?: string;
            }[];
            localRole?: string;
            peerId: string;
            peerMetadata?: Record<string, Record<string, string>>;
            peerRoles?: Record<string, string>;
            peers: string[];
            roomId: string;
            type: "room-joined";
            v?: number;
        }
        | {
            metadata?: Record<string, string>;
            peerId: string;
            role?: string;
            type: "peer-joined";
        }
        | { peerId: string; type: "peer-left" }
        | { peerId: string; type: "presence-online" }
        | { peerId: string; type: "presence-offline" }
        | { peerId: string; reason?: string; type: "kicked" }
        | { data: unknown; from: string; type: "signal" }
        | {
            channel: string;
            data?: unknown;
            from: string;
            ts: number;
            type: "broadcast";
        }
        | { code: string; message: string; type: "error" }
        | { type: "ping" }
        | { peerId: string; role: string; type: "role-changed" },
): string[]
Sends a message to every peer except one.
Parameters
- excludeId: string
  Id of the peer to skip (usually the sender).
- msg:
      | {
          iceServers?: {
              credential?: string;
              urls: string
              | string[];
              username?: string;
          }[];
          localRole?: string;
          peerId: string;
          peerMetadata?: Record<string, Record<string, string>>;
          peerRoles?: Record<string, string>;
          peers: string[];
          roomId: string;
          type: "room-joined";
          v?: number;
      }
      | {
          metadata?: Record<string, string>;
          peerId: string;
          role?: string;
          type: "peer-joined";
      }
      | { peerId: string; type: "peer-left" }
      | { peerId: string; type: "presence-online" }
      | { peerId: string; type: "presence-offline" }
      | { peerId: string; reason?: string; type: "kicked" }
      | { data: unknown; from: string; type: "signal" }
      | {
          channel: string;
          data?: unknown;
          from: string;
          ts: number;
          type: "broadcast";
      }
      | { code: string; message: string; type: "error" }
      | { type: "ping" }
      | { peerId: string; role: string; type: "role-changed" }
  The server message to fan out.
  - {
        iceServers?: {
            credential?: string;
            urls: string | string[];
            username?: string;
        }[];
        localRole?: string;
        peerId: string;
        peerMetadata?: Record<string, Record<string, string>>;
        peerRoles?: Record<string, string>;
        peers: string[];
        roomId: string;
        type: "room-joined";
        v?: number;
    }
    OptionaliceServers?: { credential?: string; urls: string | string[]; username?: string }[]
    OptionallocalRole?: string
    peerId: string
    OptionalpeerMetadata?: Record<string, Record<string, string>>
    OptionalpeerRoles?: Record<string, string>
    peers: string[]
    roomId: string
    type: "room-joined"
    Optionalv?: number
    Server's signaling protocol version; see PROTOCOL_VERSION. Optional for back-compat.
  - {
        metadata?: Record<string, string>;
        peerId: string;
        role?: string;
        type: "peer-joined";
    }
  - { peerId: string; type: "peer-left" }
  - { peerId: string; type: "presence-online" }
  - { peerId: string; type: "presence-offline" }
  - { peerId: string; reason?: string; type: "kicked" }
  - { data: unknown; from: string; type: "signal" }
  - { channel: string; data?: unknown; from: string; ts: number; type: "broadcast" }
  - { code: string; message: string; type: "error" }
  - { type: "ping" }
  - { peerId: string; role: string; type: "role-changed" }
Returns string[]
Ids of peers whose send failed; empty when all sends succeeded.
- Defined in signaling/src/Room.ts:316

disconnectAndRemove

disconnectAndRemove(peerId: string, code: number, reason: string): boolean
Disconnects a peer and removes it from the room synchronously, without sending a kicked message.
Parameters
- peerId: string
  Id of the peer to disconnect and remove.
- code: number
  WebSocket close code.
- reason: string
  WebSocket close reason.
Returns boolean
true if the peer was found and removed; false otherwise.

Remarks
Used by the heartbeat monitor to prune an unresponsive peer. Mirrors Room.kickPeer's synchronous removal so the peer does not linger in Room.getPeers (where it would be re-disconnected on every tick) or keep holding a maxPeers slot while its ws close handshake completes.
- Defined in signaling/src/Room.ts:266

dispose

dispose(): void
Tears down the room's timers and moves it to RoomState.Closed without notifying or disconnecting peers. Used during server shutdown, where connections are closed separately.

Returns void
- Defined in signaling/src/Room.ts:401

emit

emit<K extends keyof RoomEvents>(event: K, ...args: RoomEvents[K]): boolean
Synchronously invokes every listener registered for event, in registration order.
Type Parameters
- K extends keyof RoomEvents
Parameters
- event: K
  The event name to emit.
- ...args: RoomEvents[K]
  The argument tuple to pass to each listener, matching Events[event].
Returns boolean
true if at least one listener was invoked, false if there were none.

Remarks
The listener list is snapshotted before dispatch, so mutations made by handlers take effect only on subsequent emissions. Listeners are isolated: if one throws, the remaining listeners still run and the error is surfaced via console.error rather than swallowed silently (consistent with LocalMessageBus).
Inherited from EventEmitter.emit
- Defined in core/src/EventEmitter.ts:95

getPeer

getPeer(id: string): Peer | undefined
Looks up a peer by id.
Parameters
- id: string
  The peer id.
Returns Peer | undefined
The Peer, or undefined if not present.
- Defined in signaling/src/Room.ts:123

getPeerCount

getPeerCount(): number
Returns number
The number of peers currently in the room.
- Defined in signaling/src/Room.ts:106

getPeerIds

getPeerIds(): string[]
Returns string[]
A snapshot array of the ids of all peers in the room.
- Defined in signaling/src/Room.ts:113

getPeerMetadata

getPeerMetadata(peerId: string): Record<string, string> | undefined
Returns a copy of the metadata a peer supplied at join time.
Parameters
- peerId: string
  The peer id.
Returns Record<string, string> | undefined
A shallow copy of the peer's metadata, or undefined if the peer is unknown or supplied none.
- Defined in signaling/src/Room.ts:372

getPeers

getPeers(): Peer[]
Returns Peer[]
A snapshot array of all Peers currently in the room.
- Defined in signaling/src/Room.ts:99

kickPeer

kickPeer(peerId: string, reason?: string): boolean
Forcibly removes a peer from the room.
Parameters
- peerId: string
  Id of the peer to remove.
- Optionalreason: string
  Optional human-readable reason sent to the peer and used as the close reason; defaults to CloseReason.Kicked.
Returns boolean
true if the peer was found and kicked; false otherwise.

Remarks
Sends the peer a kicked message, disconnects it with CloseCode.PolicyViolation, and emits RoomEvent.PeerKicked.
- Defined in signaling/src/Room.ts:236

listenerCount

listenerCount<K extends keyof RoomEvents>(event: K): number
Returns the number of listeners currently registered for event.
Type Parameters
- K extends keyof RoomEvents
Parameters
- event: K
  The event name to count listeners for.
Returns number
The count of registered listeners (0 if none).
Inherited from EventEmitter.listenerCount
- Defined in core/src/EventEmitter.ts:128

markActivity

markActivity(): void
Marks the room as active, resetting the idle-timeout countdown.

Returns void
Remarks
Called on heartbeat pongs so that quiet-but-alive rooms are not closed by SignalingServerOptions.roomIdleTimeoutMs.
- Defined in signaling/src/Room.ts:361

off

off<K extends keyof RoomEvents>(
event: K,
listener: (...args: RoomEvents[K]) => void,
): this
Removes a previously registered listener for event.
Type Parameters
- K extends keyof RoomEvents
Parameters
- event: K
  The event name the listener was registered for.
- listener: (...args: RoomEvents[K]) => void
  The exact function reference passed to on or once.
Returns this
This emitter, for chaining.

Remarks
If the listener is not currently registered, this is a no-op. Only the first matching registration is removed.
Inherited from EventEmitter.off
- Defined in core/src/EventEmitter.ts:74

on

on<K extends keyof RoomEvents>(
event: K,
listener: (...args: RoomEvents[K]) => void,
): this
Registers a listener that is invoked every time event is emitted.
Type Parameters
- K extends keyof RoomEvents
Parameters
- event: K
  The event name to listen for.
- listener: (...args: RoomEvents[K]) => void
  Callback invoked with the event's argument tuple.
Returns this
This emitter, for chaining.
Inherited from EventEmitter.on
- Defined in core/src/EventEmitter.ts:43

once

once<K extends keyof RoomEvents>(
event: K,
listener: (...args: RoomEvents[K]) => void,
): this
Registers a listener that is invoked at most once: it is removed automatically before being called the first time event is emitted.
Type Parameters
- K extends keyof RoomEvents
Parameters
- event: K
  The event name to listen for.
- listener: (...args: RoomEvents[K]) => void
  Callback invoked with the event's argument tuple on the next emission.
Returns this
This emitter, for chaining.

Remarks
Remove a pending one-time listener by passing the same function reference to off.
Inherited from EventEmitter.once
- Defined in core/src/EventEmitter.ts:57

relay

relay(fromId: string, toId: string, data: unknown): boolean
Relays a directed signal from one peer to another and counts as room activity (resets the idle timer).
Parameters
- fromId: string
  Id of the sending peer (stamped on the outgoing signal).
- toId: string
  Id of the recipient peer.
- data: unknown
  Opaque signal payload (SDP/ICE, etc.).
Returns boolean
true if the recipient existed and the message was sent; false if the recipient is absent or the send failed (which also emits RoomEvent.PeerError).
- Defined in signaling/src/Room.ts:285

removeAllListeners

removeAllListeners(event?: keyof RoomEvents): this
Removes listeners for a single event, or for all events.
Parameters
- Optionalevent: keyof RoomEvents
  The event name to clear; if omitted, listeners for every event are removed.
Returns this
This emitter, for chaining.
Inherited from EventEmitter.removeAllListeners
- Defined in core/src/EventEmitter.ts:116

setPeerRole

setPeerRole(peerId: string, newRole: string): boolean
Changes a peer's role and notifies the whole room.
Parameters
- peerId: string
  Id of the peer whose role is changing.
- newRole: string
  The new role string.
Returns boolean
true if the peer was found and updated; false otherwise.

Remarks
Updates the peer's role and broadcasts a role-changed message to every peer (including the affected one).
- Defined in signaling/src/Room.ts:388

Class Room

Remarks

Hierarchy (View Summary)

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Parameters

OptionalidleTimeoutMs?: number

OptionalkeepAliveOnEmpty?: boolean

OptionalmaxDurationMs?: number

OptionalmaxPeers?: number

Returns Room

Default Value

Properties

Readonlyid

Accessors

state

Returns RoomState

Methods

addPeer

Parameters

Returns boolean

Remarks

Throws

broadcast

Parameters

OptionaliceServers?: { credential?: string; urls: string | string[]; username?: string }[]

OptionallocalRole?: string

peerId: string

OptionalpeerMetadata?: Record<string, Record<string, string>>

OptionalpeerRoles?: Record<string, string>

peers: string[]

roomId: string

type: "room-joined"

Optionalv?: number

Returns string[]

broadcastExcept

Parameters

OptionaliceServers?: { credential?: string; urls: string | string[]; username?: string }[]

OptionallocalRole?: string

peerId: string

OptionalpeerMetadata?: Record<string, Record<string, string>>

OptionalpeerRoles?: Record<string, string>

peers: string[]

roomId: string

type: "room-joined"

Optionalv?: number

Returns string[]

disconnectAndRemove

Parameters

Returns boolean

Remarks

dispose

Returns void

emit

Type Parameters

Parameters

Returns boolean

Remarks

getPeer

Parameters

Returns Peer | undefined

getPeerCount

Returns number

getPeerIds

Returns string[]

getPeerMetadata

Parameters

Returns Record<string, string> | undefined

getPeers

Returns Peer[]

kickPeer

Parameters

Returns boolean

Remarks

listenerCount

`Optional`idleTimeoutMs?: number

`Optional`keepAliveOnEmpty?: boolean

`Optional`maxDurationMs?: number

`Optional`maxPeers?: number

`Readonly`id

`Optional`iceServers?: { credential?: string; urls: string | string[]; username?: string }[]

`Optional`localRole?: string

`Optional`peerMetadata?: Record<string, Record<string, string>>

`Optional`peerRoles?: Record<string, string>

`Optional`v?: number

`Optional`iceServers?: { credential?: string; urls: string | string[]; username?: string }[]

`Optional`localRole?: string

`Optional`peerMetadata?: Record<string, Record<string, string>>

`Optional`peerRoles?: Record<string, string>

`Optional`v?: number