@korajs/sync 1.0.0-beta.10 → 1.0.0-beta.11

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-B2GQerqJ.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-iXX0KA_W.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-B2GQerqJ.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-iXX0KA_W.js';
 import { Operation } from '@korajs/core';
 
 /**

package/dist/{transport-B2GQerqJ.d.cts → transport-iXX0KA_W.d.cts}

@@ -93,14 +93,27 @@ type SyncState = (typeof SYNC_STATES)[number];
 /**
  * Developer-facing sync status. Simplified view of the internal state.
  */
-declare const SYNC_STATUSES: readonly ["connected", "reconnecting", "syncing", "synced", "offline", "clock-error", "error", "schema-mismatch"];
+declare const SYNC_STATUSES: readonly ["connected", "reconnecting", "syncing", "synced", "offline", "clock-error", "error", "schema-mismatch", "auth-required"];
 type SyncStatus = (typeof SYNC_STATUSES)[number];
+type SyncPhase = 'suspended' | 'offline' | 'connecting' | 'authenticating' | 'handshaking' | 'uploading' | 'receiving' | 'applying' | 'streaming' | 'blocked';
+interface ActiveApplyFailure {
+    operationId: string;
+    collection: string;
+    recordId: string;
+    code: string;
+    message: string;
+    retriable: boolean;
+    firstSeenAt: number;
+    retryCount: number;
+}
 /**
  * Sync status information exposed to developers.
  */
 interface SyncStatusInfo {
     /** Current developer-facing status */
     status: SyncStatus;
+    phase?: SyncPhase;
+    reason?: string;
     /** True when the engine is actively trying to re-establish a transport session. */
     reconnecting: boolean;
     /** Number of operations waiting to be sent */
@@ -115,7 +128,47 @@ interface SyncStatusInfo {
     conflicts: number;
     /** serverTime - localTime in ms measured at the last handshake, or null before first connect. Negative = this device's clock is fast. */
     clockSkewMs: number | null;
+    inFlightUploadOperations?: number;
+    hasInFlightDeliveryBatch?: boolean;
+    activeViewId?: string;
+    activeViewComplete?: boolean;
+    initialSync?: {
+        complete: boolean;
+        receivedBatches: number;
+        totalBatches: number | null;
+        progress: number | null;
+    };
+    deliveryWatermark?: number;
+    serverFrontier?: number | null;
+    blockedFailure?: ActiveApplyFailure | null;
+}
+interface SyncSettlementOptions {
+    upload?: boolean;
+    download?: 'active-view' | false;
+    timeoutMs?: number;
+    signal?: AbortSignal;
 }
+type SyncSettlementResult = {
+    outcome: 'settled';
+    status: SyncStatusInfo;
+} | {
+    outcome: 'offline';
+    status: SyncStatusInfo;
+} | {
+    outcome: 'suspended';
+    reason: string;
+    status: SyncStatusInfo;
+} | {
+    outcome: 'blocked';
+    failure: ActiveApplyFailure;
+    status: SyncStatusInfo;
+} | {
+    outcome: 'timeout';
+    status: SyncStatusInfo;
+} | {
+    outcome: 'aborted';
+    status: SyncStatusInfo;
+};
 /**
  * Per-collection sync scope map. Maps collection names to field-value filters.
  * Empty filter `{}` means no restriction (all records visible).
@@ -134,6 +187,14 @@ interface SyncConfig {
     auth?: () => Promise<{
         token: string;
     }>;
+    /** Auth readiness gate. A suspended result prevents transport creation and retries. */
+    authState?: () => Promise<{
+        state: 'loading' | 'signed-out' | 'anonymous' | 'authenticated';
+        mayConnectAnonymously?: boolean;
+    }>;
+    querySubsets?: {
+        mode?: 'reactive' | 'static' | 'disabled';
+    };
     /** Sync scopes per collection. Limits which records sync to this client. */
     scopes?: Record<string, (ctx: SyncScopeContext) => Record<string, unknown>>;
     /**
@@ -307,10 +368,10 @@ interface SyncQuerySubset {
  * 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.
- */
+/** Canonicalize equality subsets and remove subsets already covered by a broader one. */
 declare function dedupeQuerySubsets(subsets: SyncQuerySubset[]): SyncQuerySubset[];
+/** True when every record selected by `narrow` is also selected by `broad`. */
+declare function querySubsetContains(broad: SyncQuerySubset[], narrow: SyncQuerySubset[]): boolean;
 
 type WireFormat = 'json' | 'protobuf';
 /**
@@ -663,4 +724,4 @@ interface SyncTransport {
     isConnected(): boolean;
 }
 
-export { isYjsDocUpdateMessage as $, type AcknowledgmentMessage as A, type BlobChunkRequestMessage as B, dedupeQuerySubsets as C, type DeltaCursor as D, type EncryptedPayload as E, isAcknowledgmentMessage as F, isAwarenessUpdateMessage as G, type HandshakeMessage as H, InvalidScopeError as I, isBlobChunkPushMessage as J, isBlobChunkRequestMessage as K, isBlobChunkResponseMessage as L, MemoryRejectedOperationStorage as M, isErrorMessage as N, type OperationBatchMessage as O, isHandshakeMessage as P, type QueueStorage as Q, type RejectedOperationStorage as R, type SyncScopeMap as S, type TransportOptions as T, isHandshakeResponseMessage as U, type VersionedKey as V, type WireFormat as W, isOperationBatchMessage as X, type YjsDocUpdateMessage as Y, isOperationRejectedMessage as Z, isSyncMessage as _, type SyncMessage as a, operationMatchesQuerySubsets as a0, type SerializedOperation as b, type SyncTransport as c, type TransportMessageHandler as d, type TransportCloseHandler as e, type TransportErrorHandler as f, type BlobChunkResponseMessage as g, type BlobChunkPushMessage as h, type SyncEncryptionConfig as i, type SyncState as j, type SyncStatusInfo as k, type SyncConfig as l, type SyncStatePersistence as m, type SyncQuerySubset as n, type RejectedOperation as o, type AwarenessStateWire as p, type AwarenessUpdateMessage as q, type ErrorMessage as r, type HandshakeResponseMessage as s, type OperationRejectedMessage as t, SYNC_STATES as u, SYNC_STATUSES as v, ScopeViolationError as w, type SyncEncryptionAlgorithm as x, type SyncScopeContext as y, type SyncStatus as z };
+export { isHandshakeResponseMessage as $, type AcknowledgmentMessage as A, type BlobChunkRequestMessage as B, type SyncScopeContext as C, type DeltaCursor as D, type EncryptedPayload as E, type SyncSettlementOptions as F, type SyncSettlementResult as G, type HandshakeMessage as H, InvalidScopeError as I, type SyncStatus as J, dedupeQuerySubsets as K, isAcknowledgmentMessage as L, MemoryRejectedOperationStorage as M, isAwarenessUpdateMessage as N, type OperationBatchMessage as O, isBlobChunkPushMessage as P, type QueueStorage as Q, type RejectedOperationStorage as R, type SyncScopeMap as S, type TransportOptions as T, isBlobChunkRequestMessage as U, type VersionedKey as V, type WireFormat as W, isBlobChunkResponseMessage as X, type YjsDocUpdateMessage as Y, isErrorMessage as Z, isHandshakeMessage as _, type SyncMessage as a, isOperationBatchMessage as a0, isOperationRejectedMessage as a1, isSyncMessage as a2, isYjsDocUpdateMessage as a3, operationMatchesQuerySubsets as a4, querySubsetContains as a5, type SerializedOperation as b, type SyncTransport as c, type TransportMessageHandler as d, type TransportCloseHandler as e, type TransportErrorHandler as f, type BlobChunkResponseMessage as g, type BlobChunkPushMessage as h, type SyncEncryptionConfig as i, type SyncState as j, type SyncStatusInfo as k, type SyncConfig as l, type SyncStatePersistence as m, type SyncQuerySubset as n, type RejectedOperation as o, type ActiveApplyFailure as p, type AwarenessStateWire as q, type AwarenessUpdateMessage as r, type ErrorMessage as s, type HandshakeResponseMessage as t, type OperationRejectedMessage as u, SYNC_STATES as v, SYNC_STATUSES as w, ScopeViolationError as x, type SyncEncryptionAlgorithm as y, type SyncPhase as z };

package/dist/{transport-B2GQerqJ.d.ts → transport-iXX0KA_W.d.ts}

@@ -93,14 +93,27 @@ type SyncState = (typeof SYNC_STATES)[number];
 /**
  * Developer-facing sync status. Simplified view of the internal state.
  */
-declare const SYNC_STATUSES: readonly ["connected", "reconnecting", "syncing", "synced", "offline", "clock-error", "error", "schema-mismatch"];
+declare const SYNC_STATUSES: readonly ["connected", "reconnecting", "syncing", "synced", "offline", "clock-error", "error", "schema-mismatch", "auth-required"];
 type SyncStatus = (typeof SYNC_STATUSES)[number];
+type SyncPhase = 'suspended' | 'offline' | 'connecting' | 'authenticating' | 'handshaking' | 'uploading' | 'receiving' | 'applying' | 'streaming' | 'blocked';
+interface ActiveApplyFailure {
+    operationId: string;
+    collection: string;
+    recordId: string;
+    code: string;
+    message: string;
+    retriable: boolean;
+    firstSeenAt: number;
+    retryCount: number;
+}
 /**
  * Sync status information exposed to developers.
  */
 interface SyncStatusInfo {
     /** Current developer-facing status */
     status: SyncStatus;
+    phase?: SyncPhase;
+    reason?: string;
     /** True when the engine is actively trying to re-establish a transport session. */
     reconnecting: boolean;
     /** Number of operations waiting to be sent */
@@ -115,7 +128,47 @@ interface SyncStatusInfo {
     conflicts: number;
     /** serverTime - localTime in ms measured at the last handshake, or null before first connect. Negative = this device's clock is fast. */
     clockSkewMs: number | null;
+    inFlightUploadOperations?: number;
+    hasInFlightDeliveryBatch?: boolean;
+    activeViewId?: string;
+    activeViewComplete?: boolean;
+    initialSync?: {
+        complete: boolean;
+        receivedBatches: number;
+        totalBatches: number | null;
+        progress: number | null;
+    };
+    deliveryWatermark?: number;
+    serverFrontier?: number | null;
+    blockedFailure?: ActiveApplyFailure | null;
+}
+interface SyncSettlementOptions {
+    upload?: boolean;
+    download?: 'active-view' | false;
+    timeoutMs?: number;
+    signal?: AbortSignal;
 }
+type SyncSettlementResult = {
+    outcome: 'settled';
+    status: SyncStatusInfo;
+} | {
+    outcome: 'offline';
+    status: SyncStatusInfo;
+} | {
+    outcome: 'suspended';
+    reason: string;
+    status: SyncStatusInfo;
+} | {
+    outcome: 'blocked';
+    failure: ActiveApplyFailure;
+    status: SyncStatusInfo;
+} | {
+    outcome: 'timeout';
+    status: SyncStatusInfo;
+} | {
+    outcome: 'aborted';
+    status: SyncStatusInfo;
+};
 /**
  * Per-collection sync scope map. Maps collection names to field-value filters.
  * Empty filter `{}` means no restriction (all records visible).
@@ -134,6 +187,14 @@ interface SyncConfig {
     auth?: () => Promise<{
         token: string;
     }>;
+    /** Auth readiness gate. A suspended result prevents transport creation and retries. */
+    authState?: () => Promise<{
+        state: 'loading' | 'signed-out' | 'anonymous' | 'authenticated';
+        mayConnectAnonymously?: boolean;
+    }>;
+    querySubsets?: {
+        mode?: 'reactive' | 'static' | 'disabled';
+    };
     /** Sync scopes per collection. Limits which records sync to this client. */
     scopes?: Record<string, (ctx: SyncScopeContext) => Record<string, unknown>>;
     /**
@@ -307,10 +368,10 @@ interface SyncQuerySubset {
  * 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.
- */
+/** Canonicalize equality subsets and remove subsets already covered by a broader one. */
 declare function dedupeQuerySubsets(subsets: SyncQuerySubset[]): SyncQuerySubset[];
+/** True when every record selected by `narrow` is also selected by `broad`. */
+declare function querySubsetContains(broad: SyncQuerySubset[], narrow: SyncQuerySubset[]): boolean;
 
 type WireFormat = 'json' | 'protobuf';
 /**
@@ -663,4 +724,4 @@ interface SyncTransport {
     isConnected(): boolean;
 }
 
-export { isYjsDocUpdateMessage as $, type AcknowledgmentMessage as A, type BlobChunkRequestMessage as B, dedupeQuerySubsets as C, type DeltaCursor as D, type EncryptedPayload as E, isAcknowledgmentMessage as F, isAwarenessUpdateMessage as G, type HandshakeMessage as H, InvalidScopeError as I, isBlobChunkPushMessage as J, isBlobChunkRequestMessage as K, isBlobChunkResponseMessage as L, MemoryRejectedOperationStorage as M, isErrorMessage as N, type OperationBatchMessage as O, isHandshakeMessage as P, type QueueStorage as Q, type RejectedOperationStorage as R, type SyncScopeMap as S, type TransportOptions as T, isHandshakeResponseMessage as U, type VersionedKey as V, type WireFormat as W, isOperationBatchMessage as X, type YjsDocUpdateMessage as Y, isOperationRejectedMessage as Z, isSyncMessage as _, type SyncMessage as a, operationMatchesQuerySubsets as a0, type SerializedOperation as b, type SyncTransport as c, type TransportMessageHandler as d, type TransportCloseHandler as e, type TransportErrorHandler as f, type BlobChunkResponseMessage as g, type BlobChunkPushMessage as h, type SyncEncryptionConfig as i, type SyncState as j, type SyncStatusInfo as k, type SyncConfig as l, type SyncStatePersistence as m, type SyncQuerySubset as n, type RejectedOperation as o, type AwarenessStateWire as p, type AwarenessUpdateMessage as q, type ErrorMessage as r, type HandshakeResponseMessage as s, type OperationRejectedMessage as t, SYNC_STATES as u, SYNC_STATUSES as v, ScopeViolationError as w, type SyncEncryptionAlgorithm as x, type SyncScopeContext as y, type SyncStatus as z };
+export { isHandshakeResponseMessage as $, type AcknowledgmentMessage as A, type BlobChunkRequestMessage as B, type SyncScopeContext as C, type DeltaCursor as D, type EncryptedPayload as E, type SyncSettlementOptions as F, type SyncSettlementResult as G, type HandshakeMessage as H, InvalidScopeError as I, type SyncStatus as J, dedupeQuerySubsets as K, isAcknowledgmentMessage as L, MemoryRejectedOperationStorage as M, isAwarenessUpdateMessage as N, type OperationBatchMessage as O, isBlobChunkPushMessage as P, type QueueStorage as Q, type RejectedOperationStorage as R, type SyncScopeMap as S, type TransportOptions as T, isBlobChunkRequestMessage as U, type VersionedKey as V, type WireFormat as W, isBlobChunkResponseMessage as X, type YjsDocUpdateMessage as Y, isErrorMessage as Z, isHandshakeMessage as _, type SyncMessage as a, isOperationBatchMessage as a0, isOperationRejectedMessage as a1, isSyncMessage as a2, isYjsDocUpdateMessage as a3, operationMatchesQuerySubsets as a4, querySubsetContains as a5, type SerializedOperation as b, type SyncTransport as c, type TransportMessageHandler as d, type TransportCloseHandler as e, type TransportErrorHandler as f, type BlobChunkResponseMessage as g, type BlobChunkPushMessage as h, type SyncEncryptionConfig as i, type SyncState as j, type SyncStatusInfo as k, type SyncConfig as l, type SyncStatePersistence as m, type SyncQuerySubset as n, type RejectedOperation as o, type ActiveApplyFailure as p, type AwarenessStateWire as q, type AwarenessUpdateMessage as r, type ErrorMessage as s, type HandshakeResponseMessage as t, type OperationRejectedMessage as u, SYNC_STATES as v, SYNC_STATUSES as w, ScopeViolationError as x, type SyncEncryptionAlgorithm as y, type SyncPhase as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@korajs/sync",
-  "version": "1.0.0-beta.10",
+  "version": "1.0.0-beta.11",
   "description": "Sync protocol and transports for Kora.js with delta sync, causal ordering, and automatic reconnection",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -34,8 +34,8 @@
   ],
   "dependencies": {
     "protobufjs": "^8.0.1",
-    "@korajs/core": "1.0.0-beta.10",
-    "@korajs/merge": "1.0.0-beta.10"
+    "@korajs/core": "1.0.0-beta.11",
+    "@korajs/merge": "1.0.0-beta.11"
   },
   "devDependencies": {
     "@fast-check/vitest": "0.2.0",