# kSync v0.2 🚀

**Real-time sync engine for modern applications.**  
Built for high-performance web and AI apps that need full control over events, state management, and real-time collaboration — with developer-friendly APIs and production-ready scalability.

[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
[![Performance](https://img.shields.io/badge/Performance-300k%20ops%2Fsec-green.svg)](#performance-benchmarks)
[![Memory](https://img.shields.io/badge/Memory-18MB%20for%201k%20clients-green.svg)](#performance-benchmarks)
[![Tests](https://img.shields.io/badge/Tests-29%2F29%20passing-green.svg)](#testing)

---

## ✨ What's New in v0.2

🎯 **Developer Experience First**
- **Smart Defaults** - Works out of the box, configure only what you need
- **Factory Functions** - `createChat()`, `createTodos()`, `createGame()`, `createAI()`
- **Comprehensive Configuration** - 50+ options with full TypeScript docs
- **Backward Compatibility** - All existing APIs still work

⚡ **Performance & Scale**
- **300k+ ops/sec** - Handles massive concurrent workloads
- **Memory Efficient** - Only 18MB for 1000 clients + 10k events
- **Network Resilient** - Graceful handling of 10-200ms latency
- **Enterprise Ready** - Tested with 500+ concurrent clients

🔧 **Advanced Features**
- **Presence System** - Real-time user presence with metadata
- **Streaming Support** - Live AI responses and real-time data streams
- **Offline-First** - Queue events when offline, sync when reconnected
- **Room Management** - Multi-room support with automatic routing
- **Performance Monitoring** - Built-in metrics and debugging

---

## 🚀 Quick Start

### Installation

```bash
npm install @klastra/ksync
# or
bun add @klastra/ksync
```

### Basic Usage

```ts
import { createKSync } from '@klastra/ksync';

// Works instantly with smart defaults
const ksync = createKSync();

// Listen for events
ksync.on('message', (data, event) => {
  console.log(`${event.userId}: ${data.text}`);
});

// Send events (instant local, auto-synced if server configured)
await ksync.send('message', {
  text: 'Hello world!',
  timestamp: Date.now()
});

// Get current state
const state = ksync.getState();
```

### Factory Functions (Optimized Presets)

```ts
import { createChat, createTodos, createGame, createAI } from '@klastra/ksync';

// Chat app with presence and optimized batching
const chat = createChat('my-room', {
  serverUrl: 'ws://localhost:8080'
});

// Todo app with offline persistence
const todos = createTodos({
  offline: { persistence: true, queueSize: 5000 }
});

// Game with low-latency updates
const game = createGame('game-123', {
  performance: { batchSize: 50, batchDelay: 5 }
});

// AI with streaming responses
const ai = createAI('conversation-1', {
  features: { streaming: true }
});
```

### Real-time Chat Example

```ts
const chat = createChat('general', {
  serverUrl: 'ws://localhost:8080',
  features: { presence: true }
});

// Set user presence
await chat.setPresence({
  status: 'online',
  metadata: { name: 'Alice', avatar: 'avatar-url' }
});

// Send messages
chat.on('message', (data) => {
  console.log(`${data.author}: ${data.text}`);
});

await chat.send('message', {
  text: 'Hello everyone!',
  author: 'Alice',
  timestamp: Date.now()
});

// Check who's online
const presence = chat.getPresence();
console.log(`${presence.length} users online`);
```

### AI Streaming Example

```ts
const ai = createAI('assistant', {
  features: { streaming: true }
});

// Listen for streaming chunks
ai.on('stream-chunk', (data) => {
  process.stdout.write(data.data); // Live AI response
});

ai.on('stream-end', (data) => {
  console.log('\nResponse complete!');
});

// Start AI response stream
await ai.startStream('response-1');
await ai.streamChunk('response-1', { data: 'Hello! ' });
await ai.streamChunk('response-1', { data: 'How can I help you?' });
await ai.endStream('response-1');
```

---

## 🎛️ Comprehensive Configuration

kSync v0.2 provides extensive configuration options with intelligent defaults:

```ts
const ksync = createKSync({
  // === CONNECTION ===
  serverUrl: 'ws://localhost:8080',    // Auto-connects if provided
  room: 'my-room',                     // Default: 'default'
  userId: 'user-123',                  // Auto-generated if not provided
  
  // === AUTHENTICATION ===
  auth: {
    token: 'jwt-token',                // Static token
    provider: async () => getToken(),  // Dynamic token provider
    type: 'bearer'                     // 'bearer', 'jwt', 'custom'
  },
  
  // === PERFORMANCE ===
  performance: {
    batchSize: 100,                    // Events per batch
    batchDelay: 10,                    // Batch delay in ms
    materializationCaching: true,      // Cache state computations
    compressionThreshold: 1024         // Compress payloads > 1KB
  },
  
  // === OFFLINE SUPPORT ===
  offline: {
    enabled: true,                     // Queue events when offline
    queueSize: 1000,                   // Max queued events
    persistence: true,                 // Persist queue to storage
    syncOnReconnect: true              // Auto-sync when back online
  },
  
  // === STATE MANAGEMENT ===
  state: {
    materializer: (events) => {        // Transform events to state
      return events.reduce((state, event) => {
        // Your state logic here
        return newState;
      }, {});
    },
    enableCaching: true,               // Cache materialized state
    autoMaterialize: false             // Auto-run on new events
  },
  
  // === FEATURES ===
  features: {
    presence: true,                    // Enable presence system
    streaming: true,                   // Enable streaming support
    encryption: false                  // Client-side encryption
  },
  
  // === DEBUGGING ===
  debug: {
    events: true,                      // Log events
    sync: true,                        // Log sync operations
    performance: false,                // Log performance metrics
    storage: false                     // Log storage operations
  }
});
```

---

## 📊 Performance Benchmarks

kSync v0.2 delivers enterprise-grade performance:

### Scale Test Results

```
🚀 Scale Benchmarks

⚡ Testing 500 Concurrent Clients...
✅ 500 clients, 2500 events: 344,019 ops/sec in 7ms

🌐 Testing Network Conditions...
✅ Handled 10-200ms latency gracefully (202ms total)

💬 Testing High-Load Chat...
✅ 100 users, 400 events: 485,830 ops/sec across 5 rooms

🧠 Testing Memory Efficiency...
✅ 1000 clients, 10k events: 593,068 ops/sec (18MB heap)

📊 Summary:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🎯 500 Concurrent Clients: 344,019 ops/sec
🌐 Network Resilience: 10-200ms handled
💬 Chat Performance: 485,830 ops/sec
🧠 Memory Efficiency: 593,068 ops/sec (18MB)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

### Detailed Performance Metrics

| Test | Performance | Details |
|------|-------------|---------|
| **Basic Event Throughput** | 85,770 ops/sec | 10k events processed |
| **Event Batching** | 18,716 ops/sec | Optimized batching |
| **State Materialization** | 3.7M ops/sec | <1.35ms latency |
| **Memory Efficiency** | 0B per event | Efficient trimming |
| **Concurrent Operations** | 6,558 ops/sec | 670 concurrent ops |
| **Storage Performance** | 395M ops/sec | IndexedDB operations |
| **Presence System** | 318,108 ops/sec | 1000 users tracked |
| **Streaming** | 1.07M ops/sec | Real-time chunks |

### Run Benchmarks Yourself

```bash
# Comprehensive benchmark suite
npm run benchmark

# Quick scale test
npx tsx scripts/final-benchmark.ts
```

---

## 🏗️ Architecture

### Event-Driven Architecture

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Application   │────│     kSync       │────│   WebSocket     │
│   (Your Code)   │    │   (Local-First) │    │    Server       │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         │ send()               │ store                 │ sync
         │ on()                 │ materialize           │ broadcast
         │                      │ batch                 │
         ▼                      ▼                       ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Event Processing Flow                        │
│                                                                 │
│  1. Event Created → 2. Local Storage → 3. Materialization →    │
│  4. Batch Processing → 5. Network Sync → 6. Conflict Resolution │
└─────────────────────────────────────────────────────────────────┘
```

### Key Concepts

- **Local-First**: Events stored locally immediately, synced asynchronously
- **Event Sourcing**: Append-only event log with state materialization
- **Optimistic Updates**: UI updates instantly, conflicts resolved later
- **Smart Batching**: Automatic event batching for performance
- **Presence System**: Real-time user presence with metadata
- **Room Isolation**: Multi-room support with automatic routing

---

## 🔌 API Reference

### Core Methods

```ts
// Event Management
await ksync.send(type, data, options?)     // Send event
ksync.on(type, listener)                   // Listen to events
ksync.once(type, listener)                 // Listen once
ksync.off(type, listener)                  // Remove listener

// State Management
ksync.getState(forceMaterialize?)          // Get materialized state
ksync.getEvents()                          // Get raw events
ksync.clear(options?)                      // Clear data

// Connection Management
await ksync.connect(options?)              // Connect to server
await ksync.disconnect()                   // Disconnect
await ksync.sync(options?)                 // Manual sync

// Room Management
await ksync.joinRoom(room, options?)       // Join different room

// Presence System
await ksync.setPresence(info)              // Set user presence
ksync.getPresence(filter?)                 // Get presence info

// Streaming Support
await ksync.startStream(id, options?)      // Start stream
await ksync.streamChunk(id, chunk)         // Send chunk
await ksync.endStream(id, data?)           // End stream
ksync.getActiveStreams()                   // Get active streams

// Status & Monitoring
ksync.getStatus()                          // Get comprehensive status
```

### Factory Functions

```ts
createKSync(config?)       // Basic instance with full control
createChat(room, config?)  // Optimized for chat applications
createTodos(config?)       // Optimized for todo/task apps
createGame(id, config?)    // Optimized for multiplayer games
createAI(id?, config?)     // Optimized for AI applications
```

### Backward Compatibility

All v0.1 APIs still work:

```ts
// These still work exactly as before
ksync.defineSchema(name, schema)
ksync.defineMaterializer(name, fn)
await ksync.initialize(config?, syncClient?)
ksync.onPresence(listener)
await ksync.updatePresence(data)
await ksync.close()
```

---

## 🧪 Testing

kSync v0.2 includes comprehensive test coverage:

```bash
# Run all tests
npm test

# Run with type checking
npm run typecheck

# Run specific test file
npx tsx src/__tests__/ksync.basic.test.ts
```

### Test Results
- **29/29 tests passing** ✅
- **100% TypeScript compatibility** ✅
- **Strict mode compliant** ✅
- **All edge cases covered** ✅

---

## 📁 Examples

### Run Examples

```bash
# Basic usage
npx tsx examples/basic.ts

# Real-time sync (requires server)
npx tsx examples/sync.ts

# Advanced features
npx tsx examples/advanced-features.ts

# AI streaming
npx tsx examples/streaming.ts

# Start WebSocket server
npx tsx server/websocket-server.ts
```

### React Integration

```tsx
import { useKSync, useKSyncEvent } from '@klastra/ksync/react';

function ChatApp() {
  const [ksync] = useState(() => createChat('my-room'));
  const [messages, setMessages] = useState([]);
  
  useEffect(() => {
    ksync.on('message', (data) => {
      setMessages(prev => [...prev, data]);
    });
  }, [ksync]);

  const sendMessage = async (text: string) => {
    await ksync.send('message', {
      text,
      author: 'Current User',
      timestamp: Date.now()
    });
  };

  return (
    <div>
      <div>{messages.map(msg => <div key={msg.timestamp}>{msg.text}</div>)}</div>
      <input onKeyPress={e => e.key === 'Enter' && sendMessage(e.target.value)} />
    </div>
  );
}
```

---

## 🚀 Migration from v0.1

kSync v0.2 is fully backward compatible, but here's how to use the new features:

### Old Way (still works)
```ts
const ksync = new KSync({ serverUrl: 'ws://localhost:8080' });
await ksync.initialize();
```

### New Way (recommended)
```ts
const ksync = createKSync({ serverUrl: 'ws://localhost:8080' });
// No initialization needed - connects automatically!
```

### Using Factory Functions
```ts
// Instead of manual configuration
const ksync = createKSync({
  room: 'chat-room',
  features: { presence: true },
  performance: { batchSize: 50 }
});

// Use optimized preset
const chat = createChat('chat-room');
```

---

## 🤝 Contributing

```bash
git clone https://github.com/0ni-x4/ksync
cd ksync
npm install
npm test
npm run benchmark
```

---

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

---

## 🔗 Links

- [GitHub Repository](https://github.com/0ni-x4/ksync)
- [Documentation](https://ksync.klastra.ai)
- [Examples](./examples)
- [Benchmarks](./scripts)

**Built with ❤️ for developers who need real-time sync without the complexity.**