Installation

Install kSync v0.2 and set up your development environment

Prerequisites

Before installing kSync v0.2, make sure you have:

Node.js 18+

kSync v0.2 requires Node.js 18 or higher for modern JavaScript features

TypeScript (Recommended)

TypeScript provides excellent IntelliSense with 50+ configuration options

Package Installation

npm

npm install @klastra/ksync

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

Quick Start (30 seconds)

Get running instantly with factory functions:

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

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

// Send events
await ksync.send('message', { text: 'Hello world!' });

// Listen for events
ksync.on('message', (data) => console.log(data.text));

TypeScript Configuration

For the best experience with TypeScript, add these settings to your tsconfig.json:

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "node",
    "allowSyntheticDefaultImports": true,
    "esModuleInterop": true,
    "strict": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "jsx": "react-jsx"  // For React integration
  }
}

Environment Setup

Browser Environment

For browser applications, kSync v0.2 automatically configures optimal settings:

• IndexedDB for local storage with memory fallback
• Web Locks API for tab coordination
• WebSocket for real-time sync
• Smart batching for performance

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

// Browser-optimized configuration
const ksync = createKSync({
  serverUrl: 'ws://localhost:8080', // Your WebSocket server
  // Storage automatically uses IndexedDB
});

Node.js Environment

For server-side or Node.js applications:

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

// Server-optimized configuration
const ksync = createKSync({
  storage: { type: 'memory' }, // Memory storage for servers
  sync: { enabled: false },    // Disable sync on server
});

Bun Environment

kSync v0.2 is optimized for Bun and works perfectly:

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

const ksync = createKSync({
  serverUrl: 'ws://localhost:8080',
  performance: { 
    batchSize: 200,  // Leverage Bun's performance
    batchDelay: 5    // Ultra-low latency
  }
});

Factory Functions

kSync v0.2 provides optimized presets for common use cases:

Chat Application

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

// Optimized for chat with presence
const chat = createChat('room-name', {
  serverUrl: 'ws://localhost:8080'
});

await chat.setPresence({ 
  status: 'online', 
  metadata: { name: 'Alice' } 
});

Development Server Setup

Option 1: Use Built-in Server

kSync v0.2 includes a production-ready WebSocket server:

# Clone for development
git clone https://github.com/0ni-x4/ksync.git
cd ksync

# Install dependencies
npm install

# Start the development server
npm run server

Option 2: Custom Server

Create your own high-performance WebSocket server:

Simple Server

import { WebSocketServer } from 'ws';

const wss = new WebSocketServer({ port: 8080 });
console.log('🚀 kSync server running on ws://localhost:8080');

wss.on('connection', (ws) => {
  console.log('📱 Client connected');

  ws.on('message', (data) => {
    // Broadcast to all other clients
    wss.clients.forEach((client) => {
      if (client !== ws && client.readyState === 1) {
        client.send(data);
      }
    });
  });
});

Performance Optimization

kSync v0.2 is production-ready with enterprise performance:

Production Configuration

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

const ksync = createKSync({
  // High-performance settings
  performance: {
    batchSize: 200,              // Higher throughput
    batchDelay: 5,               // Low latency
    materializationCaching: true, // Cache computed state
    compressionThreshold: 1024   // Compress large payloads
  },
  
  // Production features
  auth: {
    token: process.env.JWT_TOKEN,
    type: 'bearer'
  },
  
  // Monitoring
  debug: {
    events: false,         // Disable in production
    performance: true,     // Monitor metrics
    sync: false,
    storage: false
  },
  
  // Scaling
  offline: {
    queueSize: 10000,      // Large offline queue
    persistence: true      // Persist across restarts
  }
});

What’s Next?

Quick Start Guide

Build your first real-time app in 2 minutes

Factory Functions

Learn about optimized presets for different use cases

Performance Benchmarks

See detailed performance metrics and optimization tips

API Reference

Explore all 50+ configuration options and methods

---

kSync v0.2: Enterprise performance with developer-friendly APIs.