Zodiac API Documentation - v0.0.3

Zodiac - Type-safe WebSocket and WebRTC messaging

Zodiac provides type-safe, validated messaging for real-time applications using WebSockets, WebRTC peer-to-peer connections, with full TypeScript support and Zod validation.

Quick Start

import { defineMessage, BrowserChannel, z } from '@xtr-dev/zodiac';

// Define a message type
const userMessage = defineMessage('user-message', z.object({
  name: z.string(),
  message: z.string()
}));

// Create and connect channel
const channel = new BrowserChannel();
await channel.connect('ws://localhost:8080');

// Listen for messages (fully typed!)
channel.on(userMessage, (data) => {
  console.log(`${data.name}: ${data.message}`);
});

// Send messages with validation
await channel.sendMessage(userMessage, {
  name: 'Alice',
  message: 'Hello world!'
});

Namespaces - Message Definition Re-exported Zod library for schema definition convenience. Use this to create validation schemas for your messages.

z

Classes - Channels WebRTC peer-to-peer data channel implementation for direct browser-to-browser communication. Enables direct messaging between browsers without requiring a server after the initial connection setup. Uses WebRTC data channels for reliable, ordered messaging with the same type-safe API as WebSocket channels. ## Overview WebRTC requires a "signaling" phase where peers exchange connection information before they can communicate directly. This class handles the WebRTC connection management, but you need to provide the signaling transport (WebSocket, Socket.IO, Firebase, etc.). ```mermaid sequenceDiagram participant A as Peer A participant S as Signaling Server participant B as Peer B A->>S: Offer S->>B: Offer B->>S: Answer S->>A: Answer A->>S: ICE Candidate S->>B: ICE Candidate B->>S: ICE Candidate S->>A: ICE Candidate Note over A,B: Direct P2P Connection Established A->>B: Type-safe messages B->>A: Type-safe messages ```

PeerChannel

Classes - Channels WebSocket channel implementation optimized for Node.js environments. Provides reliable WebSocket communication for server-side applications, with automatic reconnection, robust error handling, and full type-safety. Uses the popular 'ws' library for enhanced Node.js WebSocket support. ## Key Differences from BrowserChannel - Server Optimized: Better performance and memory usage for Node.js - Enhanced Error Handling: More detailed error information and callbacks - Callback-based Sending: Uses Node.js callback pattern for send operations - Buffer Support: Can handle Node.js Buffer objects efficiently - Process Integration: Works well with Node.js process lifecycle ## Use Cases - Microservice Communication: Connect services via WebSocket - Bot Implementations: Build chat bots, game bots, etc. - Server-to-Server: Real-time communication between servers - CLI Applications: Interactive command-line tools with live updates - Backend Workers: Background processes that need real-time updates - API Gateways: Proxy and transform WebSocket connections ## Reconnection Behavior Identical exponential backoff strategy as BrowserChannel but optimized for server environments with better error reporting and resource cleanup.

NodeChannel

Classes - Channels WebSocket channel implementation optimized for browser environments. Provides reliable WebSocket communication with automatic reconnection, exponential backoff, and full type-safety. Designed specifically for browser JavaScript environments using the standard WebSocket API. ## Features - Automatic Reconnection: Configurable retry attempts with exponential backoff - Type Safety: Full TypeScript support with Zod validation - Error Resilience: Graceful handling of connection failures - Browser Optimized: Uses native WebSocket API for best performance - Memory Efficient: Proper cleanup and resource management ## Reconnection Behavior The channel automatically attempts to reconnect when connections are lost: ```mermaid graph TD A[Connection Lost] --> B[Wait Delay] B --> C[Attempt Reconnect] C --> D{Success?} D -->|Yes| E[Reset Counter] D -->|No| F[Increment Counter] F --> G{Max Attempts?} G -->|No| H[Double Delay] H --> B G -->|Yes| I[Give Up] ``` Default retry schedule: - Attempt 1: 1 second delay - Attempt 2: 2 second delay - Attempt 3: 4 second delay - Attempt 4: 8 second delay - Attempt 5: 16 second delay - After 5 attempts: Stop trying

BrowserChannel

