@korajs/sync 1.0.0-beta.4 → 1.0.0-beta.5

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { S as SyncScopeMap, D as DeltaCursor, a as SyncMessage, b as SerializedOperation, W as WireFormat, c as SyncTransport, T as TransportOptions, d as TransportMessageHandler, e as TransportCloseHandler, f as TransportErrorHandler, B as BlobChunkRequestMessage, g as BlobChunkResponseMessage, h as BlobChunkPushMessage, i as SyncEncryptionConfig, V as VersionedKey, Y as YjsDocUpdateMessage, Q as QueueStorage, j as SyncState, k as SyncStatusInfo, l as SyncConfig, R as RejectedOperationStorage, m as SyncStatePersistence, n as SyncQuerySubset, o as RejectedOperation } from './transport-BGr-_eH8.cjs';
-export { A as AcknowledgmentMessage, p as AwarenessStateWire, q as AwarenessUpdateMessage, E as EncryptedPayload, r as ErrorMessage, H as HandshakeMessage, s as HandshakeResponseMessage, I as InvalidScopeError, M as MemoryRejectedOperationStorage, O as OperationBatchMessage, t as OperationRejectedMessage, u as SYNC_STATES, v as SYNC_STATUSES, w as ScopeViolationError, x as SyncEncryptionAlgorithm, y as SyncScopeContext, z as SyncStatus, C as dedupeQuerySubsets, F as isAcknowledgmentMessage, G as isAwarenessUpdateMessage, J as isBlobChunkPushMessage, K as isBlobChunkRequestMessage, L as isBlobChunkResponseMessage, N as isErrorMessage, P as isHandshakeMessage, U as isHandshakeResponseMessage, X as isOperationBatchMessage, Z as isOperationRejectedMessage, _ as isSyncMessage, $ as isYjsDocUpdateMessage, a0 as operationMatchesQuerySubsets } from './transport-BGr-_eH8.cjs';
+import { S as SyncScopeMap, D as DeltaCursor, a as SyncMessage, b as SerializedOperation, W as WireFormat, c as SyncTransport, T as TransportOptions, d as TransportMessageHandler, e as TransportCloseHandler, f as TransportErrorHandler, B as BlobChunkRequestMessage, g as BlobChunkResponseMessage, h as BlobChunkPushMessage, i as SyncEncryptionConfig, V as VersionedKey, Y as YjsDocUpdateMessage, Q as QueueStorage, j as SyncState, k as SyncStatusInfo, l as SyncConfig, R as RejectedOperationStorage, m as SyncStatePersistence, n as SyncQuerySubset, o as RejectedOperation } from './transport-DXmZ8kyI.cjs';
+export { A as AcknowledgmentMessage, p as AwarenessStateWire, q as AwarenessUpdateMessage, E as EncryptedPayload, r as ErrorMessage, H as HandshakeMessage, s as HandshakeResponseMessage, I as InvalidScopeError, M as MemoryRejectedOperationStorage, O as OperationBatchMessage, t as OperationRejectedMessage, u as SYNC_STATES, v as SYNC_STATUSES, w as ScopeViolationError, x as SyncEncryptionAlgorithm, y as SyncScopeContext, z as SyncStatus, C as dedupeQuerySubsets, F as isAcknowledgmentMessage, G as isAwarenessUpdateMessage, J as isBlobChunkPushMessage, K as isBlobChunkRequestMessage, L as isBlobChunkResponseMessage, N as isErrorMessage, P as isHandshakeMessage, U as isHandshakeResponseMessage, X as isOperationBatchMessage, Z as isOperationRejectedMessage, _ as isSyncMessage, $ as isYjsDocUpdateMessage, a0 as operationMatchesQuerySubsets } from './transport-DXmZ8kyI.cjs';
 import * as _korajs_core from '@korajs/core';
 import { Operation, VersionVector, ApplyResult, KoraEventEmitter, TimeSource, SyncError, ConnectionQuality } from '@korajs/core';
 export { ApplyFailureReason, ApplyResult } from '@korajs/core';
