Quickstart

Installation

npm install @klastra/ksync

yarn add @klastra/ksync

pnpm add @klastra/ksync

bun add @klastra/ksync

No dependencies required! kSync v0.2 works out of the box with smart defaults. Zod is now optional for advanced schema validation.

Quick Start (30 seconds)

The fastest way to get real-time sync working:

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)

kSync v0.2 provides factory functions optimized for different use cases:

Chat Application
Multiplayer Game
AI Application
Todo Application

import { createChat } from '@klastra/ksync';

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

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

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

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

chat.on('presence-update', (data) => {
  console.log(`${data.metadata?.name} is ${data.status}`);
});

import { createGame } from '@klastra/ksync';

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

// Player actions
await game.send('player-move', {
  playerId: 'player-1',
  x: 100,
  y: 200,
  timestamp: Date.now()
});

// Real-time game state
game.on('player-move', (data) => {
  updatePlayerPosition(data.playerId, data.x, data.y);
});

// Player presence
await game.setPresence({
  status: 'playing',
  metadata: { level: 5, score: 1200 }
});

import { createAI } from '@klastra/ksync';

// AI with streaming responses
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?' });
await ai.endStream('response-1');

import { createTodos } from '@klastra/ksync';

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

// Create todo
await todos.send('todo-created', {
  id: 'todo-1',
  title: 'Buy groceries',
  completed: false,
  createdAt: Date.now()
});

// Listen for changes
todos.on('todo-created', (data) => {
  addTodoToUI(data);
});

todos.on('todo-updated', (data) => {
  updateTodoInUI(data);
});

Real-time Chat Example

Let’s build a complete chat application in under 50 lines:

import { createChat } from '@klastra/ksync';

// Create chat instance
const chat = createChat('general', {
  serverUrl: 'ws://localhost:8080',  // Optional - works offline without server
  features: { presence: true }
});

// Set user info
await chat.setPresence({
  status: 'online',
  metadata: { 
    name: 'Alice',
    avatar: 'https://api.dicebear.com/7.x/avataaars/svg?seed=Alice'
  }
});

// UI Elements (assuming HTML exists)
const messagesDiv = document.getElementById('messages');
const messageInput = document.getElementById('messageInput');
const sendButton = document.getElementById('sendButton');
const presenceDiv = document.getElementById('presence');

// Send message function
async function sendMessage() {
  const text = messageInput.value.trim();
  if (!text) return;

  await chat.send('message', {
    text,
    author: 'Alice',
    timestamp: Date.now(),
    id: `msg-${Date.now()}`
  });

  messageInput.value = '';
}

// Listen for messages
chat.on('message', (data) => {
  const messageEl = document.createElement('div');
  messageEl.innerHTML = `
    <strong>${data.author}</strong>: ${data.text}
    <small>(${new Date(data.timestamp).toLocaleTimeString()})</small>
  `;
  messagesDiv.appendChild(messageEl);
  messagesDiv.scrollTop = messagesDiv.scrollHeight;
});

// Listen for presence updates
chat.on('presence-update', (data) => {
  updatePresenceUI();
});

function updatePresenceUI() {
  const presence = chat.getPresence();
  presenceDiv.innerHTML = presence
    .map(p => `<span class="user ${p.status}">${p.metadata?.name || p.userId}</span>`)
    .join('');
}

// Event listeners
sendButton.addEventListener('click', sendMessage);
messageInput.addEventListener('keypress', (e) => {
  if (e.key === 'Enter') sendMessage();
});

// Initial presence update
updatePresenceUI();

React Integration

For React applications, kSync v0.2 provides simple state integration:

import React, { useState, useEffect } from 'react';
import { createChat } from '@klastra/ksync';

