peerix - v0.8.0
    Preparing search index...

    Class Peer<M>

    Represents a peer connection. Do not create Peer instances manually.

    Type Parameters

    Index
    • get channels(): ReadonlyMap<string, RTCDataChannel>

      Negotiated data channels keyed by channel label.

      Returns ReadonlyMap<string, RTCDataChannel>

    • get connection(): RTCPeerConnection

      Native WebRTC peer connection to the peer.

      Returns RTCPeerConnection

    • get id(): string

      Peer identifier.

      Returns string

    • get metadata(): M | undefined

      Metadata advertised by the peer.

      Returns M | undefined

    • get streams(): ReadonlyMap<string, MediaStream>

      Remote media streams keyed by stream label.

      Returns ReadonlyMap<string, MediaStream>

    • Closes a previously opened data channel to the current peer.

      Parameters

      • options: string | { label?: string }

        Channel label or object containing label.

      Returns Promise<void>

      // close the channel with label "chat"
      await peer.close({ label: "chat" });
    • Closes and frees all connection resources.

      Returns void

    • Removes a previously registered event listener.

      Type Parameters

      Parameters

      • event: K

        Event name.

      • Optionalhandler: (...args: PeerEvents<M>[K]) => void

        Event handler to remove. If omitted, all handlers for the event will be removed.

      Returns void

    • Subscribes to a peer event.

      Type Parameters

      Parameters

      • event: K

        Event name.

      • handler: (...args: PeerEvents<M>[K]) => void

        Event handler.

      • Optionaloptions: ListenerOptions

        Listener options, such as an AbortSignal that removes the handler.

      Returns () => void

      A function that removes the handler.

      // subscribe to the "connection" event
      peer.on("connection", (e) => {
      console.log("Connection state has changed:", e.state);
      });
    • Subscribes to an event and auto-unsubscribes after first invocation.

      Type Parameters

      Parameters

      • event: K

        Event name.

      • handler: (...args: PeerEvents<M>[K]) => void

        Event handler.

      • Optionaloptions: ListenerOptions

        Listener options, such as an AbortSignal that removes the handler.

      Returns () => void

      A function that removes the handler.

    • Opens a data channel to the current peer.

      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.

      It resolves once the channel is requested, not once it is open, so wait for channel:open before sending through it.

      Parameters

      Returns Promise<void>

      // open a channel with label "chat"
      await peer.open({ label: "chat" });
    • Sends a message through a data channel.

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

      The send method works only with open channels that match the specified label and are either ordered (reliable) without a protocol, or have a protocol, which makes them raw. A raw channel accepts only strings and binary data, and an unreliable one drops a message while its buffer is backed up. Failures, including a missing channel, are PeerixError instances with the DATACHANNEL_ERROR code. A transfer fails once the channel buffer stops draining for 10 seconds.

      Parameters

      • message: unknown

        Message payload to send.

      • Optionaloptions: string | SendOptions

        Send options or channel label.

      Returns ReadableStream<TransferProgress> & Promise<void>

      A ReadableStream of transfer progress status or a Promise.

      // send a message to default channel
      await peer.send("Hello, peer!");
      // 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 }, // sent with the first chunk
      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}%`);
      }
    • Shares a new media stream to the current peer or updates an existing one.

      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>

      // 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 peer.share({ label: "camera", stream });
    • Serializes the peer to a JSON-compatible object.

      Returns {
          channels: string[];
          id: string;
          metadata?: M;
          state: ConnectionState;
          streams: string[];
      }

      A serializable representation of the peer.

    • Stops sharing a previously shared media stream to the current peer.

      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.

      Unmanaged tracks are stopped, except for streams shared through Room.share, whose tracks other peers still use.

      Parameters

      • options: string | MediaStream | { label?: string }

        A stream label, MediaStream instance, or an object containing a label.

      Returns Promise<void>

      // unshare a media stream with an explicit label
      await peer.unshare({ label: "camera" });