@@ -95,6 +95,17 @@ interface SyncStore {
         idMapping: Record<string, string>;
         rebasedCount: number;
     }>;
+    /**
+     * Optional: read a record's current materialized field values, used to backfill
+     * scope / query-subset fields that a partial update (or a delete) does not carry
+     * in its own data. Without it, such an operation would be judged out of scope by
+     * its changed fields alone and wrongly dropped from sync. Optional so hand-rolled
+     * SyncStore implementations keep working; when absent, the engine falls back to
+     * judging visibility from the operation's own data.
+     *
+     * @returns the record's fields, or null when it cannot be read.
+     */
+    readRecordFields?(collection: string, recordId: string): Promise<Record<string, unknown> | null>;
 }
 
 /** Prefix for handshake rejection when client schema version is unsupported. */
@@ -272,6 +283,14 @@ interface ChaosConfig {
     maxLatency?: number;
     /** Injectable random source for deterministic testing. Returns value in [0, 1). */
     randomSource?: () => number;
+    /**
+     * Deterministic targeted drop. When it returns true for a message and direction,
+     * that message is dropped unconditionally (independent of `dropRate`). Enables
+     * reproducing an exact gap (e.g. drop one specific operation) instead of relying
+     * on probabilistic drops. `direction` is 'outgoing' for `send` and 'incoming' for
+     * messages arriving from the inner transport.
+     */
+    dropPredicate?: (message: SyncMessage, direction: 'outgoing' | 'incoming') => boolean;
 }
 /**
  * Chaos transport that wraps another transport and injects faults.
@@ -287,6 +306,7 @@ declare class ChaosTransport implements SyncTransport {
     private readonly reorderRate;
     private readonly maxLatency;
     private readonly random;
+    private readonly dropPredicate;
     private messageHandler;
     private reorderBuffer;
     private pending;
@@ -964,6 +984,25 @@ declare class SyncEngine {
     /** Resume cursor for paginated initial sync (persisted across reconnects) */
     private resumeDeltaCursor;
     private initialSyncTotalBatches;
+    /**
+     * The delivery watermark for the CURRENT sync view: the highest server delivery
+     * sequence up to which every operation in the current view (scope + active query
+     * subscriptions) has been contiguously applied. Advanced only through the server's
+     * gap-free delivery stream (never through live relay), so it is a durable lower bound
+     * on what this client holds for this view. Reported at handshake to resume the stream.
+     *
+     * The watermark is keyed by view: switching views (a scope or subscription change)
+     * saves the current view's watermark and loads the target view's, so returning to a
+     * previously-synced view resumes exactly where it left off instead of re-syncing. This
+     * is correct because a view's watermark is a lower bound specific to that view's
+     * filter; a widened view is simply a different (initially unsynced) view.
+     */
+    private deliveryWatermark;
+    /**
+     * In-memory cache of watermark per view signature, preloaded from persistence at start
+     * so a view switch resolves synchronously (no race with the reconnect it triggers).
+     */
+    private readonly deliverySignatureWatermarks;
     constructor(options: SyncEngineOptions);
     /**
      * Start the sync engine: connect → handshake → delta exchange → streaming.
@@ -1056,6 +1095,41 @@ declare class SyncEngine {
      * @param scopeMap - New per-collection scope filters, or undefined to remove scope
      */
     updateScope(scopeMap: SyncScopeMap | undefined): void;
