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

package/dist/index.cjs

@@ -86,6 +86,7 @@ __export(index_exports, {
   isYjsDocUpdateMessage: () => isYjsDocUpdateMessage,
   operationMatchesQuerySubsets: () => operationMatchesQuerySubsets,
   operationMatchesScope: () => operationMatchesScope,
+  querySubsetContains: () => querySubsetContains,
   richtextDocKey: () => richtextDocKey,
   sliceOperationsAfterCursor: () => sliceOperationsAfterCursor,
   subscribeRemoteAwarenessStates: () => subscribeRemoteAwarenessStates,
@@ -112,7 +113,8 @@ var SYNC_STATUSES = [
   "offline",
   "clock-error",
   "error",
-  "schema-mismatch"
+  "schema-mismatch",
+  "auth-required"
 ];
 var MemoryRejectedOperationStorage = class {
   rejected = /* @__PURE__ */ new Map();
@@ -160,12 +162,19 @@ function operationMatchesScope(op, scopeMap, fullRecord) {
   const snapshot = buildSnapshot(op, fullRecord ?? void 0);
   if (!snapshot) return false;
   for (const [field, expected] of Object.entries(collectionScope)) {
-    if (snapshot[field] !== expected) {
+    if (!matchesPredicate(snapshot[field], expected)) {
       return false;
     }
   }
   return true;
 }
+function matchesPredicate(actual, expected) {
+  if (expected && typeof expected === "object" && !Array.isArray(expected) && "$in" in expected) {
+    const values = expected.$in;
+    return Array.isArray(values) && values.some((value) => Object.is(actual, value));
+  }
+  return Object.is(actual, expected);
+}
 function filterOperationsByScope(operations, scopeMap) {
   if (!scopeMap) return operations;
   return operations.filter((op) => operationMatchesScope(op, scopeMap));
@@ -222,24 +231,77 @@ function operationMatchesQuerySubsets(op, subsets, fullRecord) {
   if (collectionSubsets.length === 0) {
     return true;
   }
+  if (collectionSubsets.some((subset) => Object.keys(subset.where).length === 0)) {
+    return true;
+  }
   const snapshot = buildSnapshot2(op, fullRecord);
   if (!snapshot) {
     return false;
   }
   return collectionSubsets.some((subset) => recordMatchesWhere(snapshot, subset.where));
 }
+function stableValue(value) {
+  if (Array.isArray(value)) return value.map(stableValue);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value).filter(([, entry]) => entry !== void 0).sort(([a], [b]) => a.localeCompare(b)).map(([key, entry]) => [key, stableValue(entry)])
+    );
+  }
+  return value;
+}
+function whereContains(broad, narrow) {
+  return Object.entries(broad).every(
+    ([field, expected]) => JSON.stringify(stableValue(narrow[field])) === JSON.stringify(stableValue(expected))
+  );
+}
 function dedupeQuerySubsets(subsets) {
-  const seen = /* @__PURE__ */ new Set();
+  const normalized = subsets.map((subset) => ({
+    collection: subset.collection,
+    where: stableValue(subset.where)
+  }));
   const result = [];
-  for (const subset of subsets) {
-    const key = `${subset.collection}:${JSON.stringify(subset.where)}`;
-    if (seen.has(key)) {
+  for (const candidate of normalized) {
+    if (normalized.some(
+      (other) => other !== candidate && other.collection === candidate.collection && whereContains(other.where, candidate.where) && (Object.keys(other.where).length < Object.keys(candidate.where).length || JSON.stringify(other.where) === JSON.stringify(candidate.where))
+    )) {
+      const duplicateAlreadyKept = result.some(
+        (item) => item.collection === candidate.collection && JSON.stringify(item.where) === JSON.stringify(candidate.where)
+      );
+      if (duplicateAlreadyKept || normalized.some(
+        (other) => other !== candidate && other.collection === candidate.collection && Object.keys(other.where).length < Object.keys(candidate.where).length && whereContains(other.where, candidate.where)
+      ))
+        continue;
+    }
+    if (!result.some(
+      (item) => item.collection === candidate.collection && JSON.stringify(item.where) === JSON.stringify(candidate.where)
+    ))
+      result.push(candidate);
+  }
+  return result.sort(
+    (a, b) => `${a.collection}:${JSON.stringify(a.where)}`.localeCompare(
+      `${b.collection}:${JSON.stringify(b.where)}`
+    )
+  );
+}
+function querySubsetContains(broad, narrow) {
+  const collections = /* @__PURE__ */ new Set([
+    ...broad.map((subset) => subset.collection),
+    ...narrow.map((subset) => subset.collection)
+  ]);
+  for (const collection of collections) {
+    const broadForCollection = broad.filter((subset) => subset.collection === collection);
+    const narrowForCollection = narrow.filter((subset) => subset.collection === collection);
+    if (narrowForCollection.length === 0) {
+      if (broadForCollection.length > 0) return false;
       continue;
     }
-    seen.add(key);
-    result.push(subset);
+    if (broadForCollection.length === 0) continue;
+    if (!narrowForCollection.every(
+      (candidate) => broadForCollection.some((other) => whereContains(other.where, candidate.where))
+    ))
+      return false;
   }
-  return result;
+  return true;
 }
 
 // src/delta/delta-cursor.ts
@@ -2818,6 +2880,11 @@ var SyncEngine = class {
   clockBlocked = false;
   clockSkewMs = null;
   blobStorageEnabled = false;
+  suspensionReason = null;
+  authRejected = false;
+  serverFrontier = null;
+  hasInFlightDeliveryBatch = false;
+  blockedFailure = null;
   outboundAckTimer = null;
   startPromise = null;
   stopPromise = null;
@@ -2838,6 +2905,7 @@ var SyncEngine = class {
   activeScope;
   /** Live query subsets registered from reactive subscriptions */
   querySubsets = /* @__PURE__ */ new Map();
+  staticQuerySubsets = [];
   querySubsetReconnectTimer = null;
   /** Resume cursor for paginated initial sync (persisted across reconnects) */
   resumeDeltaCursor = null;
@@ -2931,6 +2999,22 @@ var SyncEngine = class {
     if (this.state !== "disconnected") {
       await this.stop();
     }
+    if (this.authRejected) {
+      this.emitter?.emit({
+        type: "sync:suspended",
+        reason: this.suspensionReason ?? "auth-rejected"
+      });
+      return;
+    }
+    if (this.config.authState) {
+      const authState = await this.config.authState();
+      if (authState.state === "loading" || authState.state === "signed-out") {
+        this.suspensionReason = authState.state === "loading" ? "auth-loading" : "auth-required";
+        this.emitter?.emit({ type: "sync:suspended", reason: this.suspensionReason });
+        return;
+      }
+    }
+    this.suspensionReason = null;
     await this.outboundQueue.initialize();
     if (this.syncState) {
       this.lastAckedServerVector = await this.syncState.loadLastAckedServerVector();
@@ -3060,14 +3144,30 @@ var SyncEngine = class {
   getStatus() {
     const pendingOperations = this.syncState ? this.cachedUnsyncedCount : this.outboundQueue.totalPending;
     const base = {
+      phase: this.resolvePhase(),
+      ...this.suspensionReason ? { reason: this.suspensionReason } : {},
       reconnecting: this.reconnecting,
       pendingOperations,
       lastSyncedAt: this.lastSyncedAt,
       lastSuccessfulPush: this.lastSuccessfulPush,
       lastSuccessfulPull: this.lastSuccessfulPull,
       conflicts: this.conflictCount,
-      clockSkewMs: this.clockSkewMs
+      clockSkewMs: this.clockSkewMs,
+      inFlightUploadOperations: this.currentBatch?.operations.length ?? 0,
+      hasInFlightDeliveryBatch: this.hasInFlightDeliveryBatch,
+      activeViewId: this.deliverySignature(),
+      activeViewComplete: this.state === "streaming" && !this.hasInFlightDeliveryBatch && this.blockedFailure === null && (this.serverFrontier === null || this.deliveryWatermark >= this.serverFrontier),
+      initialSync: {
+        complete: this.deltaReceiveComplete && this.deltaSendComplete,
+        receivedBatches: this.deltaBatchesReceived,
+        totalBatches: this.initialSyncTotalBatches || null,
+        progress: this.initialSyncTotalBatches > 0 ? Math.min(1, this.deltaBatchesReceived / this.initialSyncTotalBatches) : null
+      },
+      deliveryWatermark: this.deliveryWatermark,
+      serverFrontier: this.serverFrontier,
+      blockedFailure: this.blockedFailure
     };
+    if (this.suspensionReason) return { ...base, status: "auth-required" };
     switch (this.state) {
       case "disconnected":
         if (this.clockBlocked) {
@@ -3090,6 +3190,26 @@ var SyncEngine = class {
         return { ...base, status: this.schemaBlocked ? "schema-mismatch" : "error" };
     }
   }
+  resolvePhase() {
+    if (this.suspensionReason) return "suspended";
+    if (this.blockedFailure || this.schemaBlocked || this.clockBlocked) return "blocked";
+    if (this.hasInFlightDeliveryBatch) return "applying";
+    if (this.currentBatch) return "uploading";
+    switch (this.state) {
+      case "disconnected":
+        return "offline";
+      case "connecting":
+        return "connecting";
+      case "handshaking":
+        return "handshaking";
+      case "syncing":
+        return "receiving";
+      case "streaming":
+        return "streaming";
+      case "error":
+        return "blocked";
+    }
+  }
   /**
    * True when the server rejected the client's schema version at handshake.
    * Sync stays blocked until the app schema is upgraded or sync config changes.
@@ -3142,8 +3262,25 @@ var SyncEngine = class {
     await this.refreshPendingCount();
     return this.getStatus().pendingOperations;
   }
-  emitApplyFailure(op, result, overrides) {
+  emitApplyFailure(op, result, overrides, blocking = false) {
     const reason = (0, import_core7.defaultApplyFailureReason)(result, overrides);
+    if (blocking || reason.retriable) {
+      const prior = this.blockedFailure;
+      this.blockedFailure = {
+        operationId: op.id,
+        collection: op.collection,
+        recordId: op.recordId,
+        code: reason.code,
+        message: reason.message,
+        retriable: reason.retriable,
+        firstSeenAt: prior?.operationId === op.id ? prior.firstSeenAt : Date.now(),
+        retryCount: prior?.operationId === op.id ? prior.retryCount + 1 : 0
+      };
+      this.emitter?.emit({
+        type: prior?.operationId === op.id ? "sync:apply-retrying" : "sync:apply-blocked",
+        failure: this.blockedFailure
+      });
+    }
     this.emitter?.emit({
       type: "sync:apply-failed",
       operationId: op.id,
@@ -3160,11 +3297,18 @@ var SyncEngine = class {
    */
   async retryNow() {
     if (this.schemaBlocked) return;
+    this.authRejected = false;
+    this.suspensionReason = null;
     if (this.state === "disconnected" || this.state === "error") {
       this.reconnecting = false;
       await this.start();
     }
   }
+  /** Wake a permanent auth suspension after the binding reports a new auth state. */
+  notifyAuthChanged() {
+    this.authRejected = false;
+    this.suspensionReason = null;
+  }
   /**
    * Atomically refresh the transport session. Overlapping callers share one
    * reconnect, in-flight outbound batches are returned to the queue by stop(), and the
@@ -3321,23 +3465,49 @@ var SyncEngine = class {
    * Takes effect on the next connection; reconnects when already connected.
    */
   registerQuerySubset(subset) {
+    if ((this.config.querySubsets?.mode ?? "reactive") !== "reactive") return () => {
+    };
     const id = `query-${nextQuerySubsetId++}`;
     const previousSignature = this.deliverySignature();
+    const previousEffective = this.getActiveQuerySubsets();
     this.querySubsets.set(id, subset);
-    this.switchDeliveryView(previousSignature);
-    this.scheduleQuerySubsetReconnect();
+    this.switchDeliveryViewWithInheritance(previousSignature, previousEffective);
+    if (this.deliverySignature() !== previousSignature) this.scheduleQuerySubsetReconnect();
     return () => {
       const sigBeforeRemove = this.deliverySignature();
+      const effectiveBeforeRemove = this.getActiveQuerySubsets();
       this.querySubsets.delete(id);
-      this.switchDeliveryView(sigBeforeRemove);
-      this.scheduleQuerySubsetReconnect();
+      this.switchDeliveryViewWithInheritance(sigBeforeRemove, effectiveBeforeRemove);
+      if (this.deliverySignature() !== sigBeforeRemove) this.scheduleQuerySubsetReconnect();
     };
   }
+  switchDeliveryViewWithInheritance(previousSignature, previousSubsets) {
+    const nextSubsets = this.getActiveQuerySubsets();
+    const previousWatermark = this.deliveryWatermark;
+    this.switchDeliveryView(previousSignature);
+    if (this.deliveryWatermark === 0 && querySubsetContains(previousSubsets, nextSubsets)) {
+      this.deliveryWatermark = previousWatermark;
+      this.setViewWatermark(this.deliverySignature(), previousWatermark);
+      void this.persistDeliveryWatermark(previousWatermark);
+    }
+  }
+  /** Atomically replace the manifest used by static query-subset mode. */
+  setQuerySubsets(subsets) {
+    if ((this.config.querySubsets?.mode ?? "reactive") !== "static")
+      throw new Error('setQuerySubsets() requires sync.querySubsets.mode = "static"');
+    const previousSignature = this.deliverySignature();
+    const previousEffective = this.getActiveQuerySubsets();
+    this.staticQuerySubsets = dedupeQuerySubsets(subsets);
+    this.switchDeliveryViewWithInheritance(previousSignature, previousEffective);
+    if (this.deliverySignature() !== previousSignature) this.scheduleQuerySubsetReconnect();
+  }
   /**
    * Returns deduplicated active query subsets from registered subscriptions.
    */
   getActiveQuerySubsets() {
-    return dedupeQuerySubsets([...this.querySubsets.values()]);
+    const mode = this.config.querySubsets?.mode ?? "reactive";
+    if (mode === "disabled") return [];
+    return mode === "static" ? this.staticQuerySubsets : dedupeQuerySubsets([...this.querySubsets.values()]);
   }
   /**
    * Get the awareness manager for collaborative presence.
@@ -3414,6 +3584,7 @@ var SyncEngine = class {
     }
   }
   handleMessageFailure(error) {
+    this.hasInFlightDeliveryBatch = false;
     const reason = error instanceof Error ? error.message : "Message handling failed";
     this.handleTransportClose(reason);
   }
@@ -3487,6 +3658,7 @@ var SyncEngine = class {
       this.setViewWatermark(this.deliverySignature(), 0);
       await this.persistDeliveryWatermark(0);
     }
+    this.serverFrontier = msg.serverMaxDeliverySequence ?? null;
     if (msg.selectedWireFormat) {
       this.setSerializerWireFormat(msg.selectedWireFormat);
     }
@@ -3648,6 +3820,7 @@ var SyncEngine = class {
         this.sendDeliveryAck(msg.messageId, this.deliveryWatermark);
         return;
       }
+      this.hasInFlightDeliveryBatch = true;
     }
     const deserialized = msg.operations.map((s) => this.serializer.decodeOperation(s));
     const operations = this.encryptor ? await this.encryptor.decryptBatch(deserialized) : deserialized;
@@ -3668,17 +3841,22 @@ var SyncEngine = class {
       } catch (error) {
         fullyApplied = false;
         if (error instanceof import_core7.ClockDriftError) {
-          this.emitApplyFailure(transformed, "rejected", {
-            code: import_core7.APPLY_FAILURE_CODES.CLOCK_DRIFT,
-            message: error.message,
-            retriable: false
-          });
+          this.emitApplyFailure(
+            transformed,
+            "rejected",
+            {
+              code: import_core7.APPLY_FAILURE_CODES.CLOCK_DRIFT,
+              message: error.message,
+              retriable: false
+            },
+            true
+          );
           continue;
         }
         const message = error instanceof Error ? error.message : "Apply failed";
         const code = error instanceof import_core7.SyncError ? error.code : error instanceof import_core7.KoraError ? error.code : error instanceof Error && "code" in error && typeof error.code === "string" ? error.code : import_core7.APPLY_FAILURE_CODES.APPLY_FAILED;
         const retriable = code !== import_core7.APPLY_FAILURE_CODES.REFERENTIAL_INTEGRITY;
-        this.emitApplyFailure(transformed, "rejected", { code, message, retriable });
+        this.emitApplyFailure(transformed, "rejected", { code, message, retriable }, true);
       }
     }
     if (inScopeOps.length > 0) {
@@ -3711,7 +3889,13 @@ var SyncEngine = class {
       this.deliveryWatermark = msg.maxDeliverySequence;
       this.setViewWatermark(this.deliverySignature(), this.deliveryWatermark);
       await this.persistDeliveryWatermark(this.deliveryWatermark);
+      if (this.blockedFailure && inScopeOps.some((op) => op.id === this.blockedFailure?.operationId)) {
+        const recovered = this.blockedFailure;
+        this.blockedFailure = null;
+        this.emitter?.emit({ type: "sync:apply-recovered", failure: recovered });
+      }
     }
+    this.hasInFlightDeliveryBatch = false;
     if (this.state === "syncing") {
       this.deltaBatchesReceived++;
       const totalBatches = msg.totalBatches ?? this.initialSyncTotalBatches;
@@ -3784,8 +3968,11 @@ var SyncEngine = class {
       this.currentBatchRequiresPartialAck = false;
     }
     this.transitionTo("error");
-    if (msg.code === "AUTH_FAILED") {
+    if (msg.code === "AUTH_FAILED" || msg.code === "DEVICE_REVOKED") {
+      this.authRejected = true;
+      this.suspensionReason = msg.code === "DEVICE_REVOKED" ? "device-revoked" : "auth-rejected";
       this.emitter?.emit({ type: "sync:auth-failed", reason: msg.message });
+      this.emitter?.emit({ type: "sync:suspended", reason: this.suspensionReason });
     }
     if (msg.code === "INVALID_TIMESTAMP") {
       this.clockBlocked = true;
@@ -4829,13 +5016,22 @@ function fromBase642(str) {
 // src/reactivity/sync-status-controller.ts
 var OFFLINE_SYNC_STATUS = Object.freeze({
   status: "offline",
+  phase: "offline",
   reconnecting: false,
   pendingOperations: 0,
   lastSyncedAt: null,
   lastSuccessfulPush: null,
   lastSuccessfulPull: null,
   conflicts: 0,
-  clockSkewMs: null
+  clockSkewMs: null,
+  inFlightUploadOperations: 0,
+  hasInFlightDeliveryBatch: false,
+  activeViewId: "",
+  activeViewComplete: false,
+  initialSync: { complete: false, receivedBatches: 0, totalBatches: null, progress: null },
+  deliveryWatermark: 0,
+  serverFrontier: null,
+  blockedFailure: null
 });
 var SYNC_STATUS_EVENT_TYPES = [
   "sync:connected",
@@ -4847,6 +5043,10 @@ var SYNC_STATUS_EVENT_TYPES = [
   "sync:received",
   "sync:acknowledged",
   "sync:apply-failed",
+  "sync:suspended",
+  "sync:apply-blocked",
+  "sync:apply-retrying",
+  "sync:apply-recovered",
   "sync:delivery-gap",
   "sync:diagnostics",
   "sync:initial-sync-progress"
@@ -5039,6 +5239,7 @@ function subscribeRemoteAwarenessStates(awareness, listener) {
   isYjsDocUpdateMessage,
   operationMatchesQuerySubsets,
   operationMatchesScope,
+  querySubsetContains,
   richtextDocKey,
   sliceOperationsAfterCursor,
   subscribeRemoteAwarenessStates,