partialmesh

A WebRTC peer-to-peer networking library that connects your app to multiple peers automatically, without connecting to all of them.

Instead of a full mesh (where every peer connects to every other peer), PartialMesh connects each peer to a configured subset of peers. This scales better and uses less bandwidth.

What It Does

• Auto-discovers peers through a signaling server
• Auto-connects to peers that join the same session
• Manages connections so you don't exceed your limits (min/max peers)
• Sends data directly between peers via WebRTC (no server relay)
• Works in browsers with a simple JavaScript API

Think of it as: "I want to connect to a few peers at a time, not try to connect to everyone"

Features

• 🌐 Partial Mesh Topology - Connect to a subset of peers, not all of them
• 🔍 Auto-Discovery - Find peers automatically through signaling
• 🔗 Auto-Connect - Establish connections without manual work
• ⚙️ Configurable Limits - Set min/max peer connections per client
• 📡 UniWRTC Signaling - Uses UniWRTC for peer discovery
• 🎯 Simple API - Just 5 methods to learn
• 📦 TypeScript Support - Full type definitions included

Installation

npm install partialmesh

Try It Now (3 Steps)

First, build the library:

npm install
npm run build

Option 1: Run the Vue3 Example (Easiest)

1. Terminal 1 - Run the example:

   cd examples/vue3
   npm install
   npm run dev

2. Open http://localhost:5173 in your browser, click "Start", then open the same URL in another browser tab. Watch peers connect automatically.

Option 2: Use in Your Own Code

The library connects to wss://signal.peer.ooo by default (it will use the hosted /ws?room=<sessionId> endpoint under the hood).

import { PartialMesh } from 'partialmesh';

const mesh = new PartialMesh({
  signalingServer: 'wss://signal.peer.ooo',
  sessionId: 'my-app',
  minPeers: 2,
  maxPeers: 10,
  autoDiscover: true,
  autoConnect: true
});

mesh.on('peer:connected', (peerId) => {
  console.log('Connected to peer:', peerId);
});

await mesh.init();
mesh.broadcast('Hello peers!');

Full Quick Start

import { PartialMesh } from 'partialmesh';

// Create a mesh instance with auto-discovery and auto-connect
const mesh = new PartialMesh({
  signalingServer: 'wss://signal.peer.ooo',
  sessionId: 'my-session',
  minPeers: 2,        // Maintain at least 2 peer connections
  maxPeers: 10,       // Don't exceed 10 peer connections for this client
  autoDiscover: true, // Automatically discover peers
  autoConnect: true   // Automatically connect to discovered peers
});

// Set up event handlers
mesh.on('signaling:connected', (data) => {
  console.log('Connected to signaling server:', data.clientId);
});

mesh.on('peer:connected', (peerId) => {
  console.log('Connected to peer:', peerId);
});

mesh.on('peer:data', ({ peerId, data }) => {
  console.log('Received data from', peerId, ':', data.toString());
});

mesh.on('mesh:ready', () => {
  console.log('Mesh is ready! Minimum peers connected.');
});

// Initialize and connect
await mesh.init();

// Send data to a specific peer
mesh.send(peerId, 'Hello, peer!');

// Broadcast to all connected peers
mesh.broadcast('Hello, everyone!');

Configuration Options

interface PartialMeshConfig {
  /** UniWRTC signaling server URL (default: 'wss://signal.peer.ooo') */
  signalingServer?: string;
  
  /** Session/room ID for peer discovery (default: 'default-session') */
  sessionId?: string;
  
  /** Minimum number of peers to maintain (default: 2) */
  minPeers?: number;
  
  /** Maximum number of peer connections this client will maintain (default: 10) */
  maxPeers?: number;
  
  /** Automatically discover peers (default: true) */
  autoDiscover?: boolean;
  
  /** Automatically connect to discovered peers (default: true) */
  autoConnect?: boolean;
  
  /** ICE servers for STUN/TURN (default: Google STUN) */
  iceServers?: RTCIceServer[];
}

API Reference

Methods

• init() - Initialize and connect to the signaling server
• connectToPeer(peerId) - Manually connect to a specific peer
• disconnectFromPeer(peerId) - Disconnect from a specific peer
• send(peerId, data) - Send data to a specific peer
• broadcast(data) - Send data to all connected peers
• getConnectedPeers() - Get array of connected peer IDs
• getDiscoveredPeers() - Get array of discovered peer IDs
• getPeerCount() - Get count of connected peers
• getClientId() - Get this client's ID
• on(event, handler) - Register event handler
• off(event, handler) - Unregister event handler
• destroy() - Disconnect from all peers and signaling server

Events

• signaling:connected - Connected to signaling server
• signaling:disconnected - Disconnected from signaling server
• signaling:error - Signaling error occurred
• peer:discovered - New peer discovered
• peer:connected - Connected to a peer
• peer:disconnected - Disconnected from a peer
• peer:data - Received data from a peer
• peer:error - Peer connection error
• mesh:ready - Minimum peers connected

Examples

The repository includes interactive examples to test peer-to-peer connections. Both examples use the default signaling server at wss://signal.peer.ooo.

Vue3 Example (Start Here)

The simplest way to test PartialMesh. Automatically connects to peers using the default signaling server.

Steps:

1. Open a new terminal and run:

   cd examples/vue3
   npm install
   npm run dev

2. Open http://localhost:5173 in your browser
3. Click the "Start" button to join the mesh
4. Open http://localhost:5173 in another browser tab
5. Watch as the two peers automatically discover and connect to each other
6. Open more tabs to see the mesh grow

What you'll see:

• Connected peers count increases automatically
• Discovered peers shows all peers in the session
• Your client ID and connection status

Basic Example

Full-featured control panel for manual peer management.

Steps:

1. Open a new terminal and run:

   cd examples/basic
   npm install
   npm run dev

2. Open http://localhost:5173 in your browser
3. Configure settings (or use defaults):

• Signaling Server: wss://signal.peer.ooo (default)
• Session ID: any string (groups peers together)
• Min/Max Peers: connection limits

4. Click "Connect" to join the mesh
5. Open the example in another tab
6. Manually control connections from the UI

Features:

• See all discovered peers
• Manually connect/disconnect from specific peers
• Send messages to individual peers or broadcast to all
• Real-time event log

How It Works

1. Signaling: Uses UniWRTC WebSocket signaling server for peer discovery and WebRTC negotiation
2. Discovery: When you join a session, the signaling server notifies you of existing peers and notifies them of you
3. Connection: With autoConnect: true, PartialMesh automatically initiates WebRTC connections
4. Maintenance: The library maintains your configured min/max peer limits, connecting to new peers or disconnecting as needed
5. Communication: Once connected, peers can send data directly to each other via WebRTC data channels

Architecture

┌─────────────┐         ┌─────────────┐         ┌─────────────┐
│   Peer A    │◄───────►│   UniWRTC   │◄───────►│   Peer B    │
│             │         │  Signaling  │         │             │
└──────┬──────┘         │   Server    │         └──────┬──────┘
       │                └─────────────┘                │
       │                                               │
       │          WebRTC Data Channel                  │
       └───────────────────────────────────────────────┘

Requirements

• Node.js 14+ or modern browser with WebRTC support
• UniWRTC signaling server (included as dependency)

License

ISC

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Related Projects

• UniWRTC - Universal WebRTC signaling service
• simple-peer - Simple WebRTC video, voice, and data channels