docs: document `Peer` inline

.

docs/api.json

@@ -1,322 +1,2 @@
 [
-  {
-    "name": "Peer",
-    "type": "constructor",
-    "snippet": "const peer = new Peer([id], [options]);",
-    "description": "A peer can connect to other peers and listen for connections.",
-    "children": [
-      {
-        "name": "id",
-        "optional": true,
-        "type": "string",
-        "description": "Other peers can connect to this peer using the provided ID. If no ID is given, one will be generated by the brokering server. The ID must start and end with an alphanumeric character (lower or upper case character or a digit). In the middle of the ID spaces, dashes (-) and underscores (_) are allowed.<span class='warn'>It's not recommended that you use this ID to identify peers, as it's meant to be used for brokering connections only. You're recommended to set the <a href='#peerconnect-options'><code>metadata</code></a> option to send other identifying information.</span>"
-      },
-      {
-        "name": "options",
-        "optional": true,
-        "type": "object",
-        "children": [
-          {
-            "name": "key",
-            "type": "string",
-            "description": "API key for the cloud PeerServer. This is not used for servers other than <code>0.peerjs.com</code>.<span class='warn'>PeerServer cloud runs on port 443. Please ensure it is not blocked or consider running your own PeerServer instead.</span>"
-          },
-          {
-            "name": "host",
-            "type": "string",
-            "description": "Server host. Defaults to <code>0.peerjs.com</code>. Also accepts <code>'/'</code> to signify relative hostname."
-          },
-          {
-            "name": "port",
-            "type": "number",
-            "description": "Server port. Defaults to <code>443</code>."
-          },
-          {
-            "name": "pingInterval",
-            "type": "number",
-            "description": "Ping interval in ms. Defaults to <code>5000</code>."
-          },
-          {
-            "name": "path",
-            "type": "string",
-            "description": "The path where your self-hosted PeerServer is running. Defaults to <code>'/'</code>."
-          },
-          {
-            "name": "secure",
-            "type": "boolean",
-            "description": "<code>true</code> if you're using SSL.<span class='tip'>Note that our cloud-hosted server and assets may not support SSL.</span>"
-          },
-          {
-            "name": "config",
-            "type": "object",
-            "description": "Configuration hash passed to RTCPeerConnection. This hash contains any custom ICE/TURN server configuration. Defaults to <code>{ 'iceServers': [{ 'urls': 'stun:stun.l.google.com:19302' }, { 'urls': 'turn:0.peerjs.com:3478', username: 'peerjs', credential: 'peerjsp' }], 'sdpSemantics': 'unified-plan' }</code>"
-          },
-          {
-            "name": "debug",
-            "type": "number",
-            "description": "Prints log messages depending on the debug level passed in. Defaults to <code>0</code>.",
-            "children": [
-              {
-                "name": 0,
-                "description": "Prints no logs."
-              },
-              {
-                "name": 1,
-                "description": "Prints only errors."
-              },
-              {
-                "name": 2,
-                "description": "Prints errors and warnings."
-              },
-              {
-                "name": 3,
-                "description": "Prints all logs."
-              }
-            ]
-          }
-        ]
-      }
-    ]
-  },
-  {
-    "name": "peer.connect",
-    "type": "method",
-    "snippet": "const <a href='#dataconnection'>dataConnection</a> = peer.connect(id, [options]);",
-    "description": "Connects to the remote peer specified by <code>id</code> and returns a data connection. Be sure to listen on the <a href='#peeron-error'><code>error</code></a> event in case the connection fails.",
-    "children": [
-      {
-        "name": "id",
-        "type": "string",
-        "description": "The brokering ID of the remote peer (their <a href='#peerid'><code>peer.id</code></a>)."
-      },
-      {
-        "name": "options",
-        "optional": true,
-        "type": "object",
-        "children": [
-          {
-            "name": "label",
-            "type": "string",
-            "description": "A unique label by which you want to identify this data connection. If left unspecified, a label will be generated at random. Can be accessed with <a href='#dataconnection-label'><code>dataConnection.label</code></a>."
-          },
-          {
-            "name": "metadata",
-            "description": "Metadata associated with the connection, passed in by whoever initiated the connection. Can be accessed with <a href='#dataconnection-metadata'><code>dataConnection.metadata</code></a>. Can be any serializable type."
-          },
-          {
-            "name": "serialization",
-            "type": "string",
-            "description": "Can be <code>binary</code> (default), <code>binary-utf8</code>, <code>json</code>, or <code>none</code>. Can be accessed with <a href='#dataconnection-serialization'><code>dataConnection.serialization</code></a>.<span class='tip'><code>binary-utf8</code> will take a performance hit because of the way UTF8 strings are packed into binary format.</span>"
-          },
-          {
-            "name": "reliable",
-            "type": "boolean",
-            "description": "Whether the underlying data channels should be reliable (e.g. for large file transfers) or not (e.g. for gaming or streaming). Defaults to <code>false</code>.<span class='warn'>Setting reliable to true will use a shim for incompatible browsers (Chrome 30 and below only) and thus may not offer full performance.</span>"
-          }
-        ]
-      }
-    ]
-  },
-  {
-    "name": "peer.call",
-    "type": "method",
-    "snippet": "const <a href='#mediaconnection'>mediaConnection</a> = peer.call(id, stream, [options]);",
-    "description": "Calls the remote peer specified by <code>id</code> and returns a media connection. Be sure to listen on the <a href='#peeron-error'><code>error</code></a> event in case the connection fails.",
-    "children": [
-      {
-        "name": "id",
-        "type": "string",
-        "description": "The brokering ID of the remote peer (their <a href='#peerid'><code>peer.id</code></a>)."
-      },
-      {
-        "name": "stream",
-        "type": "MediaStream",
-        "description": "The caller's media stream"
-      },
-      {
-        "name": "options",
-        "optional": true,
-        "type": "object",
-        "children": [
-          {
-            "name": "metadata",
-            "description": "Metadata associated with the connection, passed in by whoever initiated the connection. Can be accessed with <a href='#mediaconnection-metadata'><code>mediaConnection.metadata</code></a>. Can be any serializable type."
-          },
-          {
-            "name": "sdpTransform",
-            "type": "method",
-            "description": "Function which runs before create offer to modify sdp offer message."
-          }
-        ]
-      }
-    ]
-  },
-  {
-    "name": "peer.on",
-    "type": "method",
-    "snippet": "peer.on(event, callback);",
-    "description": "Set listeners for peer events.",
-    "children": [
-      {
-        "name": "'open'",
-        "type": "event",
-        "snippet": "peer.on('open', function(id) { ... });",
-        "description": "Emitted when a connection to the PeerServer is established. You may use the peer before this is emitted, but messages to the server will be queued. <code>id</code> is the brokering ID of the peer (which was either provided in the constructor or assigned by the server).<span class='tip'>You should not wait for this event before connecting to other peers if connection speed is important.</span>"
-      },
-      {
-        "name": "'connection'",
-        "type": "event",
-        "snippet": "peer.on('connection', function(<a href='#dataconnection'>dataConnection</a>) { ... });",
-        "description": "Emitted when a new data connection is established from a remote peer."
-      },
-      {
-        "name": "'call'",
-        "type": "event",
-        "snippet": "peer.on('call', function(<a href='#mediaconnection'>mediaConnection</a>) { ... });",
-        "description": "Emitted when a remote peer attempts to call you. The emitted <code>mediaConnection</code> is not yet active; you must first answer the call (<a href='#mediaconnection-answer'><code>mediaConnection.answer([stream]);</code></a>). Then, you can listen for the <a href='#mediaconnection-on'><code>stream</code></a> event."
-      },
-      {
-        "name": "'close'",
-        "type": "event",
-        "snippet": "peer.on('close', function() { ... });",
-        "description": "Emitted when the peer is <a href='#peerdestroy'>destroyed</a> and can no longer accept or create any new connections. At this time, the peer's connections will all be closed. <span class='tip'>To be extra certain that peers clean up correctly, we recommend calling <code>peer.destroy()</code> on a peer when it is no longer needed.</span>"
-      },
-      {
-        "name": "'disconnected'",
-        "type": "event",
-        "snippet": "peer.on('disconnected', function() { ... });",
-        "description": "Emitted when the peer is disconnected from the signalling server, either <a href='#peerdisconnect'>manually</a> or because the connection to the signalling server was lost. When a peer is disconnected, its existing connections will stay alive, but the peer cannot accept or create any new connections. You can reconnect to the server by calling <a href='#peerreconnect'><code>peer.reconnect()</code></a>."
-      },
-      {
-        "name": "'error'",
-        "type": "event",
-        "snippet": "peer.on('error', function(err) { ... });",
-        "description": "Errors on the peer are <strong>almost always fatal</strong> and will destroy the peer. Errors from the underlying socket and PeerConnections are forwarded here.<br><br>These come in the following <code>err.type</code> flavors:",
-        "children": [
-          {
-            "name": "'browser-incompatible'",
-            "type": "Error",
-            "tags": [
-              "fatal"
-            ],
-            "description": "The client's browser does not support some or all WebRTC features that you are trying to use."
-          },
-          {
-            "name": "'disconnected'",
-            "type": "Error",
-            "description": "You've already disconnected this peer from the server and can no longer make any new connections on it."
-          },
-          {
-            "name": "'invalid-id'",
-            "type": "Error",
-            "tags": [
-              "fatal"
-            ],
-            "description": "The ID passed into the Peer constructor contains illegal characters."
-          },
-          {
-            "name": "'invalid-key'",
-            "type": "Error",
-            "tags": [
-              "fatal"
-            ],
-            "description": "The API key passed into the Peer constructor contains illegal characters or is not in the system (cloud server only)."
-          },
-          {
-            "name": "'network'",
-            "type": "Error",
-            "description": "Lost or cannot establish a connection to the signalling server."
-          },
-          {
-            "name": "'peer-unavailable'",
-            "type": "Error",
-            "description": "The peer you're trying to connect to does not exist."
-          },
-          {
-            "name": "'ssl-unavailable'",
-            "type": "Error",
-            "tags": [
-              "fatal"
-            ],
-            "description": "PeerJS is being used securely, but the cloud server does not support SSL. Use a custom PeerServer."
-          },
-          {
-            "name": "'server-error'",
-            "type": "Error",
-            "tags": [
-              "fatal"
-            ],
-            "description": "Unable to reach the server."
-          },
-          {
-            "name": "'socket-error'",
-            "type": "Error",
-            "tags": [
-              "fatal"
-            ],
-            "description": "An error from the underlying socket."
-          },
-          {
-            "name": "'socket-closed'",
-            "type": "Error",
-            "tags": [
-              "fatal"
-            ],
-            "description": "The underlying socket closed unexpectedly."
-          },
-          {
-            "name": "'unavailable-id'",
-            "type": "Error",
-            "tags": [
-              "sometimes fatal"
-            ],
-            "description": "The ID passed into the Peer constructor is already taken.<span class='warn'>This error is not fatal if your peer has open peer-to-peer connections. This can happen if you attempt to <a href='#peerreconnect'>reconnect</a> a peer that has been <a href='#peerdisconnect'>disconnected from the server</a>, but its old ID has now been taken.</span>"
-          },
-          {
-            "name": "'webrtc'",
-            "type": "Error",
-            "description": "Native WebRTC errors."
-          }
-        ]
-      }
-    ]
-  },
-  {
-    "name": "peer.disconnect",
-    "type": "method",
-    "snippet": "peer.disconnect();",
-    "description": "Close the connection to the server, leaving all existing data and media connections intact. <a href='#peerdisconnected'><code>peer.disconnected</code></a> will be set to <code>true</code> and the <a href='#peeron-disconnected'><code>disconnected</code></a> event will fire.<span class='warn'>This cannot be undone; the respective peer object will no longer be able to create or receive any connections and its ID will be forfeited on the (cloud) server.</span>"
-  },
-  {
-    "name": "peer.reconnect",
-    "type": "method",
-    "snippet": "peer.reconnect();",
-    "description": "Attempt to reconnect to the server with the peer's old ID. Only <a href='#peerdisconnect'>disconnected peers</a> can be reconnected. Destroyed peers cannot be reconnected. If the connection fails (as an example, if the peer's old ID is now taken), the peer's existing connections will not close, but any associated errors events will fire."
-  },
-  {
-    "name": "peer.destroy",
-    "type": "method",
-    "snippet": "peer.destroy();",
-    "description": "Close the connection to the server and terminate all existing connections. <a href='#peerdestroyed'><code>peer.destroyed</code></a> will be set to <code>true</code>.<span class='warn'>This cannot be undone; the respective peer object will no longer be able to create or receive any connections, its ID will be forfeited on the (cloud) server, and all of its data and media connections will be closed.</span>"
-  },
-  {
-    "name": "peer.id",
-    "type": "string",
-    "description": "The brokering ID of this peer. If no ID was specified in <a href='#peer'>the constructor</a>, this will be <code>undefined</code> until the <a href='#peeron-open'><code>open</code></a> event is emitted."
-  },
-  {
-    "name": "peer.connections",
-    "type": "object",
-    "description": "A hash of all connections associated with this peer, keyed by the remote peer's ID.<span class='tip'>We recommend keeping track of connections yourself rather than relying on this hash.</span>"
-  },
-  {
-    "name": "peer.disconnected",
-    "type": "boolean",
-    "description": "<code>false</code> if there is an active connection to the PeerServer."
-  },
-  {
-    "name": "peer.destroyed",
-    "type": "boolean",
-    "description": "<code>true</code> if this peer and all of its connections can no longer be used."
-  }
 ]

