Getting Started with tsMesh

A type-safe, distributed RPC framework with automatic service discovery and MessagePack compression.

Quick Start (5 minutes)

1. Install Dependencies

npm install

2. Run the Example

npm run example

This starts:

• Gateway (port 4000) - Service discovery & routing
• 3 Services - User, Post, Comment (self-registering)
• Client - Makes RPC calls through gateway

Expected output:

✓ All tests completed!
✓ All requests routed through single gateway endpoint
✓ Services discovered automatically by gateway

Basic Usage

1. Define Service Interface

export interface IUserService {
  getById(params: { id: number }): Promise<User>
  listAll(params: {}): Promise<User[]>
  create(params: { name: string; email: string }): Promise<User>
}

2. Implement Service

class UserService {
  async getById(params: { id: number }) { /* ... */ }
  async listAll() { /* ... */ }
  async create(params: { name: string; email: string }) { /* ... */ }
}

3. Start Service (Self-Registers)

const service = new UserService()
await startService('user', service)
// Service now registered with gateway on ws://localhost:4000

4. Use from Client

const transport = new BinaryWebSocketRpcTransport('ws://localhost:4000')
const userService = createUserServiceProxy<IUserService>(transport)

// Type-safe, remote call feels local
const user = await userService.getById({ id: 1 })
console.log(user) // { id: 1, name: 'Alice', email: '...' }

Project Structure

tsMesh/
├── packages/
│   ├── transports/      # Wire protocol (WebSocket + MessagePack)
│   ├── runtime/         # Proxy system & service factories
│   └── gateway/         # Service discovery & routing
├── examples/
│   └── advanced/        # Full working example with 3 services
├── docs/                # Architecture documentation with Mermaid diagrams
└── README.md

What's Included

• ✅ Type-Safe Proxies - Full IDE autocomplete
• ✅ Binary Compression - MessagePack on the wire (30% smaller)
• ✅ Auto Discovery - Services self-register
• ✅ Zero Config - No YAML, no protobuf
• ✅ Middleware - Retry, logging, caching support
• ✅ Pure TypeScript - No code generation needed

Packages

@tsmesh/transports

Wire protocol and serialization layer.

• BinaryWebSocketRpcTransport - WebSocket + MessagePack
• MiddlewareTransport - Middleware pipeline
• RetryMiddleware - Exponential backoff retry

@tsmesh/runtime

Type-safe proxy system and factories.

• ServiceProxy - Method interception
• ServiceAdapter - Service introspection
• ServiceClient - Service registration
• createServiceProxyFactory - Generic proxy generation
• startService - Simplified startup

@tsmesh/gateway

Service discovery and routing.

• ServiceGateway - In-memory registry
• WebSocketGatewayServer - WebSocket listener

Architecture

Client (Type-Safe Proxy)
    ↓ (Binary MessagePack)
Gateway (Service Discovery & Routing)
    ↓ (Binary MessagePack)
Services (Self-Registering)

Each service:

1. Implements methods as async functions
2. Calls startService('name', instance) to register
3. Gateway automatically routes name.method calls to it

Each client:

1. Creates proxy from transport
2. Makes type-safe calls
3. Gateway routes to correct service automatically

Common Patterns

Multiple Services

// Each service registers independently
await startService('user', new UserService())
await startService('post', new PostService())
await startService('comment', new CommentService())

// Client uses all transparently
const users = await userProxy.listAll({})
const posts = await postProxy.listAll({})
const comments = await commentProxy.listAll({})

With Retry & Logging

const transport = new MiddlewareTransport(baseTransport, [
  new RetryMiddleware(3, 1000, 10000),  // 3 retries with backoff
  new LoggingMiddleware()                // Log all calls
])

const userService = createUserServiceProxy(transport)
const user = await userService.getById({ id: 1 })  // Auto-retried if fails

Documentation

For deep dive into architecture:

• docs/ARCHITECTURE.md - System design & patterns
• docs/TRANSPORTS.md - Wire protocol & middleware
• docs/RUNTIME.md - Proxy pattern & type safety
• docs/GATEWAY.md - Service discovery & routing

Build

# Build all packages
npm run build

# Run example
npm run example

# Run tests (if configured)
npm test

Next Steps

1. See it work: npm run example
2. Read architecture: docs/ARCHITECTURE.md
3. Explore examples: examples/advanced/
4. Build your service: Copy pattern from examples

Performance

• Serialization: MessagePack 30% smaller than JSON
• Gateway routing: O(1) hash lookup, <0.5ms per request
• Throughput: 1000+ RPS per core
• Latency: ~2-3ms overhead + network + service time

License

MIT