docs: document materialize() helper for includes subqueries

- Add a "materialize" subsection to the Includes guide in live-queries.md
  with array vs singleton (findOne) examples and notes on reactivity and
  expression-context restrictions.
- Regenerate reference docs via pnpm generate-docs, which surfaces the new
  materialize() entry plus other previously-stale references.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: kevin-dp

docs/guides/live-queries.md

@@ -1252,6 +1252,48 @@ const projectsWithIssues = createLiveQueryCollection((q) =>
 
 With `toArray()`, the project row is re-emitted whenever its issues change. Without it, the child `Collection` updates independently.
 
+### materialize
+
+`materialize()` is a single helper that covers both multi-row and single-row includes:
+
+- When the wrapped subquery returns multiple rows, the parent receives `Array<T>` — same shape as `toArray()`.
+- When the wrapped subquery ends in `.findOne()`, the parent receives `T | undefined` — a single object, or `undefined` when no child matches.
+
+This spares callers from unwrapping a singleton array whenever they know the child query yields at most one row. Reactive semantics match `toArray()`: the parent row is re-emitted whenever the underlying children change, including insert / update / delete transitions and rows moving in or out of a match.
+
+```ts
+import { createLiveQueryCollection, eq, materialize } from '@tanstack/db'
+
+// Multi-row → issues: Array<Issue>
+const projectsWithIssues = createLiveQueryCollection((q) =>
+  q.from({ p: projectsCollection }).select(({ p }) => ({
+    ...p,
+    issues: materialize(
+      q
+        .from({ i: issuesCollection })
+        .where(({ i }) => eq(i.projectId, p.id)),
+    ),
+  })),
+)
+
+// Singleton → project: Project | undefined
+const issuesWithProject = createLiveQueryCollection((q) =>
+  q.from({ i: issuesCollection }).select(({ i }) => ({
+    ...i,
+    project: materialize(
+      q
+        .from({ p: projectsCollection })
+        .where(({ p }) => eq(p.id, i.projectId))
+        .findOne(),
+    ),
+  })),
+)
+```
+
+The singleton vs. array result type is inferred from whether the wrapped query ends in `.findOne()` — no extra type annotation is required.
+
+Like `toArray()`, `materialize()` is only valid as a top-level value in `.select()` — it cannot be nested inside expression helpers such as `coalesce()` or `eq()`.
+
 ### Aggregates
 
 You can use aggregate functions in child queries. Aggregates are computed per parent:

docs/reference/@tanstack/namespaces/IR/classes/Aggregate.md

@@ -5,7 +5,7 @@ title: Aggregate
 
 # Class: Aggregate\<T\>
 
-Defined in: [packages/db/src/query/ir.ts:129](https://github.com/TanStack/db/blob/main/packages/db/src/query/ir.ts#L129)
+Defined in: [packages/db/src/query/ir.ts:166](https://github.com/TanStack/db/blob/main/packages/db/src/query/ir.ts#L166)
 
 ## Extends
 
@@ -25,7 +25,7 @@ Defined in: [packages/db/src/query/ir.ts:129](https://github.com/TanStack/db/blo
 new Aggregate<T>(name, args): Aggregate<T>;
 ```
 
-Defined in: [packages/db/src/query/ir.ts:131](https://github.com/TanStack/db/blob/main/packages/db/src/query/ir.ts#L131)
+Defined in: [packages/db/src/query/ir.ts:168](https://github.com/TanStack/db/blob/main/packages/db/src/query/ir.ts#L168)
 
 #### Parameters
 
@@ -55,7 +55,7 @@ BaseExpression<T>.constructor
 readonly __returnType: T;
 ```
 
-Defined in: [packages/db/src/query/ir.ts:73](https://github.com/TanStack/db/blob/main/packages/db/src/query/ir.ts#L73)
+Defined in: [packages/db/src/query/ir.ts:82](https://github.com/TanStack/db/blob/main/packages/db/src/query/ir.ts#L82)
 
 **`Internal`**
 
@@ -75,7 +75,7 @@ BaseExpression.__returnType
 args: BasicExpression<any>[];
 ```
 
-Defined in: [packages/db/src/query/ir.ts:133](https://github.com/TanStack/db/blob/main/packages/db/src/query/ir.ts#L133)
+Defined in: [packages/db/src/query/ir.ts:170](https://github.com/TanStack/db/blob/main/packages/db/src/query/ir.ts#L170)
 
 ***
 
@@ -85,7 +85,7 @@ Defined in: [packages/db/src/query/ir.ts:133](https://github.com/TanStack/db/blo
 name: string;
 ```
 
-Defined in: [packages/db/src/query/ir.ts:132](https://github.com/TanStack/db/blob/main/packages/db/src/query/ir.ts#L132)
+Defined in: [packages/db/src/query/ir.ts:169](https://github.com/TanStack/db/blob/main/packages/db/src/query/ir.ts#L169)
 
 ***
 
@@ -95,7 +95,7 @@ Defined in: [packages/db/src/query/ir.ts:132](https://github.com/TanStack/db/blo
 type: "agg";
 ```
 
-Defined in: [packages/db/src/query/ir.ts:130](https://github.com/TanStack/db/blob/main/packages/db/src/query/ir.ts#L130)
+Defined in: [packages/db/src/query/ir.ts:167](https://github.com/TanStack/db/blob/main/packages/db/src/query/ir.ts#L167)
 
 #### Overrides
 

docs/reference/@tanstack/namespaces/IR/classes/CollectionRef.md

@@ -5,7 +5,7 @@ title: CollectionRef
 
 # Class: CollectionRef
 
-Defined in: [packages/db/src/query/ir.ts:76](https://github.com/TanStack/db/blob/main/packages/db/src/query/ir.ts#L76)
+Defined in: [packages/db/src/query/ir.ts:85](https://github.com/TanStack/db/blob/main/packages/db/src/query/ir.ts#L85)
 
 ## Extends
 
@@ -19,7 +19,7 @@ Defined in: [packages/db/src/query/ir.ts:76](https://github.com/TanStack/db/blob
 new CollectionRef(collection, alias): CollectionRef;
 ```
 
-Defined in: [packages/db/src/query/ir.ts:78](https://github.com/TanStack/db/blob/main/packages/db/src/query/ir.ts#L78)
+Defined in: [packages/db/src/query/ir.ts:87](https://github.com/TanStack/db/blob/main/packages/db/src/query/ir.ts#L87)
 
 #### Parameters
 
@@ -49,7 +49,7 @@ BaseExpression.constructor
 readonly __returnType: any;
 ```
 
-Defined in: [packages/db/src/query/ir.ts:73](https://github.com/TanStack/db/blob/main/packages/db/src/query/ir.ts#L73)
+Defined in: [packages/db/src/query/ir.ts:82](https://github.com/TanStack/db/blob/main/packages/db/src/query/ir.ts#L82)
 
 **`Internal`**
 
@@ -69,7 +69,7 @@ BaseExpression.__returnType
 alias: string;
 ```
 
-Defined in: [packages/db/src/query/ir.ts:80](https://github.com/TanStack/db/blob/main/packages/db/src/query/ir.ts#L80)
+Defined in: [packages/db/src/query/ir.ts:89](https://github.com/TanStack/db/blob/main/packages/db/src/query/ir.ts#L89)
 
 ***
 
@@ -79,7 +79,7 @@ Defined in: [packages/db/src/query/ir.ts:80](https://github.com/TanStack/db/blob
 collection: CollectionImpl;
 ```
 
-Defined in: [packages/db/src/query/ir.ts:79](https://github.com/TanStack/db/blob/main/packages/db/src/query/ir.ts#L79)
+Defined in: [packages/db/src/query/ir.ts:88](https://github.com/TanStack/db/blob/main/packages/db/src/query/ir.ts#L88)
 
 ***
 
@@ -89,7 +89,7 @@ Defined in: [packages/db/src/query/ir.ts:79](https://github.com/TanStack/db/blob
 type: "collectionRef";
 ```
 
-Defined in: [packages/db/src/query/ir.ts:77](https://github.com/TanStack/db/blob/main/packages/db/src/query/ir.ts#L77)
+Defined in: [packages/db/src/query/ir.ts:86](https://github.com/TanStack/db/blob/main/packages/db/src/query/ir.ts#L86)
 
 #### Overrides
 

docs/reference/@tanstack/namespaces/IR/classes/ConditionalSelect.md

@@ -0,0 +1,98 @@
+---
+id: ConditionalSelect
+title: ConditionalSelect
+---
+
+# Class: ConditionalSelect
+
+Defined in: [packages/db/src/query/ir.ts:204](https://github.com/TanStack/db/blob/main/packages/db/src/query/ir.ts#L204)
+
+## Extends
+
+- `BaseExpression`
+
+## Constructors
+
+### Constructor
+
+```ts
+new ConditionalSelect(branches, defaultValue?): ConditionalSelect;
+```
+
+Defined in: [packages/db/src/query/ir.ts:206](https://github.com/TanStack/db/blob/main/packages/db/src/query/ir.ts#L206)
+
+#### Parameters
+
+##### branches
+
+[`ConditionalSelectBranch`](../type-aliases/ConditionalSelectBranch.md)[]
+
+##### defaultValue?
+
+[`SelectValueExpression`](../type-aliases/SelectValueExpression.md)
+
+#### Returns
+
+`ConditionalSelect`
+
+#### Overrides
+
+```ts
+BaseExpression.constructor
+```
+
+## Properties
+
+### \_\_returnType
+
+```ts
+readonly __returnType: any;
+```
+
+Defined in: [packages/db/src/query/ir.ts:82](https://github.com/TanStack/db/blob/main/packages/db/src/query/ir.ts#L82)
+
+**`Internal`**
+
+- Type brand for TypeScript inference
+
+#### Inherited from
+
+```ts
+BaseExpression.__returnType
+```
+
+***
+
+### branches
+
+```ts
+branches: ConditionalSelectBranch[];
+```
+
+Defined in: [packages/db/src/query/ir.ts:207](https://github.com/TanStack/db/blob/main/packages/db/src/query/ir.ts#L207)
+
+***
+
+### defaultValue?
+
+```ts
+optional defaultValue: SelectValueExpression;
+```
+
+Defined in: [packages/db/src/query/ir.ts:208](https://github.com/TanStack/db/blob/main/packages/db/src/query/ir.ts#L208)
+
+***
+
+### type
+
+```ts
+type: "conditionalSelect";
+```
+
+Defined in: [packages/db/src/query/ir.ts:205](https://github.com/TanStack/db/blob/main/packages/db/src/query/ir.ts#L205)
+
+#### Overrides
+
+```ts
+BaseExpression.type
+```

docs/reference/@tanstack/namespaces/IR/classes/Func.md

@@ -5,7 +5,7 @@ title: Func
 
 # Class: Func\<T\>
 
-Defined in: [packages/db/src/query/ir.ts:114](https://github.com/TanStack/db/blob/main/packages/db/src/query/ir.ts#L114)
+Defined in: [packages/db/src/query/ir.ts:151](https://github.com/TanStack/db/blob/main/packages/db/src/query/ir.ts#L151)
 
 ## Extends
 
@@ -25,7 +25,7 @@ Defined in: [packages/db/src/query/ir.ts:114](https://github.com/TanStack/db/blo
 new Func<T>(name, args): Func<T>;
 ```
 
-Defined in: [packages/db/src/query/ir.ts:116](https://github.com/TanStack/db/blob/main/packages/db/src/query/ir.ts#L116)
+Defined in: [packages/db/src/query/ir.ts:153](https://github.com/TanStack/db/blob/main/packages/db/src/query/ir.ts#L153)
 
 #### Parameters
 
@@ -55,7 +55,7 @@ BaseExpression<T>.constructor
 readonly __returnType: T;
 ```
 
-Defined in: [packages/db/src/query/ir.ts:73](https://github.com/TanStack/db/blob/main/packages/db/src/query/ir.ts#L73)
+Defined in: [packages/db/src/query/ir.ts:82](https://github.com/TanStack/db/blob/main/packages/db/src/query/ir.ts#L82)
 
 **`Internal`**
 
@@ -75,7 +75,7 @@ BaseExpression.__returnType
 args: BasicExpression<any>[];
 ```
 
-Defined in: [packages/db/src/query/ir.ts:118](https://github.com/TanStack/db/blob/main/packages/db/src/query/ir.ts#L118)
+Defined in: [packages/db/src/query/ir.ts:155](https://github.com/TanStack/db/blob/main/packages/db/src/query/ir.ts#L155)
 
 ***
 
@@ -85,7 +85,7 @@ Defined in: [packages/db/src/query/ir.ts:118](https://github.com/TanStack/db/blo
 name: string;
 ```
 
-Defined in: [packages/db/src/query/ir.ts:117](https://github.com/TanStack/db/blob/main/packages/db/src/query/ir.ts#L117)
+Defined in: [packages/db/src/query/ir.ts:154](https://github.com/TanStack/db/blob/main/packages/db/src/query/ir.ts#L154)
 
 ***
 
@@ -95,7 +95,7 @@ Defined in: [packages/db/src/query/ir.ts:117](https://github.com/TanStack/db/blo
 type: "func";
 ```
 
-Defined in: [packages/db/src/query/ir.ts:115](https://github.com/TanStack/db/blob/main/packages/db/src/query/ir.ts#L115)
+Defined in: [packages/db/src/query/ir.ts:152](https://github.com/TanStack/db/blob/main/packages/db/src/query/ir.ts#L152)
 
 #### Overrides