+    /**
+     * A stable identifier for the current sync view: the auth/tenant scope plus the set of
+     * active query subscriptions, canonicalized so the same view always produces the same
+     * string. The delivery watermark is keyed by this, so each distinct view resumes from
+     * its own last position.
+     */
+    private deliverySignature;
+    /**
+     * Switch the active delivery watermark to the current view after a scope or subscription
+     * change. The prior view's watermark is saved so returning to it resumes; the new view's
+     * watermark is restored from the in-memory cache (0 for a never-synced view, which then
+     * does a one-time resync under that view). No data is lost: a view's watermark is a lower
+     * bound for that specific view's filter.
+     */
+    private switchDeliveryView;
+    /**
+     * Record a view's watermark in the in-memory cache as the most-recently-used entry (the
+     * Map preserves insertion order, so re-inserting moves it to the tail), then evict cold
+     * views past the retention cap. This is the single place the cache is written, so LRU
+     * order and the size bound are always maintained together.
+     */
+    private setViewWatermark;
+    /**
+     * Trim the per-view watermark cache to `MAX_DELIVERY_VIEW_WATERMARKS`, evicting the
+     * least-recently-used views. The default view ('') and the live view are never evicted
+     * (evicting the live view would force an immediate re-scan of what we are actively
+     * syncing). Each eviction also removes the persisted row, bounding storage. Safe by
+     * construction: an evicted view simply back-fills from 0 (deduplicated) when next seen.
+     */
+    private evictColdViewWatermarks;
+    /**
+     * Remove a view's persisted watermark row (best-effort; a persistence layer that omits
+     * the delete simply keeps the row, which is harmless).
+     */
+    private deleteDeliveryWatermark;
     /**
      * Get the currently active scope map. Returns undefined if no scope is configured.
      */
