@klastra/ksync/dist/core.d.ts

Real-time sync engine for modern applications with 300k+ ops/sec performance

import { EventEmitter } from 'events';
import { KSyncEvent, KSyncStorage, KSyncSync, StreamChunk, PresenceInfo } from './types.js';
export interface KSyncConfig {
    serverUrl?: string;
    room?: string;
    userId?: string;
    clientId?: string;
    auth?: {
        token?: string;
        provider?: () => Promise<string>;
        type?: 'bearer' | 'jwt' | 'custom';
    };
    storage?: {
        type?: 'memory' | 'indexeddb' | 'file' | 'custom';
        instance?: KSyncStorage;
        options?: {
            persistEvents?: boolean;
            maxEvents?: number;
            compression?: boolean;
        };
    };
    sync?: {
        enabled?: boolean;
        client?: KSyncSync;
        mode?: 'realtime' | 'manual';
        options?: {
            autoReconnect?: boolean;
            maxReconnectAttempts?: number;
            reconnectDelay?: number;
            heartbeatInterval?: number;
        };
    };
    performance?: {
        batchSize?: number;
        batchDelay?: number;
        materializationCaching?: boolean;
        compressionThreshold?: number;
    };
    offline?: {
        enabled?: boolean;
        queueSize?: number;
        persistence?: boolean;
        syncOnReconnect?: boolean;
    };
    state?: {
        materializer?: (events: KSyncEvent[]) => any;
        enableCaching?: boolean;
        autoMaterialize?: boolean;
    };
    debug?: boolean | {
        events?: boolean;
        sync?: boolean;
        performance?: boolean;
        storage?: boolean;
    };
    features?: {
        presence?: boolean;
        streaming?: boolean;
        encryption?: boolean;
    };
}
export declare class KSync extends EventEmitter {
    private config;
    private storage;
    private syncClient?;
    private events;
    private materializedState;
    private version;
    private isConnected;
    private isOnline;
    private messageQueue;
    private presenceMap;
    private streamStates;
    private eventBatchTimeout?;
    private pendingEvents;
    private materializationCache;
    private lastMaterializationHash;
    private performanceMetrics;
    private performanceInterval?;
    private onlineListener?;
    private offlineListener?;
    constructor(config?: KSyncConfig);
    /**
     * Send an event to the system
     * @param type Event type - use namespaced names like 'chat.message' for organization
     * @param data Event data - will be validated if schema is defined
     * @param options Additional options for this specific event
     */
    send(type: string, data: any, options?: {
        priority?: 'low' | 'normal' | 'high';
        ttl?: number;
        requireSync?: boolean;
        metadata?: Record<string, any>;
    }): Promise<void>;
    /**
     * Listen to events of a specific type
     * @param type Event type to listen for
     * @param listener Callback function that receives the event data
     * @returns Unsubscribe function
     */
    on(type: string, listener: (data: any, event?: KSyncEvent) => void): this;
    /**
     * Listen to an event once
     * @param type Event type to listen for
     * @param listener Callback function
     * @returns This instance for chaining
     */
    once(type: string, listener: (data: any, event?: KSyncEvent) => void): this;
    /**
     * Remove event listener
     * @param type Event type
     * @param listener Listener function to remove
     * @returns This instance for chaining
     */
    off(type: string, listener: (data: any, event?: KSyncEvent) => void): this;
    /**
     * Get current materialized state
     * @param forceMaterialize Force re-materialization even if cached
     * @returns Current state or null if no materializer is configured
     */
    getState(forceMaterialize?: boolean): any;
    /**
     * Get all events (backward compatibility)
     */
    getEvents(): KSyncEvent[];
    /**
     * Initialize the instance (backward compatibility)
     */
    initialize(config?: any, syncClient?: KSyncSync): Promise<void>;
    /**
     * Define a schema (backward compatibility - no-op for now)
     */
    defineSchema(name: string, schema: any): void;
    /**
     * Define a materializer (backward compatibility)
     */
    defineMaterializer(name: string, materializer: (events: KSyncEvent[]) => any): void;
    /**
     * Close/cleanup (backward compatibility)
     */
    close(): Promise<void>;
    /**
     * Update presence (backward compatibility)
     */
    updatePresence(data: Partial<PresenceInfo>): Promise<void>;
    /**
     * Listen to presence updates (backward compatibility)
     */
    onPresence(listener: (presence: PresenceInfo) => void): void;
    /**
     * Get system status and metrics
     * @returns Comprehensive status information
     */
    getStatus(): {
        connected: boolean;
        online: boolean;
        serverUrl: string;
        events: number;
        queued: number;
        version: number;
        room: string;
        userId: string;
        performance: {
            eventsProcessed: number;
            averageProcessingTime: number;
            materializationCount: number;
            averageMaterializationTime: number;
        };
        features: {
            syncEnabled: boolean;
            offlineEnabled: boolean;
            presenceEnabled: boolean;
            streamingEnabled: boolean;
        };
    };
    /**
     * Manually trigger sync (useful for manual sync mode or troubleshooting)
     * @param options Sync options
     */
    sync(options?: {
        force?: boolean;
        timeout?: number;
    }): Promise<{
        synced: number;
        errors: number;
    }>;
    /**
     * Join a room (for multi-room applications)
     * @param room Room name to join
     * @param options Room join options
     */
    joinRoom(room: string, options?: {
        leaveCurrentRoom?: boolean;
        syncHistory?: boolean;
    }): Promise<void>;
    /**
     * Set user presence information
     * @param info Presence information to set
     */
    setPresence(info: Partial<PresenceInfo>): Promise<void>;
    /**
     * Get presence information for all users
     * @param filter Optional filter function
     * @returns Array of presence information
     */
    getPresence(filter?: (presence: PresenceInfo) => boolean): PresenceInfo[];
    /**
     * Start a data stream (useful for AI responses, live updates, etc.)
     * @param streamId Unique stream identifier
     * @param options Stream configuration
     */
    startStream(streamId: string, options?: {
        type?: string;
        metadata?: Record<string, any>;
        autoEnd?: number;
    }): Promise<void>;
    /**
     * Send data chunk to a stream
     * @param streamId Stream identifier
     * @param chunk Data chunk to send
     */
    streamChunk(streamId: string, chunk: StreamChunk): Promise<void>;
    /**
     * End a stream
     * @param streamId Stream identifier
     * @param data Optional final data
     */
    endStream(streamId: string, data?: any): Promise<void>;
    /**
     * Get all active streams
     * @returns Array of active stream IDs and their metadata
     */
    getActiveStreams(): Array<{
        streamId: string;
        metadata: any;
    }>;
    /**
     * Connect to the sync server (usually automatic)
     * @param options Connection options
     */
    connect(options?: {
        timeout?: number;
        force?: boolean;
    }): Promise<void>;
    /**
     * Disconnect from the sync server
     */
    disconnect(): Promise<void>;
    /**
     * Clear all events and reset state
     * @param options Clear options
     */
    clear(options?: {
        events?: boolean;
        state?: boolean;
        queue?: boolean;
        storage?: boolean;
    }): Promise<void>;
    private resolveConfig;
    private initializeStorage;
    private ensureSyncInitialized;
    private setupOfflineHandling;
    private setupPerformanceMonitoring;
    private addEvent;
    private debounceBatchFlush;
    private flushPendingEvents;
    private materialize;
    private needsRematerialization;
    private getEventsHash;
    private queueEvent;
    private sendQueuedEvents;
    private sendToServer;
    private authenticate;
    private setupSyncHandlers;
    private handleSyncMessage;
    private updatePerformanceMetrics;
    private generateUserId;
}
/**
 * Create a KSync instance with sensible defaults
 * @param config Configuration options
 * @returns KSync instance
 */
export declare function createKSync(config?: KSyncConfig): KSync;
/**
 * Create a KSync instance optimized for chat applications
 * @param room Chat room name
 * @param config Additional configuration
 * @returns KSync instance configured for chat
 */
export declare function createChat(room: string, config?: Partial<KSyncConfig>): KSync;
/**
 * Create a KSync instance optimized for todo/task applications
 * @param config Configuration options
 * @returns KSync instance configured for todos
 */
export declare function createTodos(config?: Partial<KSyncConfig>): KSync;
/**
 * Create a KSync instance optimized for multiplayer games
 * @param gameId Game identifier
 * @param config Additional configuration
 * @returns KSync instance configured for gaming
 */
export declare function createGame(gameId: string, config?: Partial<KSyncConfig>): KSync;
/**
 * Create a KSync instance optimized for AI applications with streaming
 * @param conversationId Conversation identifier
 * @param config Additional configuration
 * @returns KSync instance configured for AI
 */
export declare function createAI(conversationId?: string, config?: Partial<KSyncConfig>): KSync;
//# sourceMappingURL=core.d.ts.map