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

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, g as SyncEncryptionConfig, V as VersionedKey, Y as YjsDocUpdateMessage, Q as QueueStorage, h as SyncState, i as SyncStatusInfo, j as SyncConfig, k as SyncStatePersistence, l as SyncQuerySubset } from './transport-BMesMB6s.js';
-export { A as AcknowledgmentMessage, m as AwarenessStateWire, n as AwarenessUpdateMessage, E as EncryptedPayload, o as ErrorMessage, H as HandshakeMessage, p as HandshakeResponseMessage, I as InvalidScopeError, O as OperationBatchMessage, q as SYNC_STATES, r as SYNC_STATUSES, s as ScopeViolationError, t as SyncEncryptionAlgorithm, u as SyncScopeContext, v as SyncStatus, w as dedupeQuerySubsets, x as isAcknowledgmentMessage, y as isAwarenessUpdateMessage, z as isErrorMessage, B as isHandshakeMessage, C as isHandshakeResponseMessage, F as isOperationBatchMessage, G as isSyncMessage, J as isYjsDocUpdateMessage, K as operationMatchesQuerySubsets } from './transport-BMesMB6s.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-B2GQerqJ.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-B2GQerqJ.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;
@@ -470,6 +490,71 @@ declare class AwarenessManager {
     private emitAwarenessEvent;
 }
 
+/**
+ * A blob-chunk message in decoded form (chunk bytes as a `Uint8Array` rather
+ * than the base64 wire string). This is the shape callers of the channel work
+ * with; the channel handles base64 encode/decode at the wire boundary.
+ *
+ * The shape mirrors `@korajs/store`'s `ChunkMessage` so an app-layer adapter can
+ * bridge the two with no field translation.
+ */
+type BlobChunkChannelMessage = {
+    type: 'blob-chunk-request';
+    requestId: string;
+    hash: string;
+} | {
+    type: 'blob-chunk-response';
+    requestId: string;
+    bytes: Uint8Array | null;
+} | {
+    type: 'blob-chunk-push';
+    hash: string;
+    bytes: Uint8Array;
+};
+/** Encode chunk bytes to a base64 string for the JSON wire. */
+declare function encodeBlobChunkBytes(bytes: Uint8Array): string;
+/** Decode base64 chunk bytes from the wire back to a `Uint8Array`. */
+declare function decodeBlobChunkBytes(encoded: string): Uint8Array;
+interface BlobChunkChannelOptions {
+    /**
+     * Called when a local blob-chunk message should go out on the wire. The
+     * caller (the sync engine) decides whether the connection is ready to send.
+     */
+    onSend?: (message: BlobChunkRequestMessage | BlobChunkResponseMessage | BlobChunkPushMessage) => void;
+}
+/**
+ * Ephemeral side channel for out-of-band blob chunk transfer over the sync
+ * connection. Symmetric: a peer can both request chunks it needs and answer
+ * requests for chunks it holds. Never persisted in the operation log — durable
+ * state is the `BlobRef` inside a record's fields; this channel only moves the
+ * referenced bytes.
+ *
+ * The channel owns the base64 wire encoding so callers work purely in
+ * `Uint8Array`, and its {@link BlobChunkChannelMessage} shape mirrors
+ * `@korajs/store`'s `ChunkMessage` so the app layer can expose it as a
+ * `ChunkMessagePort` without translating fields.
+ */
+declare class BlobChunkChannel {
+    private readonly onSend;
+    private readonly handlers;
+    constructor(options?: BlobChunkChannelOptions);
+    /**
+     * Send a blob-chunk message to the peer. Response bytes are base64-encoded
+     * onto the wire here; callers pass a `Uint8Array`.
+     */
+    send(message: BlobChunkChannelMessage): void;
+    /**
+     * Register a handler for inbound blob-chunk messages. Multiple handlers are
+     * allowed; each receives every delivered message.
+     */
+    onMessage(handler: (message: BlobChunkChannelMessage) => void): () => void;
+    /**
+     * Deliver an inbound wire message to registered handlers, decoding response
+     * bytes from base64 back to a `Uint8Array` first.
+     */
+    deliver(message: BlobChunkRequestMessage | BlobChunkResponseMessage | BlobChunkPushMessage): void;
+}
+
 /**
  * Configuration for the SyncMetricsCollector.
  */