@@ -1119,6 +1193,8 @@ declare class SyncEngine {
     private markDeltaSendCompleteIfReady;
     private collectDelta;
     private handleOperationBatch;
+    /** Acknowledge a delivery batch (used for duplicates) without re-applying it. */
+    private sendDeliveryAck;
     private handleAcknowledgment;
     private handleError;
     /**
@@ -1166,7 +1242,11 @@ declare class SyncEngine {
     private transitionTo;
     private setSerializerWireFormat;
     private operationAllowedForSync;
+    private matchesScopeAndSubsets;
+    private readRecordForBackfill;
+    private filterAllowedForSync;
     private persistDeltaCursor;
+    private persistDeliveryWatermark;
     private scheduleQuerySubsetReconnect;
     private reconnectForQuerySubsets;
 }

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { S as SyncScopeMap, D as DeltaCursor, a as SyncMessage, b as SerializedOperation, W as WireFormat, c as SyncTransport, T as TransportOptions, d as TransportMessageHandler, e as TransportCloseHandler, f as TransportErrorHandler, B as BlobChunkRequestMessage, g as BlobChunkResponseMessage, h as BlobChunkPushMessage, i as SyncEncryptionConfig, V as VersionedKey, Y as YjsDocUpdateMessage, Q as QueueStorage, j as SyncState, k as SyncStatusInfo, l as SyncConfig, R as RejectedOperationStorage, m as SyncStatePersistence, n as SyncQuerySubset, o as RejectedOperation } from './transport-BGr-_eH8.js';
-export { A as AcknowledgmentMessage, p as AwarenessStateWire, q as AwarenessUpdateMessage, E as EncryptedPayload, r as ErrorMessage, H as HandshakeMessage, s as HandshakeResponseMessage, I as InvalidScopeError, M as MemoryRejectedOperationStorage, O as OperationBatchMessage, t as OperationRejectedMessage, u as SYNC_STATES, v as SYNC_STATUSES, w as ScopeViolationError, x as SyncEncryptionAlgorithm, y as SyncScopeContext, z as SyncStatus, C as dedupeQuerySubsets, F as isAcknowledgmentMessage, G as isAwarenessUpdateMessage, J as isBlobChunkPushMessage, K as isBlobChunkRequestMessage, L as isBlobChunkResponseMessage, N as isErrorMessage, P as isHandshakeMessage, U as isHandshakeResponseMessage, X as isOperationBatchMessage, Z as isOperationRejectedMessage, _ as isSyncMessage, $ as isYjsDocUpdateMessage, a0 as operationMatchesQuerySubsets } from './transport-BGr-_eH8.js';
+import { S as SyncScopeMap, D as DeltaCursor, a as SyncMessage, b as SerializedOperation, W as WireFormat, c as SyncTransport, T as TransportOptions, d as TransportMessageHandler, e as TransportCloseHandler, f as TransportErrorHandler, B as BlobChunkRequestMessage, g as BlobChunkResponseMessage, h as BlobChunkPushMessage, i as SyncEncryptionConfig, V as VersionedKey, Y as YjsDocUpdateMessage, Q as QueueStorage, j as SyncState, k as SyncStatusInfo, l as SyncConfig, R as RejectedOperationStorage, m as SyncStatePersistence, n as SyncQuerySubset, o as RejectedOperation } from './transport-DXmZ8kyI.js';
+export { A as AcknowledgmentMessage, p as AwarenessStateWire, q as AwarenessUpdateMessage, E as EncryptedPayload, r as ErrorMessage, H as HandshakeMessage, s as HandshakeResponseMessage, I as InvalidScopeError, M as MemoryRejectedOperationStorage, O as OperationBatchMessage, t as OperationRejectedMessage, u as SYNC_STATES, v as SYNC_STATUSES, w as ScopeViolationError, x as SyncEncryptionAlgorithm, y as SyncScopeContext, z as SyncStatus, C as dedupeQuerySubsets, F as isAcknowledgmentMessage, G as isAwarenessUpdateMessage, J as isBlobChunkPushMessage, K as isBlobChunkRequestMessage, L as isBlobChunkResponseMessage, N as isErrorMessage, P as isHandshakeMessage, U as isHandshakeResponseMessage, X as isOperationBatchMessage, Z as isOperationRejectedMessage, _ as isSyncMessage, $ as isYjsDocUpdateMessage, a0 as operationMatchesQuerySubsets } from './transport-DXmZ8kyI.js';
 import * as _korajs_core from '@korajs/core';
 import { Operation, VersionVector, ApplyResult, KoraEventEmitter, TimeSource, SyncError, ConnectionQuality } from '@korajs/core';
 export { ApplyFailureReason, ApplyResult } from '@korajs/core';
@@ -95,6 +95,17 @@ interface SyncStore {
         idMapping: Record<string, string>;
         rebasedCount: number;
     }>;
+    /**
+     * Optional: read a record's current materialized field values, used to backfill
+     * scope / query-subset fields that a partial update (or a delete) does not carry
+     * in its own data. Without it, such an operation would be judged out of scope by
+     * its changed fields alone and wrongly dropped from sync. Optional so hand-rolled
+     * SyncStore implementations keep working; when absent, the engine falls back to
+     * judging visibility from the operation's own data.
+     *
+     * @returns the record's fields, or null when it cannot be read.
+     */
+    readRecordFields?(collection: string, recordId: string): Promise<Record<string, unknown> | null>;
 }
 
 /** Prefix for handshake rejection when client schema version is unsupported. */
@@ -272,6 +283,14 @@ interface ChaosConfig {
     maxLatency?: number;
     /** Injectable random source for deterministic testing. Returns value in [0, 1). */
     randomSource?: () => number;
+    /**
+     * Deterministic targeted drop. When it returns true for a message and direction,
+     * that message is dropped unconditionally (independent of `dropRate`). Enables
+     * reproducing an exact gap (e.g. drop one specific operation) instead of relying
+     * on probabilistic drops. `direction` is 'outgoing' for `send` and 'incoming' for
+     * messages arriving from the inner transport.
+     */
+    dropPredicate?: (message: SyncMessage, direction: 'outgoing' | 'incoming') => boolean;
 }
 /**
  * Chaos transport that wraps another transport and injects faults.
@@ -287,6 +306,7 @@ declare class ChaosTransport implements SyncTransport {
     private readonly reorderRate;
     private readonly maxLatency;
     private readonly random;
+    private readonly dropPredicate;
     private messageHandler;
     private reorderBuffer;
     private pending;
@@ -964,6 +984,25 @@ declare class SyncEngine {
     /** Resume cursor for paginated initial sync (persisted across reconnects) */
     private resumeDeltaCursor;
     private initialSyncTotalBatches;