lib/enums.ts

@@ -4,17 +4,59 @@ export enum ConnectionType {
 }
 
 export enum PeerErrorType {
+	/**
+	 * The client's browser does not support some or all WebRTC features that you are trying to use.
+	 */
 	BrowserIncompatible = "browser-incompatible",
+	/**
+	 * You've already disconnected this peer from the server and can no longer make any new connections on it.
+	 */
 	Disconnected = "disconnected",
+	/**
+	 * The ID passed into the Peer constructor contains illegal characters.
+	 */
 	InvalidID = "invalid-id",
+	/**
+	 * The API key passed into the Peer constructor contains illegal characters or is not in the system (cloud server only).
+	 */
 	InvalidKey = "invalid-key",
+	/**
+	 * Lost or cannot establish a connection to the signalling server.
+	 */
 	Network = "network",
+	/**
+	 * The peer you're trying to connect to does not exist.
+	 */
 	PeerUnavailable = "peer-unavailable",
+	/**
+	 * PeerJS is being used securely, but the cloud server does not support SSL. Use a custom PeerServer.
+	 */
 	SslUnavailable = "ssl-unavailable",
+	/**
+	 * Unable to reach the server.
+	 */
 	ServerError = "server-error",
+	/**
+	 * An error from the underlying socket.
+	 */
 	SocketError = "socket-error",
+	/**
+	 * The underlying socket closed unexpectedly.
+	 */
 	SocketClosed = "socket-closed",
+	/**
+	 * The ID passed into the Peer constructor is already taken.
+	 *
+	 * :::caution
+	 * This error is not fatal if your peer has open peer-to-peer connections.
+	 * This can happen if you attempt to {@apilink Peer.reconnect} a peer that has been disconnected from the server,
+	 * but its old ID has now been taken.
+	 * :::
+	 */
 	UnavailableID = "unavailable-id",
+	/**
+	 * Native WebRTC errors.
+	 */
 	WebRTC = "webrtc",
 }
 