function ChatApp() {
  const [chat] = useState(() => createChat('my-room'));
  const [messages, setMessages] = useState([]);
  const [presence, setPresence] = useState([]);

  useEffect(() => {
    // Listen for messages
    chat.on('message', (data) => {
      setMessages(prev => [...prev, data]);
    });

    // Listen for presence
    chat.on('presence-update', () => {
      setPresence(chat.getPresence());
    });

    // Set initial presence
    chat.setPresence({
      status: 'online',
      metadata: { name: 'React User' }
    });

    return () => {
      chat.disconnect();
    };
  }, [chat]);

  const sendMessage = async (text: string) => {
    await chat.send('message', {
      text,
      author: 'React User',
      timestamp: Date.now(),
      id: `msg-${Date.now()}`
    });
  };

  return (
    <div>
      <div>
        <h3>Online ({presence.length})</h3>
        {presence.map(p => (
          <div key={p.userId}>{p.metadata?.name || p.userId}</div>
        ))}
      </div>
      
      <div>
        <h3>Messages</h3>
        {messages.map(msg => (
          <div key={msg.id}>
            <strong>{msg.author}</strong>: {msg.text}
          </div>
        ))}
      </div>
      
      <input 
        onKeyPress={e => e.key === 'Enter' && sendMessage(e.target.value)}
        placeholder="Type a message..."
      />
    </div>
  );
}

AI Streaming Example

Build a real-time AI chat with streaming responses:

import { createAI } from '@klastra/ksync';

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

// Simple streaming chat interface
class AIChat {
  private currentResponse = '';
  private responseElement: HTMLElement;

  constructor(responseElementId: string) {
    this.responseElement = document.getElementById(responseElementId);
    this.setupListeners();
  }

  private setupListeners() {
    // Listen for streaming chunks
    ai.on('stream-chunk', (data) => {
      this.currentResponse += data.data;
      this.responseElement.textContent = this.currentResponse;
    });

    // Response complete
    ai.on('stream-end', (data) => {
      console.log('AI response complete');
      // Save to message history, etc.
    });
  }

  async askQuestion(question: string) {
    // Clear previous response
    this.currentResponse = '';
    this.responseElement.textContent = 'AI is thinking...';

    // Simulate AI response stream
    const responseId = `response-${Date.now()}`;
    await ai.startStream(responseId);

    // Simulate streaming response (replace with real AI API)
    const words = [
      'I understand your question. ',
      'Let me think about this carefully. ',
      'Based on my knowledge, ',
      'I would recommend the following approach...'
    ];

    for (const word of words) {
      await new Promise(resolve => setTimeout(resolve, 500));
      await ai.streamChunk(responseId, { data: word });
    }

    await ai.endStream(responseId);
  }
}

// Usage
const chat = new AIChat('ai-response');
document.getElementById('ask-button').onclick = () => {
  const question = document.getElementById('question-input').value;
  chat.askQuestion(question);
};

Advanced Configuration

For production applications, you can customize kSync extensively:

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

const ksync = createKSync({
  // Connection
  serverUrl: 'wss://your-server.com/ws',
  room: 'my-app',
  userId: 'user-123',

  // Authentication
  auth: {
    token: 'your-jwt-token',
    type: 'bearer'
  },

  // Performance tuning
  performance: {
    batchSize: 200,         // Higher for throughput
    batchDelay: 5,          // Lower for real-time
    materializationCaching: true,
    compressionThreshold: 1024
  },

  // Offline support
  offline: {
    enabled: true,
    queueSize: 10000,
    persistence: true,
    syncOnReconnect: true
  },

  // Features
  features: {
    presence: true,
    streaming: true,
    encryption: false
  },

  // Production debugging
  debug: {
    events: false,      // Disable in production
    performance: true   // Monitor performance
  }
});

Next Steps

Performance Benchmarks

See how kSync delivers 600k+ ops/sec performance

API Reference

Explore all available methods and configuration options

Factory Functions Guide

Learn about optimized presets for different use cases

Production Deployment

Deploy kSync for enterprise-scale applications

You now have a real-time sync engine running in under 2 minutes! kSync v0.2’s smart defaults mean you can focus on building features, not configuring infrastructure.

Get Started

Core Features

Integration

Legacy (v0.1)

Installation

Quick Start (30 seconds)

Factory Functions (Optimized Presets)

Real-time Chat Example

React Integration

AI Streaming Example

Advanced Configuration

Next Steps

Performance Benchmarks

API Reference

Factory Functions Guide

Production Deployment

​Installation

​Quick Start (30 seconds)

​Factory Functions (Optimized Presets)

​Real-time Chat Example

​React Integration

​AI Streaming Example

​Advanced Configuration

​Next Steps

Performance Benchmarks

API Reference

Factory Functions Guide

Production Deployment

Installation

Quick Start (30 seconds)

Factory Functions (Optimized Presets)

Real-time Chat Example

React Integration

AI Streaming Example

Advanced Configuration

Next Steps