Zodiac API Documentation - v0.0.3

Zodiac

Type-safe WebSocket messaging with Zod validation. A lean, modern library for real-time communication.

Features

🔒 Type Safety: Full TypeScript support with automatic type inference
✅ Runtime Validation: Powered by Zod schemas for data integrity
🌐 Universal: Works in both browser and Node.js environments
🎯 Simple API: Clean, intuitive message handling with on/off methods
🔄 Multiple Transports: WebSocket, WebRTC P2P data channels
🚀 Zero Dependencies: Only depends on Zod for validation
📦 Lightweight: Minimal bundle size with tree-shaking support

Quick Start

npm install @xtr-dev/zodiac zod

Define Messages

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

// Define type-safe messages
const userMessage = defineMessage('user-message', z.object({
  name: z.string(),
  message: z.string(),
  timestamp: z.number().optional()
}));

const chatJoin = defineMessage('chat-join', z.object({
  userId: z.string(),
  username: z.string()
}));

Browser Usage

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

const channel = new BrowserChannel();

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

channel.on(chatJoin, (data) => {
  console.log(`${data.username} joined!`);
});

// Connect and send messages
await channel.connect('wss://your-websocket-server.com');

// Send with automatic validation
await channel.sendMessage(userMessage, {
  name: 'Alice',
  message: 'Hello everyone!',
  timestamp: Date.now()
});

Node.js Usage

import { NodeChannel } from '@xtr-dev/zodiac';

const channel = new NodeChannel();

// Same API as browser
channel.on(userMessage, async (data) => {
  console.log(`Received: ${data.message}`);
  
  // Echo back
  await channel.sendMessage(userMessage, {
    name: 'Server',
    message: `Echo: ${data.message}`
  });
});

await channel.connect('ws://localhost:8080');

Zodiac also supports WebRTC peer-to-peer communication with PeerChannel for direct browser-to-browser messaging. See the API documentation for details.

Interactive Demo

Try the live HTML demo to see Zodiac in action:

git clone <this-repo>
cd zodiac
npm install
npm run example

This starts both a WebSocket todo server and opens an interactive demo where you can:

Experience multi-user real-time todo list synchronization
Send type-safe todo operations with validation
Test collaborative todo management
Open multiple tabs for multi-user testing
See TypeScript types and validation in action

Validation & Type Safety

Zodiac provides both compile-time and runtime safety:

const userMsg = defineMessage('user', z.object({
  name: z.string(),
  age: z.number()
}));

// ✅ TypeScript knows the exact shape
channel.on(userMsg, (data) => {
  console.log(data.name); // string
  console.log(data.age);  // number
});

// ✅ Runtime validation prevents invalid data
await channel.sendMessage(userMsg, {
  name: 'Alice',
  age: 'invalid' // ❌ Throws validation error
});

API Reference

`defineMessage(id, schema)`

Creates a type-safe message definition with validation schema:

const myMessage = defineMessage('my-message', z.object({
  content: z.string(),
  priority: z.enum(['low', 'high'])
}));

// Returns: { id: string, schema: ZodSchema, messageSchema: ZodObject }

Channel Methods

All channels (BrowserChannel, NodeChannel, PeerChannel) share the same core API:

channel.on(definition, handler) - Listen for messages with full type safety
channel.off(definition, handler) - Remove message listeners
channel.sendMessage(definition, data) - Send validated messages
channel.connect(url) - Establish connection
channel.disconnect() - Close connection
channel.isOpen() - Check connection status

See the full API documentation for complete details.

📖 Documentation

API Documentation - Complete TypeDoc-generated API docs
Examples - Live demos and usage examples
Local docs: Run npm run docs to generate docs locally

Generate and serve docs locally:

npm run docs        # Generate documentation
npm run docs:serve  # Serve docs at http://localhost:8080