@@ -740,6 +825,13 @@ declare class OutboundQueue {
      * Acknowledge a batch, removing its operations permanently.
      */
     acknowledge(batchId: string): Promise<void>;
+    /**
+     * Acknowledge only operations in an in-flight batch whose local sequence number is
+     * covered by the server's ack. Any later operations return to the front of the
+     * queue for retry. This is required when the server accepts a prefix but rejects a
+     * later operation retriably (for example a stale-scope push after auth changed).
+     */
+    acknowledgeThrough(batchId: string, lastSequenceNumber: number): Promise<void>;
     /**
      * Return a failed batch to the front of the queue for retry.
      * Prepends the operations to maintain priority.
@@ -779,6 +871,14 @@ declare class OutboundQueue {
      * Whether initialize() has been called.
      */
     get isInitialized(): boolean;
+    /**
+     * Remove a single operation the server permanently rejected — from the queue,
+     * from any in-flight batch, and from durable storage — so a later batch ack or
+     * a reconnect `returnBatch` can never resend or resurrect it. Returns the
+     * removed operation so the caller can record it in a durable rejected store,
+     * or null if it was not present (already acknowledged and removed).
+     */
+    reject(opId: string): Promise<Operation | null>;
     /**
      * Remove operations by id from queue and persistent storage.
      * Used when ops were already sent during handshake delta exchange.
@@ -802,6 +902,11 @@ interface SyncEngineOptions {
     emitter?: KoraEventEmitter;
     /** Queue storage for persistent outbound queue. Defaults to in-memory. */
     queueStorage?: QueueStorage;
+    /**
+     * Durable storage for operations the server rejected. Defaults to in-memory.
+     * Provide a store-backed implementation so rejections survive a page refresh.
+     */
+    rejectedStorage?: RejectedOperationStorage;
     /**
      * Optional encryptor for end-to-end encryption.
      * When provided, `data` and `previousData` fields of operations are encrypted
@@ -829,6 +934,8 @@ interface SyncDiagnostics {
     pendingOperations: number;
     hasInFlightBatch: boolean;
     reconnecting: boolean;
+    deliveryWatermark: number;
+    deliveryGapRepeatCount: number;
     timestamp: number;
 }
 /**
@@ -846,10 +953,13 @@ declare class SyncEngine {
     private readonly serializer;
     private readonly emitter;
     private readonly outboundQueue;
+    private readonly rejectedStorage;
     private readonly batchSize;
+    private readonly outboundAckTimeoutMs;
     private readonly encryptor;
     private readonly awarenessManager;
     private readonly richtextDocChannel;
+    private readonly blobChunkChannel;
     private readonly metricsCollector;
     private readonly syncState;
     private remoteVector;
@@ -860,10 +970,16 @@ declare class SyncEngine {
     private lastSuccessfulPull;
     private conflictCount;
     private currentBatch;
+    private currentBatchRequiresPartialAck;
     private reconnecting;
     private schemaBlocked;
     private clockBlocked;
     private clockSkewMs;
+    private blobStorageEnabled;
+    private outboundAckTimer;
+    private startPromise;
+    private stopPromise;
+    private reconnectPromise;
     private deltaBatchesReceived;
     private deltaReceiveComplete;
     private deltaSendComplete;
@@ -883,15 +999,38 @@ 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;
+    private deliveryGapRepeatCount;
+    private lastDeliveryGapKey;
     constructor(options: SyncEngineOptions);
     /**
      * Start the sync engine: connect → handshake → delta exchange → streaming.
      */
     start(): Promise<void>;
+    private startInternal;
     /**
      * Stop the sync engine. Disconnects the transport.
      */
     stop(): Promise<void>;
+    private stopInternal;
     private ensureDisconnected;
     /**
      * Push a local operation to the outbound queue.
@@ -949,6 +1088,13 @@ declare class SyncEngine {
      * or in error state, restarts the sync. If already connected, no-op.
      */
     retryNow(): Promise<void>;
+    /**
+     * Atomically refresh the transport session. Overlapping callers share one
+     * reconnect, in-flight outbound batches are returned to the queue by stop(), and the
+     * next start handshakes with the latest auth token, sync scope, and query subsets.
+     */
+    reconnect(): Promise<void>;
+    private reconnectInternal;
     /**
      * Export a diagnostics snapshot for debugging and support tickets.
      * Contains connection state, timing info, and queue metrics.
@@ -975,6 +1121,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.
      */
@@ -998,6 +1179,22 @@ declare class SyncEngine {
      * Optional side channel for incremental Yjs updates on large richtext fields.
      */
     getRichtextDocChannel(): RichtextDocChannel;
+    /**
+     * Side channel for out-of-band blob chunk transfer over the sync connection.
+     * The app layer bridges this to a `ChunkMessagePort` to pull/serve blob bytes.
+     */
+    getBlobChunkChannel(): BlobChunkChannel;
+    /**
+     * Whether the connected server persists blob bytes centrally (learned from the
+     * handshake response). When true, the app uploads the bytes behind `blob`
+     * fields so they stay available after the authoring device goes offline.
+     */
+    isBlobStorageEnabled(): boolean;
+    /**
+     * Upload a blob chunk (or manifest) to the server for central persistence.
+     * A no-op unless connected and the server advertised blob storage.
+     */
+    uploadBlobChunk(hash: string, bytes: Uint8Array): void;
     private messageChain;
     private enqueueMessage;
     private handleMessageAsync;
@@ -1022,8 +1219,29 @@ 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;
+    /**
+     * Handle a per-operation rejection: divert the op out of the pending outbound
+     * queue (so it is never retried or resurrected on reconnect), record it in the
+     * durable rejected store (so it is kept and explainable), and emit an event so
+     * the app can reconcile. Unlike {@link handleError}, this is a normal per-op
+     * signal, so the connection stays up.
+     */
+    private handleOperationRejected;
+    /**
+     * Every operation the server rejected that has not yet been reconciled. The app
+     * uses this (alongside the `sync:operation-rejected` event) to surface failed
+     * submissions and decide whether to roll back or resubmit.
+     */
+    getRejectedOperations(): Promise<RejectedOperation[]>;
+    /**
+     * Forget rejected operations by id once the app has reconciled them (rolled the
+     * optimistic write back or resubmitted a corrected op).
+     */
+    clearRejectedOperations(operationIds: string[]): Promise<void>;
     private checkDeltaComplete;
     /**
      * Effective server vector: persisted last-ack merged with live handshake remote vector.
@@ -1044,13 +1262,20 @@ declare class SyncEngine {
      */
     private reconcileOutboundFromOpLog;
     private flushQueue;
+    private startOutboundAckTimer;
+    private clearOutboundAckTimer;
+    private handleOutboundAckTimeout;
     private handleAwarenessUpdate;
     private handleTransportClose;
     private handleTransportError;
     private transitionTo;
     private setSerializerWireFormat;
     private operationAllowedForSync;
+    private matchesScopeAndSubsets;
+    private readRecordForBackfill;
+    private filterAllowedForSync;
     private persistDeltaCursor;
+    private persistDeliveryWatermark;
     private scheduleQuerySubsetReconnect;
     private reconnectForQuerySubsets;
 }
@@ -1292,4 +1517,4 @@ declare function getRemoteAwarenessStates(awareness: AwarenessManager): Awarenes
  */
 declare function subscribeRemoteAwarenessStates(awareness: AwarenessManager, listener: (states: AwarenessState[]) => void): () => void;
 
-export { type AwarenessChange, type AwarenessCursor, AwarenessManager, type AwarenessMessage, type AwarenessState, type AwarenessUser, type ChaosConfig, ChaosTransport, ConnectionMonitor, type ConnectionMonitorConfig, type CursorInfo, DEFAULT_RICHTEXT_DOC_CHANNEL_THRESHOLD, DecryptionError, DeltaCursor, EncryptionError, HttpLongPollingTransport, type HttpLongPollingTransportOptions, JsonMessageSerializer, KeyDerivationError, type MessageSerializer, NegotiatedMessageSerializer, OFFLINE_SYNC_STATUS, type OutboundBatch, OutboundQueue, ProtobufMessageSerializer, QueueStorage, type ReconnectionConfig, ReconnectionManager, RichtextDocChannel, type RichtextDocChannelOptions, type RichtextDocListener, SCHEMA_MISMATCH_PREFIX, SerializedOperation, SyncConfig, type SyncDiagnostics, SyncEncryptionConfig, SyncEncryptor, SyncEngine, type SyncEngineOptions, SyncMessage, SyncQuerySubset, SyncScopeMap, SyncState, SyncStatePersistence, type SyncStatusController, type SyncStatusControllerOptions, SyncStatusInfo, type SyncStore, SyncTransport, TransportCloseHandler, TransportErrorHandler, TransportMessageHandler, TransportOptions, VersionedKey, type WebSocketConstructor, type WebSocketLike, WebSocketTransport, type WebSocketTransportOptions, WireFormat, YjsDocUpdateMessage, createDeltaCursorFromBatch, createSyncStatusController, decodeDeltaCursor, decodeYjsUpdate, deriveKey, deriveVersionedKey, encodeDeltaCursor, encodeYjsUpdate, filterOperationsByScope, generateSalt, getRemoteAwarenessStates, isClientSchemaVersionSupported, isEncryptedPayload, isSchemaMismatchReject, operationMatchesScope, richtextDocKey, sliceOperationsAfterCursor, subscribeRemoteAwarenessStates, versionVectorToWire, wireToVersionVector };
+export { type AwarenessChange, type AwarenessCursor, AwarenessManager, type AwarenessMessage, type AwarenessState, type AwarenessUser, BlobChunkChannel, type BlobChunkChannelMessage, type BlobChunkChannelOptions, BlobChunkPushMessage, BlobChunkRequestMessage, BlobChunkResponseMessage, type ChaosConfig, ChaosTransport, ConnectionMonitor, type ConnectionMonitorConfig, type CursorInfo, DEFAULT_RICHTEXT_DOC_CHANNEL_THRESHOLD, DecryptionError, DeltaCursor, EncryptionError, HttpLongPollingTransport, type HttpLongPollingTransportOptions, JsonMessageSerializer, KeyDerivationError, type MessageSerializer, NegotiatedMessageSerializer, OFFLINE_SYNC_STATUS, type OutboundBatch, OutboundQueue, ProtobufMessageSerializer, QueueStorage, type ReconnectionConfig, ReconnectionManager, RejectedOperation, RejectedOperationStorage, RichtextDocChannel, type RichtextDocChannelOptions, type RichtextDocListener, SCHEMA_MISMATCH_PREFIX, SerializedOperation, SyncConfig, type SyncDiagnostics, SyncEncryptionConfig, SyncEncryptor, SyncEngine, type SyncEngineOptions, SyncMessage, SyncQuerySubset, SyncScopeMap, SyncState, SyncStatePersistence, type SyncStatusController, type SyncStatusControllerOptions, SyncStatusInfo, type SyncStore, SyncTransport, TransportCloseHandler, TransportErrorHandler, TransportMessageHandler, TransportOptions, VersionedKey, type WebSocketConstructor, type WebSocketLike, WebSocketTransport, type WebSocketTransportOptions, WireFormat, YjsDocUpdateMessage, createDeltaCursorFromBatch, createSyncStatusController, decodeBlobChunkBytes, decodeDeltaCursor, decodeYjsUpdate, deriveKey, deriveVersionedKey, encodeBlobChunkBytes, encodeDeltaCursor, encodeYjsUpdate, filterOperationsByScope, generateSalt, getRemoteAwarenessStates, isClientSchemaVersionSupported, isEncryptedPayload, isSchemaMismatchReject, operationMatchesScope, richtextDocKey, sliceOperationsAfterCursor, subscribeRemoteAwarenessStates, versionVectorToWire, wireToVersionVector };