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

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

package/dist/{transport-B2GQerqJ.d.cts → transport-CJvRO5ix.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,16 @@ 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';
+    };
+    /** Client-local behavior for records leaving the accepted downlink scope. Defaults to `retain`. */
+    scopeExit?: 'retain' | 'retract';
     /** Sync scopes per collection. Limits which records sync to this client. */
     scopes?: Record<string, (ctx: SyncScopeContext) => Record<string, unknown>>;
     /**
@@ -150,6 +213,10 @@ interface SyncConfig {
      * Defaults to 30000ms. Set to 0 to disable the watchdog.
      */
     outboundAckTimeoutMs?: number;
+    /** Initial delay before resending a transiently rejected outbound operation. Defaults to 250ms. */
+    outboundRetryBaseDelayMs?: number;
+    /** Maximum transient-operation retry delay. Defaults to 30000ms. */
+    outboundRetryMaxDelayMs?: number;
     /** Initial reconnection delay in ms. Defaults to 1000. */
     reconnectInterval?: number;
     /** Maximum reconnection delay in ms. Defaults to 30000. */
@@ -307,10 +374,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';
 /**
@@ -362,6 +429,8 @@ interface HandshakeMessage {
      * cursor for the server->client direction. Optional, so old servers ignore it.
      */
     lastDeliverySequence?: number;
+    /** Opt in to client-local removal when records leave the accepted downlink view. */
+    scopeExitPolicy?: 'retain' | 'retract';
 }
 /**
  * Server response to a handshake.
@@ -381,6 +450,10 @@ interface HandshakeResponseMessage {
     selectedWireFormat?: WireFormat;
     /** The server-accepted per-collection sync scope. Confirms what data will be synced. */
     acceptedScope?: Record<string, Record<string, unknown>>;
+    /** Server-authoritative scope for records delivered to this client. */
+    acceptedDownlinkScopes?: Record<string, Record<string, unknown>>;
+    /** Server-authoritative scope for operations uploaded by this client. */
+    acceptedUplinkScopes?: Record<string, Record<string, unknown>>;
     /** Server wall-clock time (ms since epoch) at response creation. Lets clients measure their own clock skew. */
     serverTime?: number;
     /**
@@ -404,6 +477,8 @@ interface OperationBatchMessage {
     type: 'operation-batch';
     messageId: string;
     operations: SerializedOperation[];
+    /** Client-local authorization removals; these are never domain delete operations. */
+    retractions?: ScopeRetraction[];
     /** True if this is the last batch in the delta exchange phase */
     isFinal: boolean;
     /** Index of this batch (0-based) for ordering */
@@ -427,6 +502,10 @@ interface OperationBatchMessage {
     baseDeliverySequence?: number;
     maxDeliverySequence?: number;
 }
+interface ScopeRetraction {
+    collection: string;
+    recordId: string;
+}
 /**
  * Acknowledgment of a received message.
  */
@@ -663,4 +742,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-CJvRO5ix.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,16 @@ 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';
+    };
+    /** Client-local behavior for records leaving the accepted downlink scope. Defaults to `retain`. */
+    scopeExit?: 'retain' | 'retract';
     /** Sync scopes per collection. Limits which records sync to this client. */
     scopes?: Record<string, (ctx: SyncScopeContext) => Record<string, unknown>>;
     /**
@@ -150,6 +213,10 @@ interface SyncConfig {
      * Defaults to 30000ms. Set to 0 to disable the watchdog.
      */
     outboundAckTimeoutMs?: number;
+    /** Initial delay before resending a transiently rejected outbound operation. Defaults to 250ms. */
+    outboundRetryBaseDelayMs?: number;
+    /** Maximum transient-operation retry delay. Defaults to 30000ms. */
+    outboundRetryMaxDelayMs?: number;
     /** Initial reconnection delay in ms. Defaults to 1000. */
     reconnectInterval?: number;
     /** Maximum reconnection delay in ms. Defaults to 30000. */
@@ -307,10 +374,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';
 /**
@@ -362,6 +429,8 @@ interface HandshakeMessage {
      * cursor for the server->client direction. Optional, so old servers ignore it.
      */
     lastDeliverySequence?: number;
+    /** Opt in to client-local removal when records leave the accepted downlink view. */
+    scopeExitPolicy?: 'retain' | 'retract';
 }
 /**
  * Server response to a handshake.
@@ -381,6 +450,10 @@ interface HandshakeResponseMessage {
     selectedWireFormat?: WireFormat;
     /** The server-accepted per-collection sync scope. Confirms what data will be synced. */
     acceptedScope?: Record<string, Record<string, unknown>>;
+    /** Server-authoritative scope for records delivered to this client. */
+    acceptedDownlinkScopes?: Record<string, Record<string, unknown>>;
+    /** Server-authoritative scope for operations uploaded by this client. */
+    acceptedUplinkScopes?: Record<string, Record<string, unknown>>;
     /** Server wall-clock time (ms since epoch) at response creation. Lets clients measure their own clock skew. */
     serverTime?: number;
     /**
@@ -404,6 +477,8 @@ interface OperationBatchMessage {
     type: 'operation-batch';
     messageId: string;
     operations: SerializedOperation[];
+    /** Client-local authorization removals; these are never domain delete operations. */
+    retractions?: ScopeRetraction[];
     /** True if this is the last batch in the delta exchange phase */
     isFinal: boolean;
     /** Index of this batch (0-based) for ordering */
@@ -427,6 +502,10 @@ interface OperationBatchMessage {
     baseDeliverySequence?: number;
     maxDeliverySequence?: number;
 }
+interface ScopeRetraction {
+    collection: string;
+    recordId: string;
+}
 /**
  * Acknowledgment of a received message.
  */
@@ -663,4 +742,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.12",
   "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.12",
+    "@korajs/merge": "1.0.0-beta.12"
   },
   "devDependencies": {
     "@fast-check/vitest": "0.2.0",