add status & is[Status] variables on the framework hooks (#233)

Co-authored-by: Kyle Mathews <mathews.kyle@gmail.com>

Author: samwillis

packages/db/src/collection.ts

@@ -237,7 +237,8 @@ export class CollectionImpl<
       Array<CollectionStatus>
     > = {
       idle: [`loading`, `error`, `cleaned-up`],
-      loading: [`ready`, `error`, `cleaned-up`],
+      loading: [`initialCommit`, `error`, `cleaned-up`],
+      initialCommit: [`ready`, `error`, `cleaned-up`],
       ready: [`cleaned-up`, `error`],
       error: [`cleaned-up`, `idle`],
       "cleaned-up": [`loading`, `error`],
@@ -382,14 +383,18 @@ export class CollectionImpl<
 
           pendingTransaction.committed = true
 
-          // Update status to ready
-          // We do this before committing as we want the events from the changes to
-          // be from a "ready" state.
+          // Update status to initialCommit when transitioning from loading
+          // This indicates we're in the process of committing the first transaction
           if (this._status === `loading`) {
-            this.setStatus(`ready`)
+            this.setStatus(`initialCommit`)
           }
 
           this.commitPendingTransactions()
+
+          // Transition from initialCommit to ready after the first commit is complete
+          if (this._status === `initialCommit`) {
+            this.setStatus(`ready`)
+          }
         },
       })
 

packages/db/src/query/live-query-collection.ts

@@ -162,7 +162,8 @@ export function liveQueryCollectionOptions<
 
   const allCollectionsReady = () => {
     return Object.values(collections).every(
-      (collection) => collection.status === `ready`
+      (collection) =>
+        collection.status === `ready` || collection.status === `initialCommit`
     )
   }
 

packages/db/src/types.ts

@@ -244,6 +244,8 @@ export type CollectionStatus =
   | `idle`
   /** Sync has started but hasn't received the first commit yet */
   | `loading`
+  /** Collection is in the process of committing its first transaction */
+  | `initialCommit`
   /** Collection has received at least one commit and is ready for use */
   | `ready`
   /** An error occurred during sync initialization */

packages/db/tests/collection-errors.test.ts

@@ -360,7 +360,7 @@ describe(`Collection Error Handling`, () => {
 
       // Valid transitions from loading
       expect(() =>
-        collectionImpl.validateStatusTransition(`loading`, `ready`)
+        collectionImpl.validateStatusTransition(`loading`, `initialCommit`)
       ).not.toThrow()
       expect(() =>
         collectionImpl.validateStatusTransition(`loading`, `error`)
@@ -369,6 +369,17 @@ describe(`Collection Error Handling`, () => {
         collectionImpl.validateStatusTransition(`loading`, `cleaned-up`)
       ).not.toThrow()
 
+      // Valid transitions from initialCommit
+      expect(() =>
+        collectionImpl.validateStatusTransition(`initialCommit`, `ready`)
+      ).not.toThrow()
+      expect(() =>
+        collectionImpl.validateStatusTransition(`initialCommit`, `error`)
+      ).not.toThrow()
+      expect(() =>
+        collectionImpl.validateStatusTransition(`initialCommit`, `cleaned-up`)
+      ).not.toThrow()
+
       // Valid transitions from ready
       expect(() =>
         collectionImpl.validateStatusTransition(`ready`, `cleaned-up`)
@@ -397,6 +408,12 @@ describe(`Collection Error Handling`, () => {
       expect(() =>
         collectionImpl.validateStatusTransition(`idle`, `idle`)
       ).not.toThrow()
+      expect(() =>
+        collectionImpl.validateStatusTransition(
+          `initialCommit`,
+          `initialCommit`
+        )
+      ).not.toThrow()
       expect(() =>
         collectionImpl.validateStatusTransition(`ready`, `ready`)
       ).not.toThrow()

packages/react-db/src/useLiveQuery.ts

@@ -2,6 +2,7 @@ import { useRef, useSyncExternalStore } from "react"
 import { createLiveQueryCollection } from "@tanstack/db"
 import type {
   Collection,
+  CollectionStatus,
   Context,
   GetResult,
   InitialQueryBuilder,
@@ -17,6 +18,12 @@ export function useLiveQuery<TContext extends Context>(
   state: Map<string | number, GetResult<TContext>>
   data: Array<GetResult<TContext>>
   collection: Collection<GetResult<TContext>, string | number, {}>
+  status: CollectionStatus
+  isLoading: boolean
+  isReady: boolean
+  isIdle: boolean
+  isError: boolean
+  isCleanedUp: boolean
 }
 
 // Overload 2: Accept config object
@@ -27,6 +34,12 @@ export function useLiveQuery<TContext extends Context>(
   state: Map<string | number, GetResult<TContext>>
   data: Array<GetResult<TContext>>
   collection: Collection<GetResult<TContext>, string | number, {}>
+  status: CollectionStatus
+  isLoading: boolean
+  isReady: boolean
+  isIdle: boolean
+  isError: boolean
+  isCleanedUp: boolean
 }
 
 // Overload 3: Accept pre-created live query collection
@@ -40,6 +53,12 @@ export function useLiveQuery<
   state: Map<TKey, TResult>
   data: Array<TResult>
   collection: Collection<TResult, TKey, TUtils>
+  status: CollectionStatus
+  isLoading: boolean
+  isReady: boolean
+  isIdle: boolean
+  isError: boolean
+  isCleanedUp: boolean
 }
 
 // Implementation - use function overloads to infer the actual collection type
@@ -171,5 +190,13 @@ export function useLiveQuery(
     state: snapshot.state,
     data: snapshot.data,
     collection: snapshot.collection,
+    status: snapshot.collection.status,
+    isLoading:
+      snapshot.collection.status === `loading` ||
+      snapshot.collection.status === `initialCommit`,
+    isReady: snapshot.collection.status === `ready`,
+    isIdle: snapshot.collection.status === `idle`,
+    isError: snapshot.collection.status === `error`,
+    isCleanedUp: snapshot.collection.status === `cleaned-up`,
   }
 }