feat(db): shared live-query observer + migrate all five adapters (RFC #1623 step 3)

.changeset/live-query-observer.md

@@ -0,0 +1,16 @@
+---
+'@tanstack/db': minor
+'@tanstack/react-db': patch
+'@tanstack/vue-db': patch
+'@tanstack/svelte-db': patch
+'@tanstack/solid-db': patch
+'@tanstack/angular-db': patch
+---
+
+Add an internal shared live-query observer and migrate all five framework adapters to it
+
+Introduces `createLiveQueryObserver` in `@tanstack/db`: given a resolved live-query collection (or `null` for a disabled query) it owns the lifecycle every adapter used to re-implement — sync activation on first subscribe, change and status subscriptions, a snapshot with stable identity per state revision for wholesale consumers, and delivery of the raw `ChangeMessage[]` for granular consumers. React, Vue, Svelte, Solid, and Angular's live-query hooks now materialize from the observer instead of their own hand-rolled subscription/status/snapshot machinery, keeping each adapter's native reactivity and each adapter's data-loading policy (wholesale adapters subscribe without initial state; granular adapters seed from it).
+
+The observer is an **internal, unstable contract** for TanStack DB's official adapters — it is exported so the adapter packages can consume it, but it is not a public extension point yet and its API may change in any release.
+
+The migration also fixes several live-query lifecycle defects: status-only transitions (`error`, `cleaned-up`) now reach mounted consumers; snapshot identity is stable across unsubscribe/resubscribe and stays fresh while detached; dispatch is FIFO and non-reentrant with subscriptions identified by record rather than callback; disposing during the synchronous initial replay no longer leaks the collection subscription; subscribing after dispose throws instead of registering a dead listener; Solid guards its async resource continuations against superseded collections; and constructing an observer no longer activates sync (activation belongs to the first committed subscription).

packages/angular-db/src/index.ts

@@ -9,11 +9,11 @@ import {
 import {
   BaseQueryBuilder,
   createLiveQueryCollection,
+  createLiveQueryObserver,
   isCollection,
   isSingleResultCollection,
 } from '@tanstack/db'
 import type {
-  ChangeMessage,
   Collection,
   CollectionStatus,
   Context,
@@ -249,28 +249,25 @@ export function injectLiveQuery(opts: any) {
 
     cleanup()
 
-    // Initialize immediately with current state
-    syncDataFromCollection(currentCollection)
-
-    // Start sync if idle
-    if (currentCollection.status === `idle`) {
-      currentCollection.startSyncImmediate()
-      // Update status after starting sync
-      status.set(currentCollection.status)
-    }
+    // The shared observer owns sync start, subscription, the ready-race, and
+    // status transitions; Angular re-reads the whole collection on each notify
+    // (wholesale) into its signals.
+    // Angular re-reads the collection on notify; wholesale mode preserves its
+    // pre-observer loading policy (no initial-state snapshot request).
+    const observer = createLiveQueryObserver(currentCollection, {
+      mode: `wholesale`,
+    })
 
-    // Subscribe to changes
-    const subscription = currentCollection.subscribeChanges(
-      (_: Array<ChangeMessage<any>>) => {
-        syncDataFromCollection(currentCollection)
-      },
-    )
-    unsub = subscription.unsubscribe.bind(subscription)
+    // Seed immediately from the post-start state, then re-read on every notify.
+    syncDataFromCollection(currentCollection)
 
-    // Handle ready state
-    currentCollection.onFirstReady(() => {
-      status.set(currentCollection.status)
+    const unsubscribe = observer.subscribe(() => {
+      syncDataFromCollection(currentCollection)
     })
+    unsub = () => {
+      unsubscribe()
+      observer.dispose()
+    }
 
     onCleanup(cleanup)
   })

packages/angular-db/tests/conformance.test.ts

@@ -133,6 +133,7 @@ function makeHandle(result: any, destroy: () => void): LiveQueryHandle {
     current(): ConformanceResult {
       return {
         data: result.data(),
+        state: result.state(),
         status: result.status(),
         isReady: Boolean(result.isReady()),
         isError: Boolean(result.isError()),

packages/angular-db/tests/inject-live-query.test.ts

@@ -80,14 +80,25 @@ function createMockCollection<T extends object, K extends string | number>(
   }
 
   let status: CollectionStatus = initialStatus
+  let stateRevision = 0
   const subs = new Set<(changes: Array<any>) => void>()
   const readySubs = new Set<() => void>()
+  const statusSubs = new Set<(event: any) => void>()
   const id = `mock-col-` + Math.random().toString(36).slice(2)
 
+  // Mirrors the real collection contract: committed changes advance the
+  // state revision before they are emitted.
   const notify = (changes: Array<any> = []) => {
+    if (changes.length > 0) stateRevision++
     for (const cb of subs) cb(changes)
   }
 
+  const emitStatusChange = (previousStatus: CollectionStatus) => {
+    for (const cb of statusSubs) {
+      cb({ type: `status:change`, previousStatus, status })
+    }
+  }
+
   const notifyReady = () => {
     for (const cb of readySubs) cb()
   }
@@ -97,13 +108,22 @@ function createMockCollection<T extends object, K extends string | number>(
     get status() {
       return status
     },
+    get _stateRevision() {
+      return stateRevision
+    },
+    on: (event: string, cb: (e: any) => void) => {
+      if (event === `status:change`) statusSubs.add(cb)
+      return () => statusSubs.delete(cb)
+    },
     entries: () => Array.from(map.entries()),
     values: () => Array.from(map.values()),
     get: (key: K) => map.get(key),
     has: (key: K) => map.has(key),
     size: () => map.size,
     subscribeChanges: (cb: (changes: Array<any>) => void) => {
       subs.add(cb)
+      // Real collections start sync when the first subscriber attaches.
+      api.startSyncImmediate()
       return {
         unsubscribe: () => subs.delete(cb),
       }
@@ -118,26 +138,33 @@ function createMockCollection<T extends object, K extends string | number>(
     },
     preload: () => Promise.resolve(),
     startSyncImmediate: () => {
-      const wasNotReady = status !== `ready`
+      const previousStatus = status
       if (status === `idle`) {
         status = `ready`
-      }
-      if (wasNotReady && status === `ready`) {
+        emitStatusChange(previousStatus)
         setTimeout(notifyReady, 0)
       }
     },
     __setStatus: (s: CollectionStatus) => {
+      const previousStatus = status
       const wasNotReady = status !== `ready`
       status = s
-      notify([])
+      emitStatusChange(previousStatus)
       if (wasNotReady && status === `ready`) {
         setTimeout(notifyReady, 0)
       }
     },
     __replaceAll: (rows: Array<T & Record<`id`, K>>) => {
+      const changes: Array<any> = []
+      for (const [key, value] of map.entries()) {
+        changes.push({ type: `delete`, key, value })
+      }
       map.clear()
-      for (const r of rows) map.set(r.id, r)
-      notify([])
+      for (const r of rows) {
+        map.set(r.id, r)
+        changes.push({ type: `insert`, key: r.id, value: r })
+      }
+      notify(changes)
     },
     __upsert: (row: T & Record<`id`, K>) => {
       const isUpdate = map.has(row.id)

packages/db/src/collection/changes.ts

@@ -30,6 +30,15 @@ export class CollectionChangesManager<
   public batchedEvents: Array<ChangeMessage<TOutput, TKey>> = []
   public shouldBatchEvents = false
 
+  /**
+   * Monotonic revision of the collection's visible state, advanced once per
+   * committed batch of changes — including while nothing is subscribed.
+   * Lets consumers (the live-query observer) cheaply detect "did the data
+   * change" without subscribing, and stays untouched by subscription
+   * bootstrap replays, which do not go through emitEvents.
+   */
+  public stateRevision = 0
+
   /**
    * Creates a new CollectionChangesManager instance
    */
@@ -77,6 +86,10 @@ export class CollectionChangesManager<
     changes: Array<ChangeMessage<TOutput, TKey>>,
     forceEmit = false,
   ): void {
+    // The visible state was already committed by the caller, so the revision
+    // advances even when the events below end up batched for later emission.
+    if (changes.length > 0) this.stateRevision++
+
     // Skip batching for user actions (forceEmit=true) to keep UI responsive
     if (this.shouldBatchEvents && !forceEmit) {
       // Add events to the batch

packages/db/src/collection/index.ts

@@ -420,6 +420,15 @@ export class CollectionImpl<
     return this._changes.activeSubscribersCount
   }
 
+  /**
+   * Monotonic revision of the collection's visible state; advances once per
+   * committed batch of changes, even while nothing is subscribed.
+   * Internal — used by the live-query observer's snapshot cache.
+   */
+  public get _stateRevision(): number {
+    return this._changes.stateRevision
+  }
+
   /**
    * Register a callback to be executed when the collection first becomes ready
    * Useful for preloading collections

packages/db/src/errors.ts

@@ -135,6 +135,12 @@ export class NegativeActiveSubscribersError extends CollectionStateError {
   }
 }
 
+export class LiveQueryObserverDisposedError extends CollectionStateError {
+  constructor() {
+    super(`Cannot subscribe to a disposed LiveQueryObserver`)
+  }
+}
+
 // Collection Operation Errors
 export class CollectionOperationError extends TanStackDBError {
   constructor(message: string) {

packages/db/src/index.ts

@@ -11,6 +11,7 @@ export * from './proxy'
 export * from './query/index.js'
 export * from './optimistic-action'
 export * from './live-query-adapter'
+export * from './live-query-observer'
 export * from './local-only'
 export * from './local-storage'
 export * from './errors'