@tanstack/db 0.4.6 → 0.4.8

package/src/query/live/collection-config-builder.ts

@@ -21,10 +21,15 @@ import type {
   LiveQueryCollectionConfig,
   SyncState,
 } from "./types.js"
+import type { AllCollectionEvents } from "../../collection/events.js"
 
 // Global counter for auto-generated collection IDs
 let liveQueryCollectionCounter = 0
 
+type SyncMethods<TResult extends object> = Parameters<
+  SyncConfig<TResult>[`sync`]
+>[0]
+
 export class CollectionConfigBuilder<
   TContext extends Context,
   TResult extends object = GetResult<TContext>,
@@ -44,6 +49,12 @@ export class CollectionConfigBuilder<
 
   private isGraphRunning = false
 
+  // Error state tracking
+  private isInErrorState = false
+
+  // Reference to the live query collection for error state transitions
+  private liveQueryCollection?: Collection<TResult, any, any>
+
   private graphCache: D2 | undefined
   private inputsCache: Record<string, RootStreamBuilder<unknown>> | undefined
   private pipelineCache: ResultStream | undefined
@@ -101,12 +112,12 @@ export class CollectionConfigBuilder<
   // This gives the callback a chance to load more data if needed,
   // that's used to optimize orderBy operators that set a limit,
   // in order to load some more data if we still don't have enough rows after the pipeline has run.
-  // That can happend because even though we load N rows, the pipeline might filter some of these rows out
+  // That can happen because even though we load N rows, the pipeline might filter some of these rows out
   // causing the orderBy operator to receive less than N rows or even no rows at all.
   // So this callback would notice that it doesn't have enough rows and load some more.
-  // The callback returns a boolean, when it's true it's done loading data and we can mark the collection as ready.
+  // The callback returns a boolean, when it's true it's done loading data.
   maybeRunGraph(
-    config: Parameters<SyncConfig<TResult>[`sync`]>[0],
+    config: SyncMethods<TResult>,
     syncState: FullSyncState,
     callback?: () => boolean
   ) {
@@ -120,13 +131,15 @@ export class CollectionConfigBuilder<
     this.isGraphRunning = true
 
     try {
-      const { begin, commit, markReady } = config
+      const { begin, commit } = config
+
+      // Don't run if the live query is in an error state
+      if (this.isInErrorState) {
+        return
+      }
 
-      // We only run the graph if all the collections are ready
-      if (
-        this.allCollectionsReadyOrInitialCommit() &&
-        syncState.subscribedToAllCollections
-      ) {
+      // Always run the graph if subscribed (eager execution)
+      if (syncState.subscribedToAllCollections) {
         while (syncState.graph.pendingWork()) {
           syncState.graph.run()
           callback?.()
@@ -137,10 +150,9 @@ export class CollectionConfigBuilder<
         if (syncState.messagesCount === 0) {
           begin()
           commit()
-        }
-        // Mark the collection as ready after the first successful run
-        if (this.allCollectionsReady()) {
-          markReady()
+          // After initial commit, check if we should mark ready
+          // (in case all sources were already ready before we subscribed)
+          this.updateLiveQueryStatus(config)
         }
       }
     } finally {
@@ -155,7 +167,10 @@ export class CollectionConfigBuilder<
     }
   }
 
-  private syncFn(config: Parameters<SyncConfig<TResult>[`sync`]>[0]) {
+  private syncFn(config: SyncMethods<TResult>) {
+    // Store reference to the live query collection for error state transitions
+    this.liveQueryCollection = config.collection
+
     const syncState: SyncState = {
       messagesCount: 0,
       subscribedToAllCollections: false,
@@ -233,7 +248,7 @@ export class CollectionConfigBuilder<
   }
 
   private extendPipelineWithChangeProcessing(
-    config: Parameters<SyncConfig<TResult>[`sync`]>[0],
+    config: SyncMethods<TResult>,
     syncState: SyncState
   ): FullSyncState {
     const { begin, commit } = config
@@ -266,7 +281,7 @@ export class CollectionConfigBuilder<
   }
 
   private applyChanges(
-    config: Parameters<SyncConfig<TResult>[`sync`]>[0],
+    config: SyncMethods<TResult>,
     changes: {
       deletes: number
       inserts: number
@@ -317,21 +332,76 @@ export class CollectionConfigBuilder<
     }
   }
 
+  /**
+   * Handle status changes from source collections
+   */
+  private handleSourceStatusChange(
+    config: SyncMethods<TResult>,
+    collectionId: string,
+    event: AllCollectionEvents[`status:change`]
+  ) {
+    const { status } = event
+
+    // Handle error state - any source collection in error puts live query in error
+    if (status === `error`) {
+      this.transitionToError(
+        `Source collection '${collectionId}' entered error state`
+      )
+      return
+    }
+
+    // Handle manual cleanup - this should not happen due to GC prevention,
+    // but could happen if user manually calls cleanup()
+    if (status === `cleaned-up`) {
+      this.transitionToError(
+        `Source collection '${collectionId}' was manually cleaned up while live query '${this.id}' depends on it. ` +
+          `Live queries prevent automatic GC, so this was likely a manual cleanup() call.`
+      )
+      return
+    }
+
+    // Update ready status based on all source collections
+    this.updateLiveQueryStatus(config)
+  }
+
+  /**
+   * Update the live query status based on source collection statuses
+   */
+  private updateLiveQueryStatus(config: SyncMethods<TResult>) {
+    const { markReady } = config
+
+    // Don't update status if already in error
+    if (this.isInErrorState) {
+      return
+    }
+
+    // Mark ready when all source collections are ready
+    if (this.allCollectionsReady()) {
+      markReady()
+    }
+  }
+
+  /**
+   * Transition the live query to error state
+   */
+  private transitionToError(message: string) {
+    this.isInErrorState = true
+
+    // Log error to console for debugging
+    console.error(`[Live Query Error] ${message}`)
+
+    // Transition live query collection to error state
+    this.liveQueryCollection?._lifecycle.setStatus(`error`)
+  }
+
   private allCollectionsReady() {
     return Object.values(this.collections).every((collection) =>
       collection.isReady()
     )
   }
 
-  private allCollectionsReadyOrInitialCommit() {
-    return Object.values(this.collections).every(
-      (collection) =>
-        collection.status === `ready` || collection.status === `initialCommit`
-    )
-  }
-
   private subscribeToAllCollections(
-    config: Parameters<SyncConfig<TResult>[`sync`]>[0],
+    config: SyncMethods<TResult>,
     syncState: FullSyncState
   ) {
     const loaders = Object.entries(this.collections).map(
@@ -347,6 +417,12 @@ export class CollectionConfigBuilder<
         const subscription = collectionSubscriber.subscribe()
         this.subscriptions[collectionId] = subscription
 
+        // Subscribe to status changes for status flow
+        const statusUnsubscribe = collection.on(`status:change`, (event) => {
+          this.handleSourceStatusChange(config, collectionId, event)
+        })
+        syncState.unsubscribeCallbacks.add(statusUnsubscribe)
+
         const loadMore = collectionSubscriber.loadMoreIfNeeded.bind(
           collectionSubscriber,
           subscription
@@ -364,6 +440,9 @@ export class CollectionConfigBuilder<
     // Mark the collections as subscribed in the sync state
     syncState.subscribedToAllCollections = true
 
+    // Initial status check after all subscriptions are set up
+    this.updateLiveQueryStatus(config)
+
     return loadMoreDataCallback
   }
 }

package/src/query/live/collection-subscriber.ts

@@ -103,9 +103,9 @@ export class CollectionSubscriber<
     // otherwise we end up in an infinite loop trying to load more data
     const dataLoader = sentChanges > 0 ? callback : undefined
 
-    // We need to call `maybeRunGraph` even if there's no data to load
-    // because we need to mark the collection as ready if it's not already
-    // and that's only done in `maybeRunGraph`
+    // Always call maybeRunGraph to process changes eagerly.
+    // The graph will run unless the live query is in an error state.
+    // Status management is handled separately via status:change event listeners.
     this.collectionConfigBuilder.maybeRunGraph(
       this.config,
       this.syncState,

package/src/types.ts

@@ -298,17 +298,15 @@ export type DeleteMutationFn<
  *
  * @example
  * // Status transitions
- * // idle → loading → initialCommit → ready
+ * // idle → loading → ready (when markReady() is called)
  * // Any status can transition to → error or cleaned-up
  */
 export type CollectionStatus =
   /** Collection is created but sync hasn't started yet (when startSync config is false) */
   | `idle`
-  /** Sync has started but hasn't received the first commit yet */
+  /** Sync has started and is loading data */
   | `loading`
-  /** Collection is in the process of committing its first transaction */
-  | `initialCommit`
-  /** Collection has received at least one commit and is ready for use */
+  /** Collection has been explicitly marked ready via markReady() */
   | `ready`
   /** An error occurred during sync initialization */
   | `error`