feat: add toArray() for includes subqueries (#1295)

* feat: add toArray() for includes subqueries

toArray() wraps an includes subquery so the parent row contains
Array<T> instead of Collection<T>. When children change, the parent
row is re-emitted with a fresh array snapshot.

- Add ToArrayWrapper class and toArray() function
- Add materializeAsArray flag to IncludesSubquery IR node
- Detect ToArrayWrapper in builder, pass flag through compiler
- Re-emit parent rows on child changes for toArray entries
- Add SelectValue type support for ToArrayWrapper
- Add tests for basic toArray, reactivity, ordering, and limits

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Removed obsolete test

* Small fix

* Tests for changes to deeply nested queries

* Fix changes being emitted on deeply nested collections

* ci: apply automated fixes

* Changeset

* Add type-level tests for toArray() includes subqueries

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* ci: apply automated fixes

* Rename Expected types in includes type tests to descriptive names

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Fix toArray() type inference in includes subqueries

Make ToArrayWrapper generic so it carries the child query result type,
and add a ToArrayWrapper branch in ResultTypeFromSelect to unwrap it
to Array<T>.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Fix toArray re-emit to emit change events for subscribers

The toArray re-emit in flushIncludesState mutated parent items in-place
before writing them through parentSyncMethods.begin/write/commit.
Since commitPendingTransactions captures "previous visible state" by
reading syncedData.get(key) — which returns the already-mutated object
— deepEquals always returned true and suppressed the change event.

Replace the sync methods pattern with direct event emission: capture a
shallow copy before mutation (for previousValue), mutate in-place (so
collection.get() works), and emit UPDATE events directly via the parent
collection's changes manager.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Add change propagation tests for includes subqueries

Test the reactive model difference between Collection and toArray includes:
- Collection includes: child change does NOT re-emit the parent row
  (the child Collection updates in place)
- toArray includes: child change DOES re-emit the parent row
  (the parent row is re-emitted with the updated array snapshot)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* ci: apply automated fixes

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>

Author: 3 people

.changeset/includes-to-array.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/db': patch
+---
+
+feat: add `toArray()` wrapper for includes subqueries to materialize child results as plain arrays instead of live Collections

packages/db/src/query/builder/functions.ts

@@ -2,7 +2,8 @@ import { Aggregate, Func } from '../ir'
 import { toExpression } from './ref-proxy.js'
 import type { BasicExpression } from '../ir'
 import type { RefProxy } from './ref-proxy.js'
-import type { RefLeaf } from './types.js'
+import type { Context, GetResult, RefLeaf } from './types.js'
+import type { QueryBuilder } from './index.js'
 
 type StringRef =
   | RefLeaf<string>
@@ -376,3 +377,14 @@ export const operators = [
 ] as const
 
 export type OperatorName = (typeof operators)[number]
+
+export class ToArrayWrapper<T = any> {
+  declare readonly _type: T
+  constructor(public readonly query: QueryBuilder<any>) {}
+}
+
+export function toArray<TContext extends Context>(
+  query: QueryBuilder<TContext>,
+): ToArrayWrapper<GetResult<TContext>> {
+  return new ToArrayWrapper(query)
+}

packages/db/src/query/builder/index.ts

@@ -23,6 +23,7 @@ import {
   createRefProxyWithSelected,
   toExpression,
 } from './ref-proxy.js'
+import { ToArrayWrapper } from './functions.js'
 import type { NamespacedRow, SingleResult } from '../../types.js'
 import type {
   Aggregate,
@@ -863,7 +864,14 @@ function buildNestedSelect(obj: any, parentAliases: Array<string> = []): any {
       continue
     }
     if (v instanceof BaseQueryBuilder) {
-      out[k] = buildIncludesSubquery(v, k, parentAliases)
+      out[k] = buildIncludesSubquery(v, k, parentAliases, false)
+      continue
+    }
+    if (v instanceof ToArrayWrapper) {
+      if (!(v.query instanceof BaseQueryBuilder)) {
+        throw new Error(`toArray() must wrap a subquery builder`)
+      }
+      out[k] = buildIncludesSubquery(v.query, k, parentAliases, true)
       continue
     }
     out[k] = buildNestedSelect(v, parentAliases)
@@ -880,6 +888,7 @@ function buildIncludesSubquery(
   childBuilder: BaseQueryBuilder,
   fieldName: string,
   parentAliases: Array<string>,
+  materializeAsArray: boolean,
 ): IncludesSubquery {
   const childQuery = childBuilder._getQuery()
 
@@ -943,7 +952,13 @@ function buildIncludesSubquery(
     where: modifiedWhere.length > 0 ? modifiedWhere : undefined,
   }
 
-  return new IncludesSubquery(modifiedQuery, parentRef, childRef, fieldName)
+  return new IncludesSubquery(
+    modifiedQuery,
+    parentRef,
+    childRef,
+    fieldName,
+    materializeAsArray,
+  )
 }
 
 /**

packages/db/src/query/builder/types.ts

@@ -9,6 +9,7 @@ import type {
   Value,
 } from '../ir.js'
 import type { QueryBuilder } from './index.js'
+import type { ToArrayWrapper } from './functions.js'
 
 /**
  * Context - The central state container for query builder operations
@@ -174,6 +175,7 @@ type SelectValue =
   | undefined // Optional values
   | { [key: string]: SelectValue }
   | Array<RefLeaf<any>>
+  | ToArrayWrapper // toArray() wrapped subquery
 
 // Recursive shape for select objects allowing nested projections
 type SelectShape = { [key: string]: SelectValue | SelectShape }
@@ -227,30 +229,32 @@ export type ResultTypeFromSelect<TSelectObject> = WithoutRefBrand<
   Prettify<{
     [K in keyof TSelectObject]: NeedsExtraction<TSelectObject[K]> extends true
       ? ExtractExpressionType<TSelectObject[K]>
-      : TSelectObject[K] extends Ref<infer _T>
-        ? ExtractRef<TSelectObject[K]>
-        : TSelectObject[K] extends RefLeaf<infer T>
-          ? T
-          : TSelectObject[K] extends RefLeaf<infer T> | undefined
-            ? T | undefined
-            : TSelectObject[K] extends RefLeaf<infer T> | null
-              ? T | null
-              : TSelectObject[K] extends Ref<infer _T> | undefined
-                ? ExtractRef<TSelectObject[K]> | undefined
-                : TSelectObject[K] extends Ref<infer _T> | null
-                  ? ExtractRef<TSelectObject[K]> | null
-                  : TSelectObject[K] extends Aggregate<infer T>
-                    ? T
-                    : TSelectObject[K] extends
-                          | string
-                          | number
-                          | boolean
-                          | null
-                          | undefined
-                      ? TSelectObject[K]
-                      : TSelectObject[K] extends Record<string, any>
-                        ? ResultTypeFromSelect<TSelectObject[K]>
-                        : never
+      : TSelectObject[K] extends ToArrayWrapper<infer T>
+        ? Array<T>
+        : TSelectObject[K] extends Ref<infer _T>
+          ? ExtractRef<TSelectObject[K]>
+          : TSelectObject[K] extends RefLeaf<infer T>
+            ? T
+            : TSelectObject[K] extends RefLeaf<infer T> | undefined
+              ? T | undefined
+              : TSelectObject[K] extends RefLeaf<infer T> | null
+                ? T | null
+                : TSelectObject[K] extends Ref<infer _T> | undefined
+                  ? ExtractRef<TSelectObject[K]> | undefined
+                  : TSelectObject[K] extends Ref<infer _T> | null
+                    ? ExtractRef<TSelectObject[K]> | null
+                    : TSelectObject[K] extends Aggregate<infer T>
+                      ? T
+                      : TSelectObject[K] extends
+                            | string
+                            | number
+                            | boolean
+                            | null
+                            | undefined
+                        ? TSelectObject[K]
+                        : TSelectObject[K] extends Record<string, any>
+                          ? ResultTypeFromSelect<TSelectObject[K]>
+                          : never
   }>
 >
 

packages/db/src/query/compiler/index.ts

@@ -55,6 +55,8 @@ export interface IncludesCompilationResult {
   hasOrderBy: boolean
   /** Full compilation result for the child query (for nested includes + alias tracking) */
   childCompilationResult: CompilationResult
+  /** When true, the output layer materializes children as Array<T> instead of Collection<T> */
+  materializeAsArray: boolean
 }
 
 /**
@@ -320,6 +322,7 @@ export function compileQuery(
           subquery.query.orderBy && subquery.query.orderBy.length > 0
         ),
         childCompilationResult: childResult,
+        materializeAsArray: subquery.materializeAsArray,
       })
 
       // Replace includes entry in select with a null placeholder

packages/db/src/query/index.ts

@@ -60,6 +60,8 @@ export {
   sum,
   min,
   max,
+  // Includes helpers
+  toArray,
 } from './builder/functions.js'
 
 // Ref proxy utilities

packages/db/src/query/ir.ts

@@ -139,6 +139,7 @@ export class IncludesSubquery extends BaseExpression {
     public correlationField: PropRef, // Parent-side ref (e.g., project.id)
     public childCorrelationField: PropRef, // Child-side ref (e.g., issue.projectId)
     public fieldName: string, // Result field name (e.g., "issues")
+    public materializeAsArray: boolean = false, // When true, parent gets Array<T> instead of Collection<T>
   ) {
     super()
   }

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

@@ -23,6 +23,7 @@ import type { RootStreamBuilder } from '@tanstack/db-ivm'
 import type { OrderByOptimizationInfo } from '../compiler/order-by.js'
 import type { Collection } from '../../collection/index.js'
 import type {
+  ChangeMessage,
   CollectionConfigSingleRowOption,
   KeyedStream,
   ResultStream,
@@ -788,6 +789,7 @@ export class CollectionConfigBuilder<
         config.collection,
         this.id,
         hasParentChanges ? changesToApply : null,
+        config,
       )
     }
 
@@ -819,6 +821,7 @@ export class CollectionConfigBuilder<
         fieldName: entry.fieldName,
         childCorrelationField: entry.childCorrelationField,
         hasOrderBy: entry.hasOrderBy,
+        materializeAsArray: entry.materializeAsArray,
         childRegistry: new Map(),
         pendingChildChanges: new Map(),
         correlationToParentKeys: new Map(),
@@ -1309,6 +1312,8 @@ type IncludesOutputState = {
   childCorrelationField: PropRef
   /** Whether the child query has an ORDER BY clause */
   hasOrderBy: boolean
+  /** When true, parent gets Array<T> instead of Collection<T> */
+  materializeAsArray: boolean
   /** Maps correlation key value → child Collection entry */
   childRegistry: Map<unknown, ChildCollectionEntry>
   /** Pending child changes: correlationKey → Map<childKey, Changes> */
@@ -1408,6 +1413,7 @@ function createPerEntryIncludesStates(
       fieldName: setup.compilationResult.fieldName,
       childCorrelationField: setup.compilationResult.childCorrelationField,
       hasOrderBy: setup.compilationResult.hasOrderBy,
+      materializeAsArray: setup.compilationResult.materializeAsArray,
       childRegistry: new Map(),
       pendingChildChanges: new Map(),
       correlationToParentKeys: new Map(),
@@ -1633,6 +1639,7 @@ function flushIncludesState(
   parentCollection: Collection<any, any, any>,
   parentId: string,
   parentChanges: Map<unknown, Changes<any>> | null,
+  parentSyncMethods: SyncMethods<any> | null,
 ): void {
   for (const state of includesState) {
     // Phase 1: Parent INSERTs — ensure a child Collection exists for every parent
@@ -1664,21 +1671,31 @@ function flushIncludesState(
             }
             parentKeys.add(parentKey)
 
-            // Attach child Collection to the parent result
-            parentResult[state.fieldName] =
-              state.childRegistry.get(correlationKey)!.collection
+            // Attach child Collection (or array snapshot for toArray) to the parent result
+            if (state.materializeAsArray) {
+              parentResult[state.fieldName] = [
+                ...state.childRegistry.get(correlationKey)!.collection.toArray,
+              ]
+            } else {
+              parentResult[state.fieldName] =
+                state.childRegistry.get(correlationKey)!.collection
+            }
           }
         }
       }
     }
 
