Class Room

Manages WebRTC peer connections, media streams, and data channels.

Index

Constructors

constructor

new Room(options?: RoomOptions): Room
Creates a new Room instance.
Parameters
- Optionaloptions: RoomOptions
  Room configuration options.
Returns Room
Example
```
// create a new room with default options
const room = new Room();
```
- Defined in src/room.ts:205

Accessors

active

get active(): boolean
Indicates whether the peer is currently active (joined a room).

Returns boolean
- Defined in src/room.ts:150

addons

get addons(): ReadonlySet<Addon>
Attachable extensions.

Returns ReadonlySet<Addon>
- Defined in src/room.ts:166

id

get id(): string
Unique room identifier.

Returns string
- Defined in src/room.ts:154

me

get me(): { id: string; metadata?: Record<string, unknown> } | null
Local peer id and metadata.

Returns { id: string; metadata?: Record<string, unknown> } | null
- Defined in src/room.ts:158

peers

get peers(): ReadonlyMap<string, Peer>
Active peers indexed by peer id.

Returns ReadonlyMap<string, Peer>
- Defined in src/room.ts:162

Methods

attach

attach(addon: Addon): Promise<void>
Attaches an addon/extension to the Room instance.
Parameters
- addon: Addon
  Addon instance to attach.
Returns Promise<void>
- Defined in src/room.ts:627

close

close(options: string | { label?: string }): Promise<void>
Closes a previously opened data channel with the given label and removes it from all peers.
Parameters
- options: string | { label?: string }
  Channel label or object containing label.
Returns Promise<void>
Example
```
// close the channel with an explicit label
await room.close({ label: "chat" });
```
- Defined in src/room.ts:534

detach

detach(addon: Addon): Promise<void>
Detaches a previously attached addon/extension from the Room instance.
Parameters
- addon: Addon
  Addon instance to detach.
Returns Promise<void>
- Defined in src/room.ts:637

emit

emit<K extends keyof RoomEvents>(event: K | K[], ...args: RoomEvents[K]): void
Emits one or more events. Typically, you would not call this method directly.
Type Parameters
- K extends keyof RoomEvents
Parameters
- event: K | K[]
  Event name or list of event names.
- ...args: RoomEvents[K]
  Event payload.
Returns void
- Defined in src/room.ts:696

join

join(
metadata?: Record<string, unknown>,
): Promise<{ id: string; metadata?: Record<string, unknown> } | null>
Joins a room and starts listening for incoming connections.

If the peer is already active, this method returns immediately without error.
Parameters
- Optionalmetadata: Record<string, unknown>
  Metadata to associate with the peer.
Returns Promise<{ id: string; metadata?: Record<string, unknown> } | null>
The local peer object with id and optional metadata, or null if already active.
Example
```
// join a room with optional metadata
const me = await room.join({ name: "Alice" });
console.log(`I am ${me.metadata.name} (ID: ${me.id})`);
```
- Defined in src/room.ts:264

leave

leave(): Promise<void>
Leaves the current room and closes all active connections.

If the room is not currently active, this method returns immediately without error.

Returns Promise<void>
Example
```
// leave the current room
await room.leave();
```
- Defined in src/room.ts:300

off

off<K extends keyof RoomEvents>(
event: K | K[],
handler?: (...args: RoomEvents[K]) => void,
): void
Removes a previously registered event listener.
Type Parameters
- K extends keyof RoomEvents
Parameters
- event: K | K[]
  Event name or list of event names.
- Optionalhandler: (...args: RoomEvents[K]) => void
  Event handler to remove. If omitted, all handlers for the given event(s) will be removed.
Returns void
- Defined in src/room.ts:682

on

on<K extends keyof RoomEvents>(
event: K | K[],
handler: (...args: RoomEvents[K]) => void,
): void
Subscribes to one or more room events.
Type Parameters
- K extends keyof RoomEvents
Parameters
- event: K | K[]
  Event name or list of event names.
- handler: (...args: RoomEvents[K]) => void
  Event handler.
Returns void
Example
```
// subscribe to the "connection" event
room.on("connection", (e) => {
  console.log("Connection state has changed:", e.state);
});
```
- Defined in src/room.ts:656

once

once<K extends keyof RoomEvents>(
event: K | K[],
handler: (...args: RoomEvents[K]) => void,
): void
Subscribes to an event and auto-unsubscribes after first invocation.
Type Parameters
- K extends keyof RoomEvents
Parameters
- event: K | K[]
  Event name or list of event names.
- handler: (...args: RoomEvents[K]) => void
  Event handler.
Returns void
- Defined in src/room.ts:669

open

open(options: string | ChannelOptions): Promise<void>
Opens a data channel with the given label and options to all peers. If a channel with the same label already exists, it will be reused.

You can open a channel with the same label on both local and remote peers or only on one side. In any case, only one channel will be created for each label. You can send data through the channel in both directions.
Parameters
- options: string | ChannelOptions
  Channel options or channel label.
Returns Promise<void>
Example
```
// open a channel with an explicit label
await room.open({ label: "chat" });
```
- Defined in src/room.ts:507

send

send(
message: unknown,
options?: string | SendOptions,
): ReadableStream<TransferProgress> & Promise<void>
Sends a message through data channels to all connected peers.

If options is a string, it is treated as the channel label. If a label is not provided, it uses the default channel.

The send method works only with open channels that have no protocol, are ordered (reliable), and match the specified label.
Parameters
- message: unknown
  Message payload to send.
- Optionaloptions: string | SendOptions
  Send options or channel label.
Returns ReadableStream<TransferProgress> & Promise<void>
An iterable aggregated transfer progress across all connections or a promise which resolves when all transfers complete or error.
Example
```
// send a message to default channel
await room.send("Hello, all peers!");
// send large data with a progress handler
const file = new File([new Uint8Array(1024 * 1024)], "example.dat");
const transfer = room.send(file, {
  label: "chat", // channel label
  info: { filename: file.name }, // metadata
  signal: AbortSignal.timeout(10000), // abort signal
});
// optionally handle the progress
for await (const progress of transfer) {
  const { id, label, current, total } = progress;
  const percent = Math.round((current / total) * 100);
  console.log(`[${id}:${label}] Sending... ${percent}%`);
}
```
- Defined in src/room.ts:582

share(options: MediaStream | StreamOptions): Promise<void>
Shares a new media stream or updates an existing one for all peers including new ones that join later.

If you pass a MediaStream instance directly, it will be shared under a label equal to the stream id. Otherwise, you can specify an explicit label in the options object. If a stream with the same label already exists, it will be updated and its tracks will be added/removed as needed to minimize renegotiations.
Parameters
- options: MediaStream | StreamOptions
  Stream descriptor or MediaStream instance.
Returns Promise<void>
Example
```
// get a media stream from the user's camera and microphone
const stream = await navigator.mediaDevices.getUserMedia(
  { video: true, audio: true }
);

// share a media stream with an explicit label
await room.share({ label: "camera", stream });
```
- Defined in src/room.ts:345

toJSON

toJSON(): {
    active: boolean;
    id: string;
    me: { id: string; metadata?: Record<string, unknown> }
    | null;
    peers: string[];
}
Serializes the room to a JSON-compatible object.

Returns {
    active: boolean;
    id: string;
    me: { id: string; metadata?: Record<string, unknown> } | null;
    peers: string[];
}
A serializable representation of the room.
- Defined in src/room.ts:708

unshare

unshare(options: string | MediaStream | { label?: string }): Promise<void>
Stops sharing a previously shared media stream with the given label and removes it from all peers.

If you pass a MediaStream instance directly, it will be unshared using its id as the label. Otherwise, you can specify the label in the options object or pass it directly as a string.
Parameters
- options: string | MediaStream | { label?: string }
  A stream label, MediaStream instance, or an object containing a label.
Returns Promise<void>
Example
```
// unshare a media stream with an explicit label
await room.unshare({ label: "camera" });
```
- Defined in src/room.ts:450

Class Room

Index

Constructors

Accessors

Methods

Constructors

constructor

Parameters

Returns Room

Example

Accessors

active

Returns boolean

addons

Returns ReadonlySet<Addon>

id

Returns string

me

Returns { id: string; metadata?: Record<string, unknown> } | null

peers

Returns ReadonlyMap<string, Peer>

Methods

attach

Parameters

Returns Promise<void>

close

Parameters

Returns Promise<void>

Example

detach

Parameters

Returns Promise<void>

emit

Type Parameters

Parameters

Returns void

join

Parameters

Returns Promise<{ id: string; metadata?: Record<string, unknown> } | null>

Example

leave

Returns Promise<void>

Example

off

Type Parameters

Parameters

Returns void

on

Type Parameters

Parameters

Returns void

Example

once

Type Parameters

Parameters

Returns void

open

Parameters

Returns Promise<void>

Example

send

Parameters

Returns ReadableStream<TransferProgress> & Promise<void>

Example

share

Parameters

Returns Promise<void>

Example

toJSON

Returns { active: boolean; id: string; me: { id: string; metadata?: Record<string, unknown> } | null; peers: string[];}

unshare

Parameters

Returns Promise<void>

Example

Settings

On This Page

Returns {
active: boolean;
id: string;
me: { id: string; metadata?: Record<string, unknown> } | null;
peers: string[];
}