Interfaces - Configuration Configuration options for WebRTC peer channels.

PeerChannelConfig

Interfaces - Configuration Message structure for WebRTC signaling between peers. These messages need to be exchanged through your signaling mechanism.

SignalingMessage

Interfaces - Types Complete message definition created by `defineMessage()`. Contains the message ID, data validation schema, and complete message validation schema.

MessageDefinition

Interfaces - Types The complete message structure sent over the wire. Contains the message ID, validated data, and optional timestamp.

Message

Type Aliases - Types Handler function for processing incoming messages of a specific type. Receives the validated data and complete message object.

MessageHandler

Type Aliases - Types Unique identifier for message types. Should be descriptive and unique across your application.

MessageId

Type Aliases - Types Utility type to extract the data type from a MessageDefinition. Useful for creating handlers and working with message data types.

InferMessageData

Functions - Message Definition

defineMessage

Classes - Channels WebRTC peer-to-peer data channel implementation for direct browser-to-browser communication. Enables direct messaging between browsers without requiring a server after the initial connection setup. Uses WebRTC data channels for reliable, ordered messaging with the same type-safe API as WebSocket channels. ## Overview WebRTC requires a "signaling" phase where peers exchange connection information before they can communicate directly. This class handles the WebRTC connection management, but you need to provide the signaling transport (WebSocket, Socket.IO, Firebase, etc.). ```mermaid sequenceDiagram participant A as Peer A participant S as Signaling Server participant B as Peer B A->>S: Offer S->>B: Offer B->>S: Answer S->>A: Answer A->>S: ICE Candidate S->>B: ICE Candidate B->>S: ICE Candidate S->>A: ICE Candidate Note over A,B: Direct P2P Connection Established A->>B: Type-safe messages B->>A: Type-safe messages ```

PeerChannel

Classes - Channels WebSocket channel implementation optimized for Node.js environments. Provides reliable WebSocket communication for server-side applications, with automatic reconnection, robust error handling, and full type-safety. Uses the popular 'ws' library for enhanced Node.js WebSocket support. ## Key Differences from BrowserChannel - **Server Optimized**: Better performance and memory usage for Node.js - **Enhanced Error Handling**: More detailed error information and callbacks - **Callback-based Sending**: Uses Node.js callback pattern for send operations - **Buffer Support**: Can handle Node.js Buffer objects efficiently - **Process Integration**: Works well with Node.js process lifecycle ## Use Cases - **Microservice Communication**: Connect services via WebSocket - **Bot Implementations**: Build chat bots, game bots, etc. - **Server-to-Server**: Real-time communication between servers - **CLI Applications**: Interactive command-line tools with live updates - **Backend Workers**: Background processes that need real-time updates - **API Gateways**: Proxy and transform WebSocket connections ## Reconnection Behavior Identical exponential backoff strategy as BrowserChannel but optimized for server environments with better error reporting and resource cleanup.

NodeChannel

Classes - Channels WebSocket channel implementation optimized for browser environments. Provides reliable WebSocket communication with automatic reconnection, exponential backoff, and full type-safety. Designed specifically for browser JavaScript environments using the standard WebSocket API. ## Features - **Automatic Reconnection**: Configurable retry attempts with exponential backoff - **Type Safety**: Full TypeScript support with Zod validation - **Error Resilience**: Graceful handling of connection failures - **Browser Optimized**: Uses native WebSocket API for best performance - **Memory Efficient**: Proper cleanup and resource management ## Reconnection Behavior The channel automatically attempts to reconnect when connections are lost: ```mermaid graph TD A[Connection Lost] --> B[Wait Delay] B --> C[Attempt Reconnect] C --> D{Success?} D -->|Yes| E[Reset Counter] D -->|No| F[Increment Counter] F --> G{Max Attempts?} G -->|No| H[Double Delay] H --> B G -->|Yes| I[Give Up] ``` Default retry schedule: - Attempt 1: 1 second delay - Attempt 2: 2 second delay - Attempt 3: 4 second delay - Attempt 4: 8 second delay - Attempt 5: 16 second delay - After 5 attempts: Stop trying

BrowserChannel