@tanstack/db 0.5.33 → 0.6.0

package/dist/cjs/collection/state.cjs

@@ -2,6 +2,8 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const utils = require("../utils.cjs");
 const SortedMap = require("../SortedMap.cjs");
+const virtualProps = require("../virtual-props.cjs");
+const transactionMetadata = require("./transaction-metadata.cjs");
 class CollectionStateManager {
   /**
    * Creates a new CollectionState manager
@@ -9,14 +11,24 @@ class CollectionStateManager {
   constructor(config) {
     this.pendingSyncedTransactions = [];
     this.syncedMetadata = /* @__PURE__ */ new Map();
+    this.syncedCollectionMetadata = /* @__PURE__ */ new Map();
     this.optimisticUpserts = /* @__PURE__ */ new Map();
     this.optimisticDeletes = /* @__PURE__ */ new Set();
+    this.pendingOptimisticUpserts = /* @__PURE__ */ new Map();
+    this.pendingOptimisticDeletes = /* @__PURE__ */ new Set();
+    this.pendingOptimisticDirectUpserts = /* @__PURE__ */ new Set();
+    this.pendingOptimisticDirectDeletes = /* @__PURE__ */ new Set();
+    this.rowOrigins = /* @__PURE__ */ new Map();
+    this.pendingLocalChanges = /* @__PURE__ */ new Set();
+    this.pendingLocalOrigins = /* @__PURE__ */ new Set();
+    this.virtualPropsCache = /* @__PURE__ */ new WeakMap();
     this.size = 0;
     this.syncedKeys = /* @__PURE__ */ new Set();
     this.preSyncVisibleState = /* @__PURE__ */ new Map();
     this.recentlySyncedKeys = /* @__PURE__ */ new Set();
     this.hasReceivedFirstCommit = false;
     this.isCommittingSyncTransactions = false;
+    this.isLocalOnly = false;
     this.commitPendingTransactions = () => {
       let hasPersistingTransaction = false;
       for (const transaction of this.transactions.values()) {
@@ -54,12 +66,20 @@ class CollectionStateManager {
       );
       if (!hasPersistingTransaction || hasTruncateSync || hasImmediateSync) {
         this.isCommittingSyncTransactions = true;
+        const previousRowOrigins = new Map(this.rowOrigins);
+        const previousOptimisticUpserts = new Map(this.optimisticUpserts);
+        const previousOptimisticDeletes = new Set(this.optimisticDeletes);
         const truncateOptimisticSnapshot = hasTruncateSync ? committedSyncedTransactions.find((t) => t.truncate)?.optimisticSnapshot : null;
+        let truncatePendingLocalChanges;
+        let truncatePendingLocalOrigins;
         const changedKeys = /* @__PURE__ */ new Set();
         for (const transaction of committedSyncedTransactions) {
           for (const operation of transaction.operations) {
             changedKeys.add(operation.key);
           }
+          for (const [key] of transaction.rowMetadataWrites) {
+            changedKeys.add(key);
+          }
         }
         let currentVisibleState = this.preSyncVisibleState;
         if (currentVisibleState.size === 0) {
@@ -73,6 +93,21 @@ class CollectionStateManager {
         }
         const events = [];
         const rowUpdateMode = this.config.sync.rowUpdateMode || `partial`;
+        const completedOptimisticOps = /* @__PURE__ */ new Map();
+        for (const transaction of this.transactions.values()) {
+          if (transaction.state === `completed`) {
+            for (const mutation of transaction.mutations) {
+              if (this.isThisCollection(mutation.collection)) {
+                if (mutation.optimistic) {
+                  completedOptimisticOps.set(mutation.key, {
+                    type: mutation.type,
+                    value: mutation.modified
+                  });
+                }
+              }
+            }
+          }
+        }
         for (const transaction of committedSyncedTransactions) {
           if (transaction.truncate) {
             const visibleKeys = /* @__PURE__ */ new Set([
@@ -86,9 +121,12 @@ class CollectionStateManager {
                 events.push({ type: `delete`, key, value: previousValue });
               }
             }
+            truncatePendingLocalChanges = new Set(this.pendingLocalChanges);
+            truncatePendingLocalOrigins = new Set(this.pendingLocalOrigins);
             this.syncedData.clear();
             this.syncedMetadata.clear();
             this.syncedKeys.clear();
+            this.clearOriginTrackingState();
             for (const key of changedKeys) {
               currentVisibleState.delete(key);
             }
@@ -100,27 +138,17 @@ class CollectionStateManager {
           for (const operation of transaction.operations) {
             const key = operation.key;
             this.syncedKeys.add(key);
-            switch (operation.type) {
-              case `insert`:
-                this.syncedMetadata.set(key, operation.metadata);
-                break;
-              case `update`:
-                this.syncedMetadata.set(
-                  key,
-                  Object.assign(
-                    {},
-                    this.syncedMetadata.get(key),
-                    operation.metadata
-                  )
-                );
-                break;
-              case `delete`:
-                this.syncedMetadata.delete(key);
-                break;
-            }
+            const origin = this.isLocalOnly || this.pendingLocalChanges.has(key) || this.pendingLocalOrigins.has(key) || truncatePendingLocalChanges?.has(key) === true || truncatePendingLocalOrigins?.has(key) === true ? "local" : "remote";
             switch (operation.type) {
               case `insert`:
                 this.syncedData.set(key, operation.value);
+                this.rowOrigins.set(key, origin);
+                this.pendingLocalChanges.delete(key);
+                this.pendingLocalOrigins.delete(key);
+                this.pendingOptimisticUpserts.delete(key);
+                this.pendingOptimisticDeletes.delete(key);
+                this.pendingOptimisticDirectUpserts.delete(key);
+                this.pendingOptimisticDirectDeletes.delete(key);
                 break;
               case `update`: {
                 if (rowUpdateMode === `partial`) {
@@ -133,13 +161,45 @@ class CollectionStateManager {
                 } else {
                   this.syncedData.set(key, operation.value);
                 }
+                this.rowOrigins.set(key, origin);
+                this.pendingLocalChanges.delete(key);
+                this.pendingLocalOrigins.delete(key);
+                this.pendingOptimisticUpserts.delete(key);
+                this.pendingOptimisticDeletes.delete(key);
+                this.pendingOptimisticDirectUpserts.delete(key);
+                this.pendingOptimisticDirectDeletes.delete(key);
                 break;
               }
               case `delete`:
                 this.syncedData.delete(key);
+                this.syncedMetadata.delete(key);
+                this.rowOrigins.delete(key);
+                this.pendingLocalChanges.delete(key);
+                this.pendingLocalOrigins.delete(key);
+                this.pendingOptimisticUpserts.delete(key);
+                this.pendingOptimisticDeletes.delete(key);
+                this.pendingOptimisticDirectUpserts.delete(key);
+                this.pendingOptimisticDirectDeletes.delete(key);
                 break;
             }
           }
+          for (const [key, metadataWrite] of transaction.rowMetadataWrites) {
+            if (metadataWrite.type === `delete`) {
+              this.syncedMetadata.delete(key);
+              continue;
+            }
+            this.syncedMetadata.set(key, metadataWrite.value);
+          }
+          for (const [
+            key,
+            metadataWrite
+          ] of transaction.collectionMetadataWrites) {
+            if (metadataWrite.type === `delete`) {
+              this.syncedCollectionMetadata.delete(key);
+              continue;
+            }
+            this.syncedCollectionMetadata.set(key, metadataWrite.value);
+          }
         }
         if (hasTruncateSync) {
           const syncedInsertedOrUpdatedKeys = /* @__PURE__ */ new Set();
@@ -223,22 +283,24 @@ class CollectionStateManager {
             }
           }
         }
-        const completedOptimisticOps = /* @__PURE__ */ new Map();
-        for (const transaction of this.transactions.values()) {
-          if (transaction.state === `completed`) {
-            for (const mutation of transaction.mutations) {
-              if (mutation.optimistic && this.isThisCollection(mutation.collection) && changedKeys.has(mutation.key)) {
-                completedOptimisticOps.set(mutation.key, {
-                  type: mutation.type,
-                  value: mutation.modified
-                });
-              }
-            }
-          }
-        }
         for (const key of changedKeys) {
           const previousVisibleValue = currentVisibleState.get(key);
           const newVisibleValue = this.get(key);
+          const previousVirtualProps = this.getVirtualPropsSnapshotForState(key, {
+            rowOrigins: previousRowOrigins,
+            optimisticUpserts: previousOptimisticUpserts,
+            optimisticDeletes: previousOptimisticDeletes,
+            completedOptimisticKeys: completedOptimisticOps
+          });
+          const nextVirtualProps = this.getVirtualPropsSnapshotForState(key);
+          const virtualChanged = previousVirtualProps.$synced !== nextVirtualProps.$synced || previousVirtualProps.$origin !== nextVirtualProps.$origin;
+          const previousValueWithVirtual = previousVisibleValue !== void 0 ? virtualProps.enrichRowWithVirtualProps(
+            previousVisibleValue,
+            key,
+            this.collection.id,
+            () => previousVirtualProps.$synced,
+            () => previousVirtualProps.$origin
+          ) : void 0;
           const completedOp = completedOptimisticOps.get(key);
           let isRedundantSync = false;
           if (completedOp) {
@@ -248,27 +310,47 @@ class CollectionStateManager {
               isRedundantSync = true;
             }
           }
-          if (!isRedundantSync) {
-            if (previousVisibleValue === void 0 && newVisibleValue !== void 0) {
-              events.push({
-                type: `insert`,
+          const shouldEmitVirtualUpdate = virtualChanged && previousVisibleValue !== void 0 && newVisibleValue !== void 0 && utils.deepEquals(previousVisibleValue, newVisibleValue);
+          if (isRedundantSync && !shouldEmitVirtualUpdate) {
+            continue;
+          }
+          if (previousVisibleValue === void 0 && newVisibleValue !== void 0) {
+            const completedOptimisticOp = completedOptimisticOps.get(key);
+            if (completedOptimisticOp) {
+              const previousValueFromCompleted = completedOptimisticOp.value;
+              const previousValueWithVirtualFromCompleted = virtualProps.enrichRowWithVirtualProps(
+                previousValueFromCompleted,
                 key,
-                value: newVisibleValue
-              });
-            } else if (previousVisibleValue !== void 0 && newVisibleValue === void 0) {
+                this.collection.id,
+                () => previousVirtualProps.$synced,
+                () => previousVirtualProps.$origin
+              );
               events.push({
-                type: `delete`,
+                type: `update`,
                 key,
-                value: previousVisibleValue
+                value: newVisibleValue,
+                previousValue: previousValueWithVirtualFromCompleted
               });
-            } else if (previousVisibleValue !== void 0 && newVisibleValue !== void 0 && !utils.deepEquals(previousVisibleValue, newVisibleValue)) {
+            } else {
               events.push({
-                type: `update`,
+                type: `insert`,
                 key,
-                value: newVisibleValue,
-                previousValue: previousVisibleValue
+                value: newVisibleValue
               });
             }
+          } else if (previousVisibleValue !== void 0 && newVisibleValue === void 0) {
+            events.push({
+              type: `delete`,
+              key,
+              value: previousValueWithVirtual ?? previousVisibleValue
+            });
+          } else if (previousVisibleValue !== void 0 && newVisibleValue !== void 0 && (!utils.deepEquals(previousVisibleValue, newVisibleValue) || shouldEmitVirtualUpdate)) {
+            events.push({
+              type: `update`,
+              key,
+              value: newVisibleValue,
+              previousValue: previousValueWithVirtual ?? previousVisibleValue
+            });
           }
         }
         this.size = this.calculateSize();
@@ -299,6 +381,125 @@ class CollectionStateManager {
     this.indexes = deps.indexes;
     this._events = deps.events;
   }
+  /**
+   * Checks if a row has pending optimistic mutations (not yet confirmed by sync).
+   * Used to compute the $synced virtual property.
+   */
+  isRowSynced(key) {
+    if (this.isLocalOnly) {
+      return true;
+    }
+    return !this.optimisticUpserts.has(key) && !this.optimisticDeletes.has(key);
+  }
+  /**
+   * Gets the origin of the last confirmed change to a row.
+   * Returns 'local' if the row has optimistic mutations (optimistic changes are local).
+   * Used to compute the $origin virtual property.
+   */
+  getRowOrigin(key) {
+    if (this.isLocalOnly) {
+      return "local";
+    }
+    if (this.optimisticUpserts.has(key) || this.optimisticDeletes.has(key)) {
+      return "local";
+    }
+    return this.rowOrigins.get(key) ?? "remote";
+  }
+  createVirtualPropsSnapshot(key, overrides) {
+    return {
+      $synced: overrides?.$synced ?? this.isRowSynced(key),
+      $origin: overrides?.$origin ?? this.getRowOrigin(key),
+      $key: overrides?.$key ?? key,
+      $collectionId: overrides?.$collectionId ?? this.collection.id
+    };
+  }
+  getVirtualPropsSnapshotForState(key, options) {
+    if (this.isLocalOnly) {
+      return this.createVirtualPropsSnapshot(key, {
+        $synced: true,
+        $origin: "local"
+      });
+    }
+    const optimisticUpserts = options?.optimisticUpserts ?? this.optimisticUpserts;
+    const optimisticDeletes = options?.optimisticDeletes ?? this.optimisticDeletes;
+    const hasOptimisticChange = optimisticUpserts.has(key) || optimisticDeletes.has(key) || options?.completedOptimisticKeys?.has(key) === true;
+    return this.createVirtualPropsSnapshot(key, {
+      $synced: !hasOptimisticChange,
+      $origin: hasOptimisticChange ? "local" : (options?.rowOrigins ?? this.rowOrigins).get(key) ?? "remote"
+    });
+  }
+  enrichWithVirtualPropsSnapshot(row, virtualProps2) {
+    const existingRow = row;
+    const synced = existingRow.$synced ?? virtualProps2.$synced;
+    const origin = existingRow.$origin ?? virtualProps2.$origin;
+    const resolvedKey = existingRow.$key ?? virtualProps2.$key;
+    const collectionId = existingRow.$collectionId ?? virtualProps2.$collectionId;
+    const cached = this.virtualPropsCache.get(row);
+    if (cached && cached.synced === synced && cached.origin === origin && cached.key === resolvedKey && cached.collectionId === collectionId) {
+      return cached.enriched;
+    }
+    const enriched = {
+      ...row,
+      $synced: synced,
+      $origin: origin,
+      $key: resolvedKey,
+      $collectionId: collectionId
+    };
+    this.virtualPropsCache.set(row, {
+      synced,
+      origin,
+      key: resolvedKey,
+      collectionId,
+      enriched
+    });
+    return enriched;
+  }
+  clearOriginTrackingState() {
+    this.rowOrigins.clear();
+    this.pendingLocalChanges.clear();
+    this.pendingLocalOrigins.clear();
+  }
+  /**
+   * Enriches a row with virtual properties using the "add-if-missing" pattern.
+   * If the row already has virtual properties (from an upstream collection),
+   * they are preserved. Otherwise, new values are computed.
+   */
+  enrichWithVirtualProps(row, key) {
+    return this.enrichWithVirtualPropsSnapshot(
+      row,
+      this.createVirtualPropsSnapshot(key)
+    );
+  }
+  /**
+   * Creates a change message with virtual properties.
+   * Uses the "add-if-missing" pattern so that pass-through from upstream
+   * collections works correctly.
+   */
+  enrichChangeMessage(change) {
+    const { __virtualProps } = change;
+    const enrichedValue = __virtualProps?.value ? this.enrichWithVirtualPropsSnapshot(change.value, __virtualProps.value) : this.enrichWithVirtualProps(change.value, change.key);
+    const enrichedPreviousValue = change.previousValue ? __virtualProps?.previousValue ? this.enrichWithVirtualPropsSnapshot(
+      change.previousValue,
+      __virtualProps.previousValue
+    ) : this.enrichWithVirtualProps(change.previousValue, change.key) : void 0;
+    return {
+      key: change.key,
+      type: change.type,
+      value: enrichedValue,
+      previousValue: enrichedPreviousValue,
+      metadata: change.metadata
+    };
+  }
+  /**
+   * Get the current value for a key enriched with virtual properties.
+   */
+  getWithVirtualProps(key) {
+    const value = this.get(key);
+    if (value === void 0) {
+      return void 0;
+    }
+    return this.enrichWithVirtualProps(value, key);
+  }
   /**
    * Get the current value for a key (virtual derived state)
    */
@@ -408,8 +609,95 @@ class CollectionStateManager {
     }
     const previousState = new Map(this.optimisticUpserts);
     const previousDeletes = new Set(this.optimisticDeletes);
+    const previousRowOrigins = new Map(this.rowOrigins);
+    for (const transaction of this.transactions.values()) {
+      const isDirectTransaction = transaction.metadata[transactionMetadata.DIRECT_TRANSACTION_METADATA_KEY] === true;
+      if (transaction.state === `completed`) {
+        for (const mutation of transaction.mutations) {
+          if (!this.isThisCollection(mutation.collection)) {
+            continue;
+          }
+          this.pendingLocalOrigins.add(mutation.key);
+          if (!mutation.optimistic) {
+            continue;
+          }
+          switch (mutation.type) {
+            case `insert`:
+            case `update`:
+              this.pendingOptimisticUpserts.set(
+                mutation.key,
+                mutation.modified
+              );
+              this.pendingOptimisticDeletes.delete(mutation.key);
+              if (isDirectTransaction) {
+                this.pendingOptimisticDirectUpserts.add(mutation.key);
+                this.pendingOptimisticDirectDeletes.delete(mutation.key);
+              } else {
+                this.pendingOptimisticDirectUpserts.delete(mutation.key);
+                this.pendingOptimisticDirectDeletes.delete(mutation.key);
+              }
+              break;
+            case `delete`:
+              this.pendingOptimisticUpserts.delete(mutation.key);
+              this.pendingOptimisticDeletes.add(mutation.key);
+              if (isDirectTransaction) {
+                this.pendingOptimisticDirectUpserts.delete(mutation.key);
+                this.pendingOptimisticDirectDeletes.add(mutation.key);
+              } else {
+                this.pendingOptimisticDirectUpserts.delete(mutation.key);
+                this.pendingOptimisticDirectDeletes.delete(mutation.key);
+              }
+              break;
+          }
+        }
+      } else if (transaction.state === `failed`) {
+        for (const mutation of transaction.mutations) {
+          if (!this.isThisCollection(mutation.collection)) {
+            continue;
+          }
+          this.pendingLocalOrigins.delete(mutation.key);
+          if (mutation.optimistic) {
+            this.pendingOptimisticUpserts.delete(mutation.key);
+            this.pendingOptimisticDeletes.delete(mutation.key);
+            this.pendingOptimisticDirectUpserts.delete(mutation.key);
+            this.pendingOptimisticDirectDeletes.delete(mutation.key);
+          }
+        }
+      }
+    }
     this.optimisticUpserts.clear();
     this.optimisticDeletes.clear();
+    this.pendingLocalChanges.clear();
+    const pendingSyncKeys = /* @__PURE__ */ new Set();
+    for (const transaction of this.pendingSyncedTransactions) {
+      for (const operation of transaction.operations) {
+        pendingSyncKeys.add(operation.key);
+      }
+    }
+    const staleOptimisticUpserts = [];
+    for (const [key, value] of this.pendingOptimisticUpserts) {
+      if (pendingSyncKeys.has(key) || this.pendingOptimisticDirectUpserts.has(key)) {
+        this.optimisticUpserts.set(key, value);
+      } else {
+        staleOptimisticUpserts.push(key);
+      }
+    }
+    for (const key of staleOptimisticUpserts) {
+      this.pendingOptimisticUpserts.delete(key);
+      this.pendingLocalOrigins.delete(key);
+    }
+    const staleOptimisticDeletes = [];
+    for (const key of this.pendingOptimisticDeletes) {
+      if (pendingSyncKeys.has(key) || this.pendingOptimisticDirectDeletes.has(key)) {
+        this.optimisticDeletes.add(key);
+      } else {
+        staleOptimisticDeletes.push(key);
+      }
+    }
+    for (const key of staleOptimisticDeletes) {
+      this.pendingOptimisticDeletes.delete(key);
+      this.pendingLocalOrigins.delete(key);
+    }
     const activeTransactions = [];
     for (const transaction of this.transactions.values()) {
       if (![`completed`, `failed`].includes(transaction.state)) {
@@ -418,7 +706,11 @@ class CollectionStateManager {
     }
     for (const transaction of activeTransactions) {
       for (const mutation of transaction.mutations) {
-        if (this.isThisCollection(mutation.collection) && mutation.optimistic) {
+        if (!this.isThisCollection(mutation.collection)) {
+          continue;
+        }
+        this.pendingLocalChanges.add(mutation.key);
+        if (mutation.optimistic) {
           switch (mutation.type) {
             case `insert`:
             case `update`:
@@ -438,7 +730,12 @@ class CollectionStateManager {
     }
     this.size = this.calculateSize();
     const events = [];
-    this.collectOptimisticChanges(previousState, previousDeletes, events);
+    this.collectOptimisticChanges(
+      previousState,
+      previousDeletes,
+      previousRowOrigins,
+      events
+    );
     const filteredEventsBySyncStatus = events.filter((event) => {
       if (!this.recentlySyncedKeys.has(event.key)) {
         return true;
@@ -449,14 +746,14 @@ class CollectionStateManager {
       return false;
     });
     if (this.pendingSyncedTransactions.length > 0 && !triggeredByUserAction) {
-      const pendingSyncKeys = /* @__PURE__ */ new Set();
+      const pendingSyncKeysForFilter = /* @__PURE__ */ new Set();
       for (const transaction of this.pendingSyncedTransactions) {
         for (const operation of transaction.operations) {
-          pendingSyncKeys.add(operation.key);
+          pendingSyncKeysForFilter.add(operation.key);
         }
       }
       const filteredEvents = filteredEventsBySyncStatus.filter((event) => {
-        if (event.type === `delete` && pendingSyncKeys.has(event.key)) {
+        if (event.type === `delete` && pendingSyncKeysForFilter.has(event.key)) {
           const hasActiveOptimisticMutation = activeTransactions.some(
             (tx) => tx.mutations.some(
               (m) => this.isThisCollection(m.collection) && m.key === event.key
@@ -495,7 +792,7 @@ class CollectionStateManager {
   /**
    * Collect events for optimistic changes
    */
-  collectOptimisticChanges(previousUpserts, previousDeletes, events) {
+  collectOptimisticChanges(previousUpserts, previousDeletes, previousRowOrigins, events) {
     const allKeys = /* @__PURE__ */ new Set([
       ...previousUpserts.keys(),
       ...this.optimisticUpserts.keys(),
@@ -509,16 +806,40 @@ class CollectionStateManager {
         previousUpserts,
         previousDeletes
       );
+      const previousVirtualProps = this.getVirtualPropsSnapshotForState(key, {
+        rowOrigins: previousRowOrigins,
+        optimisticUpserts: previousUpserts,
+        optimisticDeletes: previousDeletes
+      });
+      const nextVirtualProps = this.getVirtualPropsSnapshotForState(key);
       if (previousValue !== void 0 && currentValue === void 0) {
-        events.push({ type: `delete`, key, value: previousValue });
+        events.push({
+          type: `delete`,
+          key,
+          value: previousValue,
+          __virtualProps: {
+            value: previousVirtualProps
+          }
+        });
       } else if (previousValue === void 0 && currentValue !== void 0) {
-        events.push({ type: `insert`, key, value: currentValue });
+        events.push({
+          type: `insert`,
+          key,
+          value: currentValue,
+          __virtualProps: {
+            value: nextVirtualProps
+          }
+        });
       } else if (previousValue !== void 0 && currentValue !== void 0 && previousValue !== currentValue) {
         events.push({
           type: `update`,
           key,
           value: currentValue,
-          previousValue
+          previousValue,
+          __virtualProps: {
+            value: nextVirtualProps,
+            previousValue: previousVirtualProps
+          }
         });
       }
     }
@@ -588,8 +909,15 @@ class CollectionStateManager {
   cleanup() {
     this.syncedData.clear();
     this.syncedMetadata.clear();
+    this.syncedCollectionMetadata.clear();
     this.optimisticUpserts.clear();
     this.optimisticDeletes.clear();
+    this.pendingOptimisticUpserts.clear();
+    this.pendingOptimisticDeletes.clear();
+    this.pendingOptimisticDirectUpserts.clear();
+    this.pendingOptimisticDirectDeletes.clear();
+    this.clearOriginTrackingState();
+    this.isLocalOnly = false;
     this.size = 0;
     this.pendingSyncedTransactions = [];
     this.syncedKeys.clear();