+    /**
+     * The delivery watermark for the CURRENT sync view: the highest server delivery
+     * sequence up to which every operation in the current view (scope + active query
+     * subscriptions) has been contiguously applied. Advanced only through the server's
+     * gap-free delivery stream (never through live relay), so it is a durable lower bound
+     * on what this client holds for this view. Reported at handshake to resume the stream.
+     *
+     * The watermark is keyed by view: switching views (a scope or subscription change)
+     * saves the current view's watermark and loads the target view's, so returning to a
+     * previously-synced view resumes exactly where it left off instead of re-syncing. This
+     * is correct because a view's watermark is a lower bound specific to that view's
+     * filter; a widened view is simply a different (initially unsynced) view.
+     */
+    private deliveryWatermark;
+    /**
+     * In-memory cache of watermark per view signature, preloaded from persistence at start
+     * so a view switch resolves synchronously (no race with the reconnect it triggers).
+     */
+    private readonly deliverySignatureWatermarks;
     constructor(options: SyncEngineOptions);
     /**
      * Start the sync engine: connect → handshake → delta exchange → streaming.
@@ -1056,6 +1095,41 @@ declare class SyncEngine {
      * @param scopeMap - New per-collection scope filters, or undefined to remove scope
      */
     updateScope(scopeMap: SyncScopeMap | undefined): void;
+    /**
+     * A stable identifier for the current sync view: the auth/tenant scope plus the set of
+     * active query subscriptions, canonicalized so the same view always produces the same
+     * string. The delivery watermark is keyed by this, so each distinct view resumes from
+     * its own last position.
+     */
+    private deliverySignature;
+    /**
+     * Switch the active delivery watermark to the current view after a scope or subscription
+     * change. The prior view's watermark is saved so returning to it resumes; the new view's
+     * watermark is restored from the in-memory cache (0 for a never-synced view, which then
+     * does a one-time resync under that view). No data is lost: a view's watermark is a lower
+     * bound for that specific view's filter.
+     */
+    private switchDeliveryView;
+    /**
+     * Record a view's watermark in the in-memory cache as the most-recently-used entry (the
+     * Map preserves insertion order, so re-inserting moves it to the tail), then evict cold
+     * views past the retention cap. This is the single place the cache is written, so LRU
+     * order and the size bound are always maintained together.
+     */
+    private setViewWatermark;
+    /**
+     * Trim the per-view watermark cache to `MAX_DELIVERY_VIEW_WATERMARKS`, evicting the
+     * least-recently-used views. The default view ('') and the live view are never evicted
+     * (evicting the live view would force an immediate re-scan of what we are actively
+     * syncing). Each eviction also removes the persisted row, bounding storage. Safe by
+     * construction: an evicted view simply back-fills from 0 (deduplicated) when next seen.
+     */
+    private evictColdViewWatermarks;
+    /**
+     * Remove a view's persisted watermark row (best-effort; a persistence layer that omits
+     * the delete simply keeps the row, which is harmless).
+     */
+    private deleteDeliveryWatermark;
     /**
      * Get the currently active scope map. Returns undefined if no scope is configured.
      */
@@ -1119,6 +1193,8 @@ declare class SyncEngine {
     private markDeltaSendCompleteIfReady;
     private collectDelta;
     private handleOperationBatch;
+    /** Acknowledge a delivery batch (used for duplicates) without re-applying it. */
+    private sendDeliveryAck;
     private handleAcknowledgment;
     private handleError;
     /**
@@ -1166,7 +1242,11 @@ declare class SyncEngine {
     private transitionTo;
     private setSerializerWireFormat;
     private operationAllowedForSync;
+    private matchesScopeAndSubsets;
+    private readRecordForBackfill;
+    private filterAllowedForSync;
     private persistDeltaCursor;
+    private persistDeliveryWatermark;
     private scheduleQuerySubsetReconnect;
     private reconnectForQuerySubsets;
 }