lib/exports.ts

@@ -1,6 +1,6 @@
 export { util, type Util } from "./util";
 import { Peer } from "./peer";
-export type { PeerEvents } from "./peer";
+export type { PeerEvents, PeerError } from "./peer";
 
 export type {
 	PeerJSOption,
@@ -9,6 +9,7 @@ export type {
 	CallOption,
 } from "./optionInterfaces";
 export type { UtilSupportsObj } from "./util";
+export type { BaseConnection } from "./baseconnection";
 export type { DataConnection, DataConnectionEvents } from "./dataconnection";
 export type { MediaConnection, MediaConnectionEvents } from "./mediaconnection";
 export type { LogLevel } from "./logger";

lib/logger.ts

@@ -8,9 +8,21 @@ Prints log messages depending on the debug level passed in. Defaults to 0.
 3  Prints all logs.
 */
 export enum LogLevel {
+	/**
+	 * Prints no logs.
+	 */
 	Disabled,
+	/**
+	 * Prints only errors.
+	 */
 	Errors,
+	/**
+	 * Prints errors and warnings.
+	 */
 	Warnings,
+	/**
+	 * Prints all logs.
+	 */
 	All,
 }
 

lib/optionInterfaces.ts

@@ -18,13 +18,34 @@ export interface PeerJSOption {
 }
 
 export interface PeerConnectOption {
+	/**
+	 * A unique label by which you want to identify this data connection.
+	 * If left unspecified, a label will be generated at random.
+	 *
+	 * Can be accessed with {@apilink DataConnection.label}
+	 */
 	label?: string;
+	/**
+	 * Metadata associated with the connection, passed in by whoever initiated the connection.
+	 *
+	 * Can be accessed with {@apilink DataConnection.metadata}.
+	 * Can be any serializable type.
+	 */
 	metadata?: any;
 	serialization?: string;
 	reliable?: boolean;
 }
 
 export interface CallOption {
+	/**
+	 * Metadata associated with the connection, passed in by whoever initiated the connection.
+	 *
+	 * Can be accessed with {@apilink MediaConnection.metadata}.
+	 * Can be any serializable type.
+	 */
 	metadata?: any;
+	/**
+	 * Function which runs before create offer to modify sdp offer message.
+	 */
 	sdpTransform?: Function;
 }

lib/peer.ts

@@ -19,22 +19,70 @@ import type {
 } from "./optionInterfaces";
 
 class PeerOptions implements PeerJSOption {
-	debug?: LogLevel; // 1: Errors, 2: Warnings, 3: All logs
+	/**
+	 * Prints log messages depending on the debug level passed in.
+	 */
+	debug?: LogLevel;
+	/**
+	 * Server host. Defaults to `0.peerjs.com`.
+	 * Also accepts `'/'` to signify relative hostname.
+	 */
 	host?: string;
+	/**
+	 * Server port. Defaults to `443`.
+	 */
 	port?: number;
+	/**
+	 * The path where your self-hosted PeerServer is running. Defaults to `'/'`
+	 */
 	path?: string;
+	/**
+	 * API key for the PeerServer.
+	 * This is not used anymore.
+	 * @deprecated
+	 */
 	key?: string;
 	token?: string;
+	/**
+	 * Configuration hash passed to RTCPeerConnection.
+	 * This hash contains any custom ICE/TURN server configuration.
+	 *
+	 * Defaults to {@apilink util.defaultConfig}
+	 */
 	config?: any;
+	/**
+	 * Set to true `true` if you're using TLS.
+	 * :::danger
+	 * If possible *always use TLS*
+	 * :::
+	 */
 	secure?: boolean;
 	pingInterval?: number;
 	referrerPolicy?: ReferrerPolicy;
 	logFunction?: (logLevel: LogLevel, ...rest: any[]) => void;
 }
 
+class PeerError extends Error {
+	constructor(type: PeerErrorType, err: Error | string) {
+		if (typeof err === "string") {
+			super(err);
+		} else {
+			super();
+			Object.assign(this, err);
+		}
+
+		this.type = type;
+	}
+
+	type: PeerErrorType;
+}
+export type { PeerError };
+
 export type PeerEvents = {
 	/**
 	 * Emitted when a connection to the PeerServer is established.
+	 *
+	 * You may use the peer before this is emitted, but messages to the server will be queued. <code>id</code> is the brokering ID of the peer (which was either provided in the constructor or assigned by the server).<span class='tip'>You should not wait for this event before connecting to other peers if connection speed is important.</span>
 	 */
 	open: (id: string) => void;
 	/**
@@ -55,8 +103,10 @@ export type PeerEvents = {
 	disconnected: (currentId: string) => void;
 	/**
 	 * Errors on the peer are almost always fatal and will destroy the peer.
+	 *
+	 * Errors from the underlying socket and PeerConnections are forwarded here.
 	 */
-	error: (error: Error) => void;
+	error: (error: PeerError) => void;
 };
 /**
  * A peer who can initiate connections with other peers.
@@ -82,6 +132,9 @@ export class Peer extends EventEmitter<PeerEvents> {
 	private readonly _lostMessages: Map<string, ServerMessage[]> = new Map(); // src => [list of messages]
 	/**
 	 * The brokering ID of this peer
+	 *
+	 * If no ID was specified in {@apilink Peer | the constructor},
+	 * this will be `undefined` until the {@apilink PeerEvents | `open`} event is emitted.
 	 */
 	get id() {
 		return this._id;
@@ -142,6 +195,7 @@ export class Peer extends EventEmitter<PeerEvents> {
 	 * A peer can connect to other peers and listen for connections.
 	 * @param id Other peers can connect to this peer using the provided ID.
 	 *     If no ID is given, one will be generated by the brokering server.
+	 * The ID must start and end with an alphanumeric character (lower or upper case character or a digit). In the middle of the ID spaces, dashes (-) and underscores (_) are allowed. Use {@apilink PeerOptions.metadata } to send identifying information.
 	 * @param options for specifying details about PeerServer
 	 */
 	constructor(id: string, options?: PeerOptions);
@@ -410,7 +464,7 @@ export class Peer extends EventEmitter<PeerEvents> {
 
 	/**
 	 * Connects to the remote peer specified by id and returns a data connection.
-	 * @param peer The brokering ID of the remote peer (their peer.id).
+	 * @param peer The brokering ID of the remote peer (their {@apilink Peer.id}).
 	 * @param options for specifying details about Peer Connection
 	 */
 	connect(peer: string, options: PeerConnectOption = {}): DataConnection {
@@ -549,24 +603,18 @@ export class Peer extends EventEmitter<PeerEvents> {
 	emitError(type: PeerErrorType, err: string | Error): void {
 		logger.error("Error:", err);
 
-		let error: Error & { type?: PeerErrorType };
-
-		if (typeof err === "string") {
-			error = new Error(err);
-		} else {
-			error = err as Error;
-		}
-
-		error.type = type;
-
-		this.emit("error", error);
+		this.emit("error", new PeerError(type, err));
 	}
 
 	/**
 	 * Destroys the Peer: closes all active connections as well as the connection
-	 *  to the server.
-	 * Warning: The peer can no longer create or accept connections after being
-	 *  destroyed.
+	 * to the server.
+	 *
+	 * :::caution
+	 * This cannot be undone; the respective peer object will no longer be able
+	 * to create or receive any connections, its ID will be forfeited on the server,
+	 * and all of its data and media connections will be closed.
+	 * :::
 	 */
 	destroy(): void {
 		if (this.destroyed) {
@@ -630,7 +678,13 @@ export class Peer extends EventEmitter<PeerEvents> {
 		this.emit("disconnected", currentId);
 	}
 
-	/** Attempts to reconnect with the same ID. */
+	/** Attempts to reconnect with the same ID.
+	 *
+	 * Only {@apilink Peer.disconnect | disconnected peers} can be reconnected.
+	 * Destroyed peers cannot be reconnected.
+	 * If the connection fails (as an example, if the peer's old ID is now taken),
+	 * the peer's existing connections will not close, but any associated errors events will fire.
+	 */
 	reconnect(): void {
 		if (this.disconnected && !this.destroyed) {
 			logger.log(