@korajs/sync 0.4.0 → 0.5.0

package/dist/internal.d.cts

@@ -1,4 +1,4 @@
-import { c as SyncTransport, T as TransportOptions, a as SyncMessage, d as TransportMessageHandler, e as TransportCloseHandler, f as TransportErrorHandler, Q as QueueStorage } from './transport-B-BIguq9.cjs';
+import { c as SyncTransport, T as TransportOptions, a as SyncMessage, d as TransportMessageHandler, e as TransportCloseHandler, f as TransportErrorHandler, Q as QueueStorage } from './transport-BrdBj7rH.cjs';
 import { Operation } from '@korajs/core';
 
 /**

package/dist/internal.d.ts

@@ -1,4 +1,4 @@
-import { c as SyncTransport, T as TransportOptions, a as SyncMessage, d as TransportMessageHandler, e as TransportCloseHandler, f as TransportErrorHandler, Q as QueueStorage } from './transport-B-BIguq9.js';
+import { c as SyncTransport, T as TransportOptions, a as SyncMessage, d as TransportMessageHandler, e as TransportCloseHandler, f as TransportErrorHandler, Q as QueueStorage } from './transport-BrdBj7rH.js';
 import { Operation } from '@korajs/core';
 
 /**

package/dist/{transport-B-BIguq9.d.cts → transport-BrdBj7rH.d.cts}

@@ -1,4 +1,5 @@
-import { KoraError, Operation, OperationType, HLCTimestamp, AtomicOp } from '@korajs/core';
+import * as _korajs_core from '@korajs/core';
+import { KoraError, Operation, VersionVector, OperationType, HLCTimestamp, AtomicOp } from '@korajs/core';
 
 /**
  * Encryption types for the Kora.js sync layer.
@@ -92,7 +93,7 @@ type SyncState = (typeof SYNC_STATES)[number];
 /**
  * Developer-facing sync status. Simplified view of the internal state.
  */
-declare const SYNC_STATUSES: readonly ["connected", "syncing", "synced", "offline", "error"];
+declare const SYNC_STATUSES: readonly ["connected", "syncing", "synced", "offline", "error", "schema-mismatch"];
 type SyncStatus = (typeof SYNC_STATUSES)[number];
 /**
  * Sync status information exposed to developers.
@@ -144,6 +145,20 @@ interface SyncConfig {
     maxReconnectInterval?: number;
     /** Schema version of this client. */
     schemaVersion?: number;
+    /** Start sync automatically when the engine is created. Defaults to false. */
+    autoConnect?: boolean;
+    /**
+     * When true, wait for server ACKs on all outbound handshake delta batches before
+     * entering streaming. Improves backpressure for large initial syncs.
+     */
+    strictHandshake?: boolean;
+    /** Optional operation transforms for cross-schema-version sync. */
+    operationTransforms?: _korajs_core.OperationTransform[];
+    /**
+     * Richtext snapshot size (bytes) at which the optional Yjs doc channel is used.
+     * Defaults to 4096.
+     */
+    richtextDocChannelThreshold?: number;
     /**
      * End-to-end encryption configuration.
      * When enabled, `data` and `previousData` fields are encrypted before sending
@@ -158,6 +173,25 @@ interface SyncScopeContext {
     userId?: string;
     [key: string]: unknown;
 }
+/**
+ * Persists last-acked server version vector and computes unsynced operations from the op log.
+ */
+interface DeltaCursor {
+    /** ID of the last fully applied operation in the previous delta stream */
+    lastOperationId: string;
+    /** Zero-based batch index where the cursor was recorded */
+    batchIndex: number;
+}
+interface SyncStatePersistence {
+    loadLastAckedServerVector(): Promise<VersionVector>;
+    saveLastAckedServerVector(vector: VersionVector): Promise<void>;
+    mergeServerVectors(a: VersionVector, b: VersionVector): VersionVector;
+    countUnsyncedOperations(serverVector: VersionVector): Promise<number>;
+    getUnsyncedOperations(serverVector: VersionVector): Promise<Operation[]>;
+    /** Resume position for paginated initial sync (optional). */
+    loadDeltaCursor?(): Promise<DeltaCursor | null>;
+    saveDeltaCursor?(cursor: DeltaCursor | null): Promise<void>;
+}
 /**
  * Interface for persisting the outbound operation queue.
  * Operations must survive page refreshes and be sent when connection is re-established.
@@ -191,6 +225,23 @@ declare class InvalidScopeError extends KoraError {
     constructor(message: string, context?: Record<string, unknown>);
 }
 
+/**
+ * A live query filter that narrows which operations sync for a collection.
+ */
+interface SyncQuerySubset {
+    collection: string;
+    where: Record<string, unknown>;
+}
+/**
+ * Returns true when an operation matches at least one active query subset
+ * for its collection. Collections without query subsets pass through.
+ */
+declare function operationMatchesQuerySubsets(op: Operation, subsets: SyncQuerySubset[] | undefined, fullRecord?: Record<string, unknown> | null): boolean;
+/**
+ * Deduplicate query subsets by collection + where JSON key.
+ */
+declare function dedupeQuerySubsets(subsets: SyncQuerySubset[]): SyncQuerySubset[];
+
 type WireFormat = 'json' | 'protobuf';
 /**
  * Wire-format operation. Plain object (no Map) for JSON serialization.
@@ -229,6 +280,10 @@ interface HandshakeMessage {
     supportedWireFormats?: WireFormat[];
     /** Per-collection sync scope filters. Limits which records are synced to this client. */
     syncScope?: Record<string, Record<string, unknown>>;
+    /** Base64url-encoded delta cursor for resuming paginated initial sync */
+    deltaCursor?: string;
+    /** Live query filters that further narrow synced data within auth/schema scope */
+    syncQueries?: SyncQuerySubset[];
 }
 /**
  * Server response to a handshake.
@@ -241,6 +296,10 @@ interface HandshakeResponseMessage {
     schemaVersion: number;
     accepted: boolean;
     rejectReason?: string;
+    /** Inclusive minimum schema version the server accepts (present when rejected for schema mismatch). */
+    supportedSchemaMin?: number;
+    /** Inclusive maximum schema version the server accepts (present when rejected for schema mismatch). */
+    supportedSchemaMax?: number;
     selectedWireFormat?: WireFormat;
     /** The server-accepted per-collection sync scope. Confirms what data will be synced. */
     acceptedScope?: Record<string, Record<string, unknown>>;
@@ -256,6 +315,10 @@ interface OperationBatchMessage {
     isFinal: boolean;
     /** Index of this batch (0-based) for ordering */
     batchIndex: number;
+    /** Base64url-encoded cursor marking the last operation in this batch */
+    cursor?: string;
+    /** Total batches in this delta exchange (for progress reporting) */
+    totalBatches?: number;
 }
 /**
  * Acknowledgment of a received message.
@@ -307,10 +370,23 @@ interface AwarenessUpdateMessage {
     /** Map of clientId -> state (null means removal) */
     states: Record<string, AwarenessStateWire | null>;
 }
+/**
+ * Incremental Yjs update for a richtext field. Ephemeral side channel for large documents.
+ * JSON transport only; not persisted on the server operation log.
+ */
+interface YjsDocUpdateMessage {
+    type: 'yjs-doc-update';
+    messageId: string;
+    collection: string;
+    recordId: string;
+    field: string;
+    /** Base64-encoded Yjs update binary */
+    update: string;
+}
 /**
  * Union of all sync protocol messages.
  */
-type SyncMessage = HandshakeMessage | HandshakeResponseMessage | OperationBatchMessage | AcknowledgmentMessage | ErrorMessage | AwarenessUpdateMessage;
+type SyncMessage = HandshakeMessage | HandshakeResponseMessage | OperationBatchMessage | AcknowledgmentMessage | ErrorMessage | AwarenessUpdateMessage | YjsDocUpdateMessage;
 /**
  * Check if an unknown value is a valid SyncMessage.
  */
@@ -339,6 +415,10 @@ declare function isErrorMessage(value: unknown): value is ErrorMessage;
  * Check if a value is an AwarenessUpdateMessage.
  */
 declare function isAwarenessUpdateMessage(value: unknown): value is AwarenessUpdateMessage;
+/**
+ * Check if a value is a YjsDocUpdateMessage.
+ */
+declare function isYjsDocUpdateMessage(value: unknown): value is YjsDocUpdateMessage;
 
 /**
  * Options for transport connection.
@@ -382,4 +462,4 @@ interface SyncTransport {
     isConnected(): boolean;
 }
 
-export { type AcknowledgmentMessage as A, isSyncMessage as B, type EncryptedPayload as E, type HandshakeMessage as H, InvalidScopeError as I, type OperationBatchMessage as O, type QueueStorage as Q, type SyncScopeMap as S, type TransportOptions as T, type VersionedKey as V, type WireFormat as W, type SyncMessage as a, type SerializedOperation as b, type SyncTransport as c, type TransportMessageHandler as d, type TransportCloseHandler as e, type TransportErrorHandler as f, type SyncEncryptionConfig as g, type SyncState as h, type SyncStatusInfo as i, type SyncConfig as j, type AwarenessStateWire as k, type AwarenessUpdateMessage as l, type ErrorMessage as m, type HandshakeResponseMessage as n, SYNC_STATES as o, SYNC_STATUSES as p, ScopeViolationError as q, type SyncEncryptionAlgorithm as r, type SyncScopeContext as s, type SyncStatus as t, isAcknowledgmentMessage as u, isAwarenessUpdateMessage as v, isErrorMessage as w, isHandshakeMessage as x, isHandshakeResponseMessage as y, isOperationBatchMessage as z };
+export { type AcknowledgmentMessage as A, isHandshakeMessage as B, isHandshakeResponseMessage as C, type DeltaCursor as D, type EncryptedPayload as E, isOperationBatchMessage as F, isSyncMessage as G, type HandshakeMessage as H, InvalidScopeError as I, isYjsDocUpdateMessage as J, operationMatchesQuerySubsets as K, type OperationBatchMessage as O, type QueueStorage as Q, type SyncScopeMap as S, type TransportOptions as T, type VersionedKey as V, type WireFormat as W, type YjsDocUpdateMessage as Y, type SyncMessage as a, type SerializedOperation as b, type SyncTransport as c, type TransportMessageHandler as d, type TransportCloseHandler as e, type TransportErrorHandler as f, type SyncEncryptionConfig as g, type SyncState as h, type SyncStatusInfo as i, type SyncConfig as j, type SyncStatePersistence as k, type SyncQuerySubset as l, type AwarenessStateWire as m, type AwarenessUpdateMessage as n, type ErrorMessage as o, type HandshakeResponseMessage as p, SYNC_STATES as q, SYNC_STATUSES as r, ScopeViolationError as s, type SyncEncryptionAlgorithm as t, type SyncScopeContext as u, type SyncStatus as v, dedupeQuerySubsets as w, isAcknowledgmentMessage as x, isAwarenessUpdateMessage as y, isErrorMessage as z };

package/dist/{transport-B-BIguq9.d.ts → transport-BrdBj7rH.d.ts}

@@ -1,4 +1,5 @@
-import { KoraError, Operation, OperationType, HLCTimestamp, AtomicOp } from '@korajs/core';
+import * as _korajs_core from '@korajs/core';
+import { KoraError, Operation, VersionVector, OperationType, HLCTimestamp, AtomicOp } from '@korajs/core';
 
 /**
  * Encryption types for the Kora.js sync layer.
@@ -92,7 +93,7 @@ type SyncState = (typeof SYNC_STATES)[number];
 /**
  * Developer-facing sync status. Simplified view of the internal state.
  */
-declare const SYNC_STATUSES: readonly ["connected", "syncing", "synced", "offline", "error"];
+declare const SYNC_STATUSES: readonly ["connected", "syncing", "synced", "offline", "error", "schema-mismatch"];
 type SyncStatus = (typeof SYNC_STATUSES)[number];
 /**
  * Sync status information exposed to developers.
@@ -144,6 +145,20 @@ interface SyncConfig {
     maxReconnectInterval?: number;
     /** Schema version of this client. */
     schemaVersion?: number;
+    /** Start sync automatically when the engine is created. Defaults to false. */
+    autoConnect?: boolean;
+    /**
+     * When true, wait for server ACKs on all outbound handshake delta batches before
+     * entering streaming. Improves backpressure for large initial syncs.
+     */
+    strictHandshake?: boolean;
+    /** Optional operation transforms for cross-schema-version sync. */
+    operationTransforms?: _korajs_core.OperationTransform[];
+    /**
+     * Richtext snapshot size (bytes) at which the optional Yjs doc channel is used.
+     * Defaults to 4096.
+     */
+    richtextDocChannelThreshold?: number;
     /**
      * End-to-end encryption configuration.
      * When enabled, `data` and `previousData` fields are encrypted before sending
@@ -158,6 +173,25 @@ interface SyncScopeContext {
     userId?: string;
     [key: string]: unknown;
 }
+/**
+ * Persists last-acked server version vector and computes unsynced operations from the op log.
+ */
+interface DeltaCursor {
+    /** ID of the last fully applied operation in the previous delta stream */
+    lastOperationId: string;
+    /** Zero-based batch index where the cursor was recorded */
+    batchIndex: number;
+}
+interface SyncStatePersistence {
+    loadLastAckedServerVector(): Promise<VersionVector>;
+    saveLastAckedServerVector(vector: VersionVector): Promise<void>;
+    mergeServerVectors(a: VersionVector, b: VersionVector): VersionVector;
+    countUnsyncedOperations(serverVector: VersionVector): Promise<number>;
+    getUnsyncedOperations(serverVector: VersionVector): Promise<Operation[]>;
+    /** Resume position for paginated initial sync (optional). */
+    loadDeltaCursor?(): Promise<DeltaCursor | null>;
+    saveDeltaCursor?(cursor: DeltaCursor | null): Promise<void>;
+}
 /**
  * Interface for persisting the outbound operation queue.
  * Operations must survive page refreshes and be sent when connection is re-established.
@@ -191,6 +225,23 @@ declare class InvalidScopeError extends KoraError {
     constructor(message: string, context?: Record<string, unknown>);
 }
 
+/**
+ * A live query filter that narrows which operations sync for a collection.
+ */
+interface SyncQuerySubset {
+    collection: string;
+    where: Record<string, unknown>;
+}
+/**
+ * Returns true when an operation matches at least one active query subset
+ * for its collection. Collections without query subsets pass through.
+ */
+declare function operationMatchesQuerySubsets(op: Operation, subsets: SyncQuerySubset[] | undefined, fullRecord?: Record<string, unknown> | null): boolean;
+/**
+ * Deduplicate query subsets by collection + where JSON key.
+ */
+declare function dedupeQuerySubsets(subsets: SyncQuerySubset[]): SyncQuerySubset[];
+
 type WireFormat = 'json' | 'protobuf';
 /**
  * Wire-format operation. Plain object (no Map) for JSON serialization.
@@ -229,6 +280,10 @@ interface HandshakeMessage {
     supportedWireFormats?: WireFormat[];
     /** Per-collection sync scope filters. Limits which records are synced to this client. */
     syncScope?: Record<string, Record<string, unknown>>;
+    /** Base64url-encoded delta cursor for resuming paginated initial sync */
+    deltaCursor?: string;
+    /** Live query filters that further narrow synced data within auth/schema scope */
+    syncQueries?: SyncQuerySubset[];
 }
 /**
  * Server response to a handshake.
@@ -241,6 +296,10 @@ interface HandshakeResponseMessage {
     schemaVersion: number;
     accepted: boolean;
     rejectReason?: string;
+    /** Inclusive minimum schema version the server accepts (present when rejected for schema mismatch). */
+    supportedSchemaMin?: number;
+    /** Inclusive maximum schema version the server accepts (present when rejected for schema mismatch). */
+    supportedSchemaMax?: number;
     selectedWireFormat?: WireFormat;
     /** The server-accepted per-collection sync scope. Confirms what data will be synced. */
     acceptedScope?: Record<string, Record<string, unknown>>;
@@ -256,6 +315,10 @@ interface OperationBatchMessage {
     isFinal: boolean;
     /** Index of this batch (0-based) for ordering */
     batchIndex: number;
+    /** Base64url-encoded cursor marking the last operation in this batch */
+    cursor?: string;
+    /** Total batches in this delta exchange (for progress reporting) */
+    totalBatches?: number;
 }
 /**
  * Acknowledgment of a received message.
@@ -307,10 +370,23 @@ interface AwarenessUpdateMessage {
     /** Map of clientId -> state (null means removal) */
     states: Record<string, AwarenessStateWire | null>;
 }
+/**
+ * Incremental Yjs update for a richtext field. Ephemeral side channel for large documents.
+ * JSON transport only; not persisted on the server operation log.
+ */
+interface YjsDocUpdateMessage {
+    type: 'yjs-doc-update';
+    messageId: string;
+    collection: string;
+    recordId: string;
+    field: string;
+    /** Base64-encoded Yjs update binary */
+    update: string;
+}
 /**
  * Union of all sync protocol messages.
  */
-type SyncMessage = HandshakeMessage | HandshakeResponseMessage | OperationBatchMessage | AcknowledgmentMessage | ErrorMessage | AwarenessUpdateMessage;
+type SyncMessage = HandshakeMessage | HandshakeResponseMessage | OperationBatchMessage | AcknowledgmentMessage | ErrorMessage | AwarenessUpdateMessage | YjsDocUpdateMessage;
 /**
  * Check if an unknown value is a valid SyncMessage.
  */
@@ -339,6 +415,10 @@ declare function isErrorMessage(value: unknown): value is ErrorMessage;
  * Check if a value is an AwarenessUpdateMessage.
  */
 declare function isAwarenessUpdateMessage(value: unknown): value is AwarenessUpdateMessage;
+/**
+ * Check if a value is a YjsDocUpdateMessage.
+ */
+declare function isYjsDocUpdateMessage(value: unknown): value is YjsDocUpdateMessage;
 
 /**
  * Options for transport connection.
@@ -382,4 +462,4 @@ interface SyncTransport {
     isConnected(): boolean;
 }
 
-export { type AcknowledgmentMessage as A, isSyncMessage as B, type EncryptedPayload as E, type HandshakeMessage as H, InvalidScopeError as I, type OperationBatchMessage as O, type QueueStorage as Q, type SyncScopeMap as S, type TransportOptions as T, type VersionedKey as V, type WireFormat as W, type SyncMessage as a, type SerializedOperation as b, type SyncTransport as c, type TransportMessageHandler as d, type TransportCloseHandler as e, type TransportErrorHandler as f, type SyncEncryptionConfig as g, type SyncState as h, type SyncStatusInfo as i, type SyncConfig as j, type AwarenessStateWire as k, type AwarenessUpdateMessage as l, type ErrorMessage as m, type HandshakeResponseMessage as n, SYNC_STATES as o, SYNC_STATUSES as p, ScopeViolationError as q, type SyncEncryptionAlgorithm as r, type SyncScopeContext as s, type SyncStatus as t, isAcknowledgmentMessage as u, isAwarenessUpdateMessage as v, isErrorMessage as w, isHandshakeMessage as x, isHandshakeResponseMessage as y, isOperationBatchMessage as z };
+export { type AcknowledgmentMessage as A, isHandshakeMessage as B, isHandshakeResponseMessage as C, type DeltaCursor as D, type EncryptedPayload as E, isOperationBatchMessage as F, isSyncMessage as G, type HandshakeMessage as H, InvalidScopeError as I, isYjsDocUpdateMessage as J, operationMatchesQuerySubsets as K, type OperationBatchMessage as O, type QueueStorage as Q, type SyncScopeMap as S, type TransportOptions as T, type VersionedKey as V, type WireFormat as W, type YjsDocUpdateMessage as Y, type SyncMessage as a, type SerializedOperation as b, type SyncTransport as c, type TransportMessageHandler as d, type TransportCloseHandler as e, type TransportErrorHandler as f, type SyncEncryptionConfig as g, type SyncState as h, type SyncStatusInfo as i, type SyncConfig as j, type SyncStatePersistence as k, type SyncQuerySubset as l, type AwarenessStateWire as m, type AwarenessUpdateMessage as n, type ErrorMessage as o, type HandshakeResponseMessage as p, SYNC_STATES as q, SYNC_STATUSES as r, ScopeViolationError as s, type SyncEncryptionAlgorithm as t, type SyncScopeContext as u, type SyncStatus as v, dedupeQuerySubsets as w, isAcknowledgmentMessage as x, isAwarenessUpdateMessage as y, isErrorMessage as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@korajs/sync",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Sync protocol and transports for Kora.js with delta sync, causal ordering, and automatic reconnection",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -33,8 +33,8 @@
   ],
   "dependencies": {
     "protobufjs": "^8.0.1",
-    "@korajs/core": "0.4.0",
-    "@korajs/merge": "0.4.0"
+    "@korajs/core": "0.5.0",
+    "@korajs/merge": "0.5.0"
   },
   "devDependencies": {
     "@fast-check/vitest": "0.2.0",
@@ -47,7 +47,8 @@
     "build": "tsup",
     "dev": "tsup --watch",
     "test": "vitest run",
-    "test:chaos": "vitest run tests/integration/chaos-nightly.test.ts",
+    "test:benchmarks": "vitest run --config vitest.benchmark.config.ts",
+    "test:chaos": "NIGHTLY=true vitest run tests/integration/chaos-nightly.test.ts",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
     "lint": "biome check .",