Class Peer

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

Example

// create a new peer
// using default in-memory signaling driver
const peer = new Peer();

// listen for connection state changes
peer.on("connection", (e) => {
  const { remote, state } = e;
  console.log(`Peer "${remote.id}" state changed to "${state}"`);
});

// listen for open channel event
peer.on("channel:open", (e) => {
  const { remote, label } = e;
  console.log(`Channel "${label}" opened with peer "${remote.id}"`);
  // send a message to the remote peer
  remote.send("Hello, peer!", { label });
});

// listen for incoming messages
peer.on("channel:message", async (e) => {
  const { remote, data, label } = e;
  const message = await data;
  console.log(`Message from peer "${remote.id}" on channel "${label}":`, message);
});

// open a data channel
await peer.open({ label: "default" });

// join a room
await peer.join({ room: "room-id" });

Index

Constructors

constructor

new Peer(options?: PeerOptions): Peer
Creates a new Peer instance.
Parameters
- Optionaloptions: PeerOptions
  Peer configuration options.
Returns Peer
Example
```
// create a new peer with default options
const peer = new Peer();
```
- Defined in src/peer.ts:122

Accessors

active

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

Returns boolean
- Defined in src/peer.ts:59

addons

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

Returns Set<Addon>
- Defined in src/peer.ts:87

channels

get channels(): Map<string, ChannelOptions>
Configured local data channels indexed by channel label.

Returns Map<string, ChannelOptions>
- Defined in src/peer.ts:83

connections

get connections(): Map<string, RemotePeer>
Active remote peers indexed by remote peer id.

Returns Map<string, RemotePeer>
- Defined in src/peer.ts:75

id

get id(): string
Unique identifier for the local peer. Empty until join() is called.

Returns string
- Defined in src/peer.ts:63

metadata

get metadata(): unknown
Optional metadata announced to other peers in signaling messages. Undefined until join() is called.

Returns unknown
- Defined in src/peer.ts:71

room

get room(): string
Current room name. Empty until join() is called.

Returns string
- Defined in src/peer.ts:67

streams

get streams(): Map<string, StreamOptions>
Configured local streams indexed by application-level stream label.

Returns Map<string, StreamOptions>
- Defined in src/peer.ts:79

Methods

attach

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

close

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

detach

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

emit

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

join

join(options?: string | PeerJoinOptions): Promise<void>
Joins a room and starts listening for incoming connections.
Parameters
- Optionaloptions: string | PeerJoinOptions
  Room name or join options.
Returns Promise<void>
Example
```
// join a room with ID "room-id" and custom metadata
await peer.join({ room: "room-id", metadata: { name: "Alice" } });
```
- Defined in src/peer.ts:173

leave

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

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

off

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

on

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

once

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

open

open(options: string | ChannelOptions): Promise<void>
Opens a data channel with the given label and options to all remote 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 label "chat"
await peer.open({ label: "chat" });
```
- Defined in src/peer.ts:387

send

send(
message: unknown,
options?: string | SendOptions,
): ReadableStream<TransferProgress> & Promise<void>
Sends a message through data channels to all connected remote 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>
A ReadableStream of aggregated transfer progress across all connections. The returned value also implements Promise, which resolves when all transfers complete or error.
Example
```
// send a message to default channel
await peer.send("Hello, all peers!");
// send large data with a progress handler
const file = new File([new Uint8Array(1024 * 1024)], "example.dat");
const transfer = peer.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/peer.ts:466

share(options: MediaStream | StreamOptions): Promise<void | MediaStream>
Shares a new media stream or updates an existing one for all remote 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.

If the stream is shared with the managed option, its tracks will be automatically stopped when the stream is unshared or replaced with a new stream.
Parameters
- options: MediaStream | StreamOptions
  Stream descriptor or MediaStream instance.
Returns Promise<void | MediaStream>
The shared MediaStream instance if successful, or undefined.
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
const sharedStream = await peer.share({ label: "camera", stream, managed: true });
```
- Defined in src/peer.ts:260

toJSON

toJSON(): {
    active: boolean;
    channels: string[];
    connections: string[];
    id: string;
    metadata: unknown;
    room: string;
    streams: string[];
}
Serializes the peer to a JSON-compatible object.

Returns {
    active: boolean;
    channels: string[];
    connections: string[];
    id: string;
    metadata: unknown;
    room: string;
    streams: string[];
}
A serializable representation of the peer.
- Defined in src/peer.ts:593

unshare

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

If the stream was shared with the managed option, its tracks will be stopped automatically.
Parameters
- options: string | MediaStream | { label?: string }
  A stream label, MediaStream instance, or an object containing a label.
Returns Promise<void | MediaStream>
The unshared MediaStream instance, or undefined.
Example
```
// unshare a media stream with an explicit label
await peer.unshare({ label: "camera" });
```
- Defined in src/peer.ts:334

Class Peer

Example

Index

Constructors

Accessors

Methods

Constructors

constructor

Parameters

Returns Peer

Example

Accessors

active

Returns boolean

addons

Returns Set<Addon>

channels

Returns Map<string, ChannelOptions>

connections

Returns Map<string, RemotePeer>

id

Returns string

metadata

Returns unknown

room

Returns string

streams

Returns Map<string, StreamOptions>

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<void>

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 | MediaStream>

Example

toJSON

Returns { active: boolean; channels: string[]; connections: string[]; id: string; metadata: unknown; room: string; streams: string[];}

unshare

Parameters

Returns Promise<void | MediaStream>

Returns {
active: boolean;
channels: string[];
connections: string[];
id: string;
metadata: unknown;
room: string;
streams: string[];
}