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.

✨ 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

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

Basic Usage

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)

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

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

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:

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

# 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

// 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

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:

// 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:

# 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

# 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

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)

const ksync = new KSync({ serverUrl: 'ws://localhost:8080' });
await ksync.initialize();

New Way (recommended)

const ksync = createKSync({ serverUrl: 'ws://localhost:8080' });
// No initialization needed - connects automatically!

Using Factory Functions

// 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

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

📄 License

MIT License - see LICENSE file for details.

🔗 Links

• GitHub Repository
• Documentation
• Examples
• Benchmarks

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