@klastra/ksync
Version:
Real-time sync engine for modern applications with 300k+ ops/sec performance
502 lines (383 loc) • 14.4 kB
Markdown
# 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.
[](https://www.typescriptlang.org/)
[](#performance-benchmarks)
[](#performance-benchmarks)
[](#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.**