@korajs/sync 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,505 @@
+import { S as SyncMessage, a as SerializedOperation, W as WireFormat, b as SyncTransport, T as TransportOptions, c as TransportMessageHandler, d as TransportCloseHandler, e as TransportErrorHandler, Q as QueueStorage, f as SyncConfig, g as SyncStatusInfo, h as SyncState } from './transport-B5EFsr5F.cjs';
+export { A as AcknowledgmentMessage, E as ErrorMessage, H as HandshakeMessage, i as HandshakeResponseMessage, O as OperationBatchMessage, j as SYNC_STATES, k as SYNC_STATUSES, l as SyncScopeContext, m as SyncStatus, n as isAcknowledgmentMessage, o as isErrorMessage, p as isHandshakeMessage, q as isHandshakeResponseMessage, r as isOperationBatchMessage, s as isSyncMessage } from './transport-B5EFsr5F.cjs';
+import { VersionVector, Operation, KoraEventEmitter, TimeSource, ConnectionQuality } from '@korajs/core';
+
+/**
+ * Result of applying a remote operation to the store.
+ */
+type ApplyResult = 'applied' | 'duplicate' | 'skipped';
+/**
+ * Interface that the local store must implement for sync.
+ * This decouples @korajs/sync from @korajs/store — the store satisfies this interface.
+ *
+ * @korajs/store's Store class already implements these methods:
+ * - getVersionVector() — returns the current version vector
+ * - getNodeId() — returns this instance's nodeId
+ * - applyRemoteOperation(op) — applies a remote op with dedup and merge
+ * - getOperationRange(nodeId, fromSeq, toSeq) — fetches operations from the log
+ */
+interface SyncStore {
+    /** Get the current version vector for this store */
+    getVersionVector(): VersionVector;
+    /** Get the node ID for this store instance */
+    getNodeId(): string;
+    /**
+     * Apply a remote operation to the local store.
+     * Must handle deduplication (content-addressed) and merge resolution.
+     * @returns 'applied' if the operation was new, 'duplicate' if already seen, 'skipped' if filtered
+     */
+    applyRemoteOperation(op: Operation): Promise<ApplyResult>;
+    /**
+     * Get operations from a specific node within a sequence range.
+     * Used for computing deltas during sync.
+     * @param nodeId - The originating node
+     * @param fromSeq - Start sequence number (inclusive)
+     * @param toSeq - End sequence number (inclusive)
+     */
+    getOperationRange(nodeId: string, fromSeq: number, toSeq: number): Promise<Operation[]>;
+}
+
+type EncodedMessage = string | Uint8Array;
+/**
+ * Interface for encoding/decoding sync protocol messages.
+ */
+interface MessageSerializer {
+    encode(message: SyncMessage): EncodedMessage;
+    decode(data: string | Uint8Array | ArrayBuffer): SyncMessage;
+    encodeOperation(op: Operation): SerializedOperation;
+    decodeOperation(serialized: SerializedOperation): Operation;
+    setWireFormat?(format: WireFormat): void;
+    getWireFormat?(): WireFormat;
+}
+/**
+ * Convert a VersionVector (Map) to a plain object for wire transmission.
+ */
+declare function versionVectorToWire(vector: VersionVector): Record<string, number>;
+/**
+ * Convert a wire-format version vector (plain object) back to a VersionVector (Map).
+ */
+declare function wireToVersionVector(wire: Record<string, number>): VersionVector;
+/**
+ * JSON-based message serializer.
+ */
+declare class JsonMessageSerializer implements MessageSerializer {
+    encode(message: SyncMessage): string;
+    decode(data: string | Uint8Array | ArrayBuffer): SyncMessage;
+    encodeOperation(op: Operation): SerializedOperation;
+    decodeOperation(serialized: SerializedOperation): Operation;
+}
+/**
+ * Protobuf-based serializer for sync messages.
+ */
+declare class ProtobufMessageSerializer implements MessageSerializer {
+    encode(message: SyncMessage): Uint8Array;
+    decode(data: string | Uint8Array | ArrayBuffer): SyncMessage;
+    encodeOperation(op: Operation): SerializedOperation;
+    decodeOperation(serialized: SerializedOperation): Operation;
+}
+/**
+ * Negotiated serializer that supports runtime wire-format switching.
+ */
+declare class NegotiatedMessageSerializer implements MessageSerializer {
+    private readonly json;
+    private readonly protobuf;
+    private wireFormat;
+    constructor(initialWireFormat?: WireFormat);
+    encode(message: SyncMessage): EncodedMessage;
+    decode(data: string | Uint8Array | ArrayBuffer): SyncMessage;
+    encodeOperation(op: Operation): SerializedOperation;
+    decodeOperation(serialized: SerializedOperation): Operation;
+    setWireFormat(format: WireFormat): void;
+    getWireFormat(): WireFormat;
+}
+
+/**
+ * WebSocket event interface for dependency injection.
+ * Matches the subset of the browser WebSocket API that we need.
+ */
+interface WebSocketLike {
+    readonly readyState: number;
+    send(data: string | Uint8Array): void;
+    close(code?: number, reason?: string): void;
+    onopen: ((event: unknown) => void) | null;
+    onmessage: ((event: {
+        data: unknown;
+    }) => void) | null;
+    onclose: ((event: {
+        reason: string;
+        code: number;
+    }) => void) | null;
+    onerror: ((event: unknown) => void) | null;
+}
+/**
+ * Constructor for WebSocket-like objects. Allows injection of mock WebSocket for testing.
+ */
+type WebSocketConstructor = new (url: string, protocols?: string | string[]) => WebSocketLike;
+/**
+ * Options for the WebSocket transport.
+ */
+interface WebSocketTransportOptions {
+    /** Custom serializer. Defaults to JSON. */
+    serializer?: MessageSerializer;
+    /** Injectable WebSocket constructor for testing. Defaults to globalThis.WebSocket. */
+    WebSocketImpl?: WebSocketConstructor;
+}
+/**
+ * WebSocket-based sync transport implementation.
+ */
+declare class WebSocketTransport implements SyncTransport {
+    private ws;
+    private messageHandler;
+    private closeHandler;
+    private errorHandler;
+    private readonly serializer;
+    private readonly WebSocketImpl;
+    constructor(options?: WebSocketTransportOptions);
+    connect(url: string, options?: TransportOptions): Promise<void>;
+    disconnect(): Promise<void>;
+    send(message: SyncMessage): void;
+    onMessage(handler: TransportMessageHandler): void;
+    onClose(handler: TransportCloseHandler): void;
+    onError(handler: TransportErrorHandler): void;
+    isConnected(): boolean;
+}
+
+interface HttpLongPollingTransportOptions {
+    serializer?: MessageSerializer;
+    fetchImpl?: typeof fetch;
+    retryDelayMs?: number;
+    preferWebSocket?: boolean;
+    webSocketFactory?: () => SyncTransport;
+}
+/**
+ * HTTP long-polling transport with optional WebSocket upgrade.
+ */
+declare class HttpLongPollingTransport implements SyncTransport {
+    private readonly serializer;
+    private readonly fetchImpl;
+    private readonly retryDelayMs;
+    private readonly preferWebSocket;
+    private readonly webSocketFactory;
+    private messageHandler;
+    private closeHandler;
+    private errorHandler;
+    private connected;
+    private polling;
+    private url;
+    private authToken;
+    private pollAbort;
+    private upgradedTransport;
+    constructor(options?: HttpLongPollingTransportOptions);
+    connect(url: string, options?: TransportOptions): Promise<void>;
+    disconnect(): Promise<void>;
+    send(message: SyncMessage): void;
+    onMessage(handler: TransportMessageHandler): void;
+    onClose(handler: TransportCloseHandler): void;
+    onError(handler: TransportErrorHandler): void;
+    isConnected(): boolean;
+    private tryUpgradeToWebSocket;
+    private postMessage;
+    private runPollLoop;
+    private makePollHeaders;
+}
+
+/**
+ * Configuration for the chaos transport.
+ */
+interface ChaosConfig {
+    /** Probability of dropping a message (0-1). Defaults to 0. */
+    dropRate?: number;
+    /** Probability of duplicating a message (0-1). Defaults to 0. */
+    duplicateRate?: number;
+    /** Probability of reordering messages (0-1). Defaults to 0. */
+    reorderRate?: number;
+    /** Maximum latency in ms for delayed messages. Defaults to 0. */
+    maxLatency?: number;
+    /** Injectable random source for deterministic testing. Returns value in [0, 1). */
+    randomSource?: () => number;
+}
+/**
+ * Chaos transport that wraps another transport and injects faults.
+ * Used for testing sync convergence under unreliable network conditions.
+ *
+ * Supports message dropping, duplication, reordering, and latency injection.
+ * All random behavior is injectable for deterministic, reproducible tests.
+ */
+declare class ChaosTransport implements SyncTransport {
+    private readonly inner;
+    private readonly dropRate;
+    private readonly duplicateRate;
+    private readonly reorderRate;
+    private readonly maxLatency;
+    private readonly random;
+    private messageHandler;
+    private reorderBuffer;
+    private timers;
+    constructor(inner: SyncTransport, config?: ChaosConfig);
+    connect(url: string, options?: TransportOptions): Promise<void>;
+    disconnect(): Promise<void>;
+    send(message: SyncMessage): void;
+    onMessage(handler: TransportMessageHandler): void;
+    onClose(handler: TransportCloseHandler): void;
+    onError(handler: TransportErrorHandler): void;
+    isConnected(): boolean;
+    private handleIncoming;
+    private deliverIncoming;
+    private flushReorderBuffer;
+}
+
+/**
+ * A batch of operations taken from the queue for sending.
+ */
+interface OutboundBatch {
+    /** Unique identifier for this batch */
+    batchId: string;
+    /** Operations in this batch, in causal order */
+    operations: Operation[];
+}
+/**
+ * Outbound operation queue with pluggable persistence.
+ * Manages operations waiting to be sent to the sync server.
+ *
+ * Operations are deduplicated by ID (content-addressed) and maintained
+ * in causal order via topological sort.
+ */
+declare class OutboundQueue {
+    private readonly storage;
+    private queue;
+    private readonly seen;
+    private readonly inFlight;
+    private nextBatchId;
+    private initialized;
+    constructor(storage: QueueStorage);
+    /**
+     * Load persisted operations from storage.
+     * Must be called before using the queue.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Add an operation to the outbound queue.
+     * Deduplicates by operation ID. Persists to storage.
+     */
+    enqueue(op: Operation): Promise<void>;
+    /**
+     * Take a batch of operations from the front of the queue.
+     * Moves them to in-flight status. Returns null if queue is empty.
+     *
+     * @param batchSize - Maximum number of operations in the batch
+     */
+    takeBatch(batchSize: number): OutboundBatch | null;
+    /**
+     * Acknowledge a batch, removing its operations permanently.
+     */
+    acknowledge(batchId: string): Promise<void>;
+    /**
+     * Return a failed batch to the front of the queue for retry.
+     * Prepends the operations to maintain priority.
+     */
+    returnBatch(batchId: string): void;
+    /**
+     * Number of operations waiting in the queue (not counting in-flight).
+     */
+    get size(): number;
+    /**
+     * Total operations including in-flight.
+     */
+    get totalPending(): number;
+    /**
+     * Whether the queue has any operations to send.
+     */
+    get hasOperations(): boolean;
+    /**
+     * Peek at the first `count` operations without removing them.
+     */
+    peek(count: number): Operation[];
+    /**
+     * Whether initialize() has been called.
+     */
+    get isInitialized(): boolean;
+}
+
+/**
+ * Options for creating a SyncEngine.
+ */
+interface SyncEngineOptions {
+    /** Transport implementation (WebSocket, memory, etc.) */
+    transport: SyncTransport;
+    /** Local store implementing SyncStore */
+    store: SyncStore;
+    /** Sync configuration */
+    config: SyncConfig;
+    /** Message serializer. Defaults to JSON. */
+    serializer?: MessageSerializer;
+    /** Event emitter for DevTools integration */
+    emitter?: KoraEventEmitter;
+    /** Queue storage for persistent outbound queue. Defaults to in-memory. */
+    queueStorage?: QueueStorage;
+}
+/**
+ * Core sync orchestrator. Manages the sync lifecycle:
+ * disconnected → connecting → handshaking → syncing → streaming
+ *
+ * Coordinates handshake, delta exchange, and real-time streaming
+ * between a local store and a remote sync server.
+ */
+declare class SyncEngine {
+    private state;
+    private readonly transport;
+    private readonly store;
+    private readonly config;
+    private readonly serializer;
+    private readonly emitter;
+    private readonly outboundQueue;
+    private readonly batchSize;
+    private remoteVector;
+    private lastSyncedAt;
+    private currentBatch;
+    private deltaBatchesReceived;
+    private deltaReceiveComplete;
+    private deltaSendComplete;
+    constructor(options: SyncEngineOptions);
+    /**
+     * Start the sync engine: connect → handshake → delta exchange → streaming.
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the sync engine. Disconnects the transport.
+     */
+    stop(): Promise<void>;
+    private ensureDisconnected;
+    /**
+     * Push a local operation to the outbound queue.
+     * If streaming, flushes immediately.
+     */
+    pushOperation(op: Operation): Promise<void>;
+    /**
+     * Get the current developer-facing sync status.
+     */
+    getStatus(): SyncStatusInfo;
+    /**
+     * Get the current internal state (for testing).
+     */
+    getState(): SyncState;
+    /**
+     * Get the outbound queue (for testing).
+     */
+    getOutboundQueue(): OutboundQueue;
+    private handleMessage;
+    private handleHandshakeResponse;
+    private sendDelta;
+    private collectDelta;
+    private handleOperationBatch;
+    private handleAcknowledgment;
+    private handleError;
+    private checkDeltaComplete;
+    private flushQueue;
+    private handleTransportClose;
+    private handleTransportError;
+    private transitionTo;
+    private setSerializerWireFormat;
+}
+
+/**
+ * Configuration for the connection monitor.
+ */
+interface ConnectionMonitorConfig {
+    /** Number of latency samples to keep in the rolling window. Defaults to 20. */
+    windowSize?: number;
+    /** Time in ms after which the connection is considered stale. Defaults to 30000. */
+    staleThreshold?: number;
+    /** Injectable time source for deterministic testing */
+    timeSource?: TimeSource;
+}
+/**
+ * Monitors connection quality based on RTT latency samples,
+ * missed acknowledgments, and activity timestamps.
+ */
+declare class ConnectionMonitor {
+    private readonly windowSize;
+    private readonly staleThreshold;
+    private readonly timeSource;
+    private latencies;
+    private missedAcks;
+    private lastActivityTime;
+    constructor(config?: ConnectionMonitorConfig);
+    /**
+     * Record a round-trip time sample.
+     */
+    recordLatency(ms: number): void;
+    /**
+     * Record a missed acknowledgment (message sent but no response received).
+     */
+    recordMissedAck(): void;
+    /**
+     * Record any activity (message sent or received).
+     */
+    recordActivity(): void;
+    /**
+     * Assess current connection quality based on collected metrics.
+     *
+     * Quality thresholds (average RTT):
+     * - excellent: < 100ms, 0 missed acks
+     * - good: < 300ms, ≤ 1 missed ack
+     * - fair: < 1000ms, ≤ 3 missed acks
+     * - poor: < 5000ms or > 3 missed acks
+     * - offline: no activity for staleThreshold ms
+     */
+    getQuality(): ConnectionQuality;
+    /**
+     * Reset all metrics. Call on disconnect.
+     */
+    reset(): void;
+    /**
+     * Get the current average latency in ms. Returns null if no samples.
+     */
+    getAverageLatency(): number | null;
+    /**
+     * Get the number of missed acks.
+     */
+    getMissedAcks(): number;
+}
+
+/**
+ * Configuration for the reconnection manager.
+ */
+interface ReconnectionConfig {
+    /** Initial delay in ms before first reconnection attempt. Defaults to 1000. */
+    initialDelay?: number;
+    /** Maximum delay in ms between attempts. Defaults to 30000. */
+    maxDelay?: number;
+    /** Multiplier for exponential backoff. Defaults to 2. */
+    multiplier?: number;
+    /** Maximum number of reconnection attempts. 0 means unlimited. Defaults to 0. */
+    maxAttempts?: number;
+    /** Jitter factor (0-1). Random variation applied to delay. Defaults to 0.25. */
+    jitter?: number;
+    /** Injectable time source for deterministic testing. */
+    timeSource?: TimeSource;
+    /** Injectable random source for deterministic jitter. Returns value in [0, 1). */
+    randomSource?: () => number;
+}
+/**
+ * Manages reconnection attempts with exponential backoff and jitter.
+ *
+ * Formula: min(initialDelay * multiplier^attempt, maxDelay) * (1 + jitter * (random - 0.5) * 2)
+ */
+declare class ReconnectionManager {
+    private readonly initialDelay;
+    private readonly maxDelay;
+    private readonly multiplier;
+    private readonly maxAttempts;
+    private readonly jitter;
+    private readonly random;
+    private attempt;
+    private timer;
+    private stopped;
+    private waitResolve;
+    constructor(config?: ReconnectionConfig);
+    /**
+     * Start reconnection attempts. Calls `onReconnect` with exponential backoff.
+     *
+     * @param onReconnect - Called on each attempt. Return `true` if reconnection succeeded.
+     * @returns Promise that resolves when reconnection succeeds or maxAttempts reached.
+     */
+    start(onReconnect: () => Promise<boolean>): Promise<boolean>;
+    /**
+     * Stop any pending reconnection attempt.
+     */
+    stop(): void;
+    /**
+     * Reset the attempt counter. Call after a successful manual reconnection.
+     */
+    reset(): void;
+    /**
+     * Compute the next delay for the current attempt.
+     * Exposed for testing purposes.
+     */
+    getNextDelay(): number;
+    /**
+     * Current attempt number (for testing).
+     */
+    getAttemptCount(): number;
+    private wait;
+}
+
+export { type ApplyResult, type ChaosConfig, ChaosTransport, ConnectionMonitor, type ConnectionMonitorConfig, HttpLongPollingTransport, type HttpLongPollingTransportOptions, JsonMessageSerializer, type MessageSerializer, NegotiatedMessageSerializer, type OutboundBatch, OutboundQueue, ProtobufMessageSerializer, QueueStorage, type ReconnectionConfig, ReconnectionManager, SerializedOperation, SyncConfig, SyncEngine, type SyncEngineOptions, SyncMessage, SyncState, SyncStatusInfo, type SyncStore, SyncTransport, TransportCloseHandler, TransportErrorHandler, TransportMessageHandler, TransportOptions, type WebSocketConstructor, type WebSocketLike, WebSocketTransport, type WebSocketTransportOptions, WireFormat, versionVectorToWire, wireToVersionVector };