Add a scheduler that ensures single batch of changes from live query due to a transaction that touches multiple source collections

.changeset/olive-crews-love.md

@@ -0,0 +1,5 @@
+---
+"@tanstack/db": patch
+---
+
+Add a scheduler that ensures that if a transaction touches multiple collections that feed into a single live query, the live query only emits a single batch of updates. This fixes an issue where multiple renders could be triggered from a live query under this situation.

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

@@ -1,5 +1,10 @@
 import { createCollection } from "../collection/index.js"
 import { CollectionConfigBuilder } from "./live/collection-config-builder.js"
+import {
+  getBuilderFromConfig,
+  registerCollectionBuilder,
+} from "./live/collection-registry.js"
+import type { LiveQueryCollectionUtils } from "./live/collection-config-builder.js"
 import type { LiveQueryCollectionConfig } from "./live/types.js"
 import type { InitialQueryBuilder, QueryBuilder } from "./builder/index.js"
 import type { Collection } from "../collection/index.js"
@@ -55,15 +60,17 @@ export function liveQueryCollectionOptions<
   TResult extends object = GetResult<TContext>,
 >(
   config: LiveQueryCollectionConfig<TContext, TResult>
-): CollectionConfigForContext<TContext, TResult> {
+): CollectionConfigForContext<TContext, TResult> & {
+  utils: LiveQueryCollectionUtils
+} {
   const collectionConfigBuilder = new CollectionConfigBuilder<
     TContext,
     TResult
   >(config)
   return collectionConfigBuilder.getConfig() as CollectionConfigForContext<
     TContext,
     TResult
-  >
+  > & { utils: LiveQueryCollectionUtils }
 }
 
 /**
@@ -106,7 +113,9 @@ export function createLiveQueryCollection<
   TResult extends object = GetResult<TContext>,
 >(
   query: (q: InitialQueryBuilder) => QueryBuilder<TContext>
-): CollectionForContext<TContext, TResult>
+): CollectionForContext<TContext, TResult> & {
+  utils: LiveQueryCollectionUtils
+}
 
 // Overload 2: Accept full config object with optional utilities
 export function createLiveQueryCollection<
@@ -115,7 +124,9 @@ export function createLiveQueryCollection<
   TUtils extends UtilsRecord = {},
 >(
   config: LiveQueryCollectionConfig<TContext, TResult> & { utils?: TUtils }
-): CollectionForContext<TContext, TResult>
+): CollectionForContext<TContext, TResult> & {
+  utils: LiveQueryCollectionUtils & TUtils
+}
 
 // Implementation
 export function createLiveQueryCollection<
@@ -126,7 +137,9 @@ export function createLiveQueryCollection<
   configOrQuery:
     | (LiveQueryCollectionConfig<TContext, TResult> & { utils?: TUtils })
     | ((q: InitialQueryBuilder) => QueryBuilder<TContext>)
-): CollectionForContext<TContext, TResult> {
+): CollectionForContext<TContext, TResult> & {
+  utils: LiveQueryCollectionUtils & TUtils
+} {
   // Determine if the argument is a function (query) or a config object
   if (typeof configOrQuery === `function`) {
     // Simple query function case
@@ -139,18 +152,24 @@ export function createLiveQueryCollection<
     return bridgeToCreateCollection(options) as CollectionForContext<
       TContext,
       TResult
-    >
+    > & { utils: LiveQueryCollectionUtils & TUtils }
   } else {
     // Config object case
     const config = configOrQuery as LiveQueryCollectionConfig<
       TContext,
       TResult
     > & { utils?: TUtils }
     const options = liveQueryCollectionOptions<TContext, TResult>(config)
-    return bridgeToCreateCollection({
-      ...options,
-      utils: config.utils,
-    }) as CollectionForContext<TContext, TResult>
+
+    // Merge custom utils if provided, preserving the getBuilder() method for dependency tracking
+    if (config.utils) {
+      options.utils = { ...options.utils, ...config.utils }
+    }
+
+    return bridgeToCreateCollection(options) as CollectionForContext<
+      TContext,
+      TResult
+    > & { utils: LiveQueryCollectionUtils & TUtils }
   }
 }
 
@@ -162,12 +181,18 @@ function bridgeToCreateCollection<
   TResult extends object,
   TUtils extends UtilsRecord = {},
 >(
-  options: CollectionConfig<TResult> & { utils?: TUtils }
+  options: CollectionConfig<TResult> & { utils: TUtils }
 ): Collection<TResult, string | number, TUtils> {
-  // This is the only place we need a type assertion, hidden from user API
-  return createCollection(options as any) as unknown as Collection<
+  const collection = createCollection(options as any) as unknown as Collection<
     TResult,
     string | number,
-    TUtils
+    LiveQueryCollectionUtils
   >
+
+  const builder = getBuilderFromConfig(options)
+  if (builder) {
+    registerCollectionBuilder(collection, builder)
+  }
+
+  return collection as unknown as Collection<TResult, string | number, TUtils>
 }