+    // Track affected correlation keys for toArray re-emit (before clearing pendingChildChanges)
+    const affectedCorrelationKeys = state.materializeAsArray
+      ? new Set<unknown>(state.pendingChildChanges.keys())
+      : null
+
     // Phase 2: Child changes — apply to child Collections
     // Track which entries had child changes and capture their childChanges maps
     const entriesWithChildChanges = new Map<
       unknown,
       { entry: ChildCollectionEntry; childChanges: Map<unknown, Changes<any>> }
     >()
-
     if (state.pendingChildChanges.size > 0) {
       for (const [correlationKey, childChanges] of state.pendingChildChanges) {
         // Ensure child Collection exists for this correlation key
@@ -1694,14 +1711,17 @@ function flushIncludesState(
           state.childRegistry.set(correlationKey, entry)
         }
 
-        // Attach the child Collection to ANY parent that has this correlation key
-        attachChildCollectionToParent(
-          parentCollection,
-          state.fieldName,
-          correlationKey,
-          state.correlationToParentKeys,
-          entry.collection,
-        )
+        // For non-toArray: attach the child Collection to ANY parent that has this correlation key
+        // For toArray: skip — the array snapshot is set during re-emit below
+        if (!state.materializeAsArray) {
+          attachChildCollectionToParent(
+            parentCollection,
+            state.fieldName,
+            correlationKey,
+            state.correlationToParentKeys,
+            entry.collection,
+          )
+        }
 
         // Apply child changes to the child Collection
         if (entry.syncMethods) {
@@ -1748,6 +1768,7 @@ function flushIncludesState(
           entry.collection,
           entry.collection.id,
           childChanges,
+          entry.syncMethods,
         )
       }
     }
@@ -1761,10 +1782,57 @@ function flushIncludesState(
           entry.collection,
           entry.collection.id,
           null,
+          entry.syncMethods,
         )
       }
     }
 
+    // For toArray entries: re-emit affected parents with updated array snapshots.
+    // We mutate items in-place (so collection.get() reflects changes immediately)
+    // and emit UPDATE events directly. We bypass the sync methods because
+    // commitPendingTransactions compares previous vs new visible state using
+    // deepEquals, but in-place mutation means both sides reference the same
+    // object, so the comparison always returns true and suppresses the event.
+    const toArrayReEmitKeys = state.materializeAsArray
+      ? new Set([...(affectedCorrelationKeys || []), ...dirtyFromBuffers])
+      : null
+    if (parentSyncMethods && toArrayReEmitKeys && toArrayReEmitKeys.size > 0) {
+      const events: Array<ChangeMessage<any>> = []
+      for (const correlationKey of toArrayReEmitKeys) {
+        const parentKeys = state.correlationToParentKeys.get(correlationKey)
+        if (!parentKeys) continue
+        const entry = state.childRegistry.get(correlationKey)
+        for (const parentKey of parentKeys) {
+          const item = parentCollection.get(parentKey as any)
+          if (item) {
+            const key = parentSyncMethods.collection.getKeyFromItem(item)
+            // Capture previous value before in-place mutation
+            const previousValue = { ...item }
+            if (entry) {
+              item[state.fieldName] = [...entry.collection.toArray]
+            }
+            events.push({
+              type: `update`,
+              key,
+              value: item,
+              previousValue,
+            })
+          }
+        }
+      }
+      if (events.length > 0) {
+        // Emit directly — the in-place mutation already updated the data in
+        // syncedData, so we only need to notify subscribers.
+        const changesManager = (parentCollection as any)._changes as {
+          emitEvents: (
+            changes: Array<ChangeMessage<any>>,
+            forceEmit?: boolean,
+          ) => void
+        }
+        changesManager.emitEvents(events, true)
+      }
+    }
+
     // Phase 5: Parent DELETEs — dispose child Collections and clean up
     if (parentChanges) {
       for (const [parentKey, changes] of parentChanges) {