diff --git a/docs/reference/classes/BaseQueryBuilder.md b/docs/reference/classes/BaseQueryBuilder.md
index 20f8e6ccd..0962768ed 100644
--- a/docs/reference/classes/BaseQueryBuilder.md
+++ b/docs/reference/classes/BaseQueryBuilder.md
@@ -120,7 +120,7 @@ A function that receives a row and returns the selected value
 
 ###### Returns
 
-[`QueryBuilder`](../type-aliases/QueryBuilder.md)\<`WithResult`\<`TContext`, `TFuncSelectResult`\>\>
+[`QueryBuilder`](../type-aliases/QueryBuilder.md)\<[`WithResult`](../type-aliases/WithResult.md)\<`TContext`, `TFuncSelectResult`\>\>
 
 A QueryBuilder with functional selection applied
 
@@ -273,10 +273,10 @@ An object with a single key-value pair where the key is the table alias and the
 #### Returns
 
 [`QueryBuilder`](../type-aliases/QueryBuilder.md)\<\{
-  `baseSchema`: `SchemaFromSource`\<`TSource`\>;
+  `baseSchema`: [`SchemaFromSource`](../type-aliases/SchemaFromSource.md)\<`TSource`\>;
   `fromSourceName`: keyof `TSource` & `string`;
   `hasJoins`: `false`;
-  `schema`: `SchemaFromSource`\<`TSource`\>;
+  `schema`: [`SchemaFromSource`](../type-aliases/SchemaFromSource.md)\<`TSource`\>;
 \}\>
 
 A QueryBuilder with the specified source
@@ -320,13 +320,13 @@ An object with a single key-value pair where the key is the table alias and the
 
 ##### onCallback
 
-`JoinOnCallback`\<`MergeContextForJoinCallback`\<`TContext`, \{ \[K in string \| number \| symbol\]: \{ \[K in string \| number \| symbol\]: TSource\[K\] extends CollectionImpl\<any, any, any, any, any\> ? InferCollectionType\<any\[any\]\> : TSource\[K\] extends QueryBuilder\<TContext\> ? \{ \[K in string \| number \| symbol\]: ((...)\[(...)\] extends object ? any\[any\] : (...) extends (...) ? (...) : (...))\[K\] \} : never \}\[K\] \}\>\>
+[`JoinOnCallback`](../type-aliases/JoinOnCallback.md)\<[`MergeContextForJoinCallback`](../type-aliases/MergeContextForJoinCallback.md)\<`TContext`, \{ \[K in string \| number \| symbol\]: \{ \[K in string \| number \| symbol\]: TSource\[K\] extends CollectionImpl\<any, any, any, any, any\> ? InferCollectionType\<any\[any\]\> : TSource\[K\] extends QueryBuilder\<TContext\> ? \{ \[K in string \| number \| symbol\]: ((...)\[(...)\] extends object ? any\[any\] : (...) extends (...) ? (...) : (...))\[K\] \} : never \}\[K\] \}\>\>
 
 A function that receives table references and returns the join condition
 
 #### Returns
 
-[`QueryBuilder`](../type-aliases/QueryBuilder.md)\<`MergeContextWithJoinType`\<`TContext`, `SchemaFromSource`\<`TSource`\>, `"full"`\>\>
+[`QueryBuilder`](../type-aliases/QueryBuilder.md)\<[`MergeContextWithJoinType`](../type-aliases/MergeContextWithJoinType.md)\<`TContext`, [`SchemaFromSource`](../type-aliases/SchemaFromSource.md)\<`TSource`\>, `"full"`\>\>
 
 A QueryBuilder with the full joined table available
 
@@ -355,7 +355,7 @@ Group rows by one or more columns for aggregation
 
 ##### callback
 
-`GroupByCallback`\<`TContext`\>
+[`GroupByCallback`](../type-aliases/GroupByCallback.md)\<`TContext`\>
 
 A function that receives table references and returns the field(s) to group by
 
@@ -404,7 +404,7 @@ Filter grouped rows based on aggregate conditions
 
 ##### callback
 
-`WhereCallback`\<`TContext`\>
+[`WhereCallback`](../type-aliases/WhereCallback.md)\<`TContext`\>
 
 A function that receives table references and returns an expression
 
@@ -465,13 +465,13 @@ An object with a single key-value pair where the key is the table alias and the
 
 ##### onCallback
 
-`JoinOnCallback`\<`MergeContextForJoinCallback`\<`TContext`, \{ \[K in string \| number \| symbol\]: \{ \[K in string \| number \| symbol\]: TSource\[K\] extends CollectionImpl\<any, any, any, any, any\> ? InferCollectionType\<any\[any\]\> : TSource\[K\] extends QueryBuilder\<TContext\> ? \{ \[K in string \| number \| symbol\]: ((...)\[(...)\] extends object ? any\[any\] : (...) extends (...) ? (...) : (...))\[K\] \} : never \}\[K\] \}\>\>
+[`JoinOnCallback`](../type-aliases/JoinOnCallback.md)\<[`MergeContextForJoinCallback`](../type-aliases/MergeContextForJoinCallback.md)\<`TContext`, \{ \[K in string \| number \| symbol\]: \{ \[K in string \| number \| symbol\]: TSource\[K\] extends CollectionImpl\<any, any, any, any, any\> ? InferCollectionType\<any\[any\]\> : TSource\[K\] extends QueryBuilder\<TContext\> ? \{ \[K in string \| number \| symbol\]: ((...)\[(...)\] extends object ? any\[any\] : (...) extends (...) ? (...) : (...))\[K\] \} : never \}\[K\] \}\>\>
 
 A function that receives table references and returns the join condition
 
 #### Returns
 
-[`QueryBuilder`](../type-aliases/QueryBuilder.md)\<`MergeContextWithJoinType`\<`TContext`, `SchemaFromSource`\<`TSource`\>, `"inner"`\>\>
+[`QueryBuilder`](../type-aliases/QueryBuilder.md)\<[`MergeContextWithJoinType`](../type-aliases/MergeContextWithJoinType.md)\<`TContext`, [`SchemaFromSource`](../type-aliases/SchemaFromSource.md)\<`TSource`\>, `"inner"`\>\>
 
 A QueryBuilder with the inner joined table available
 
@@ -519,7 +519,7 @@ An object with a single key-value pair where the key is the table alias and the
 
 ##### onCallback
 
-`JoinOnCallback`\<`MergeContextForJoinCallback`\<`TContext`, \{ \[K in string \| number \| symbol\]: \{ \[K in string \| number \| symbol\]: TSource\[K\] extends CollectionImpl\<any, any, any, any, any\> ? InferCollectionType\<any\[any\]\> : TSource\[K\] extends QueryBuilder\<TContext\> ? \{ \[K in string \| number \| symbol\]: ((...)\[(...)\] extends object ? any\[any\] : (...) extends (...) ? (...) : (...))\[K\] \} : never \}\[K\] \}\>\>
+[`JoinOnCallback`](../type-aliases/JoinOnCallback.md)\<[`MergeContextForJoinCallback`](../type-aliases/MergeContextForJoinCallback.md)\<`TContext`, \{ \[K in string \| number \| symbol\]: \{ \[K in string \| number \| symbol\]: TSource\[K\] extends CollectionImpl\<any, any, any, any, any\> ? InferCollectionType\<any\[any\]\> : TSource\[K\] extends QueryBuilder\<TContext\> ? \{ \[K in string \| number \| symbol\]: ((...)\[(...)\] extends object ? any\[any\] : (...) extends (...) ? (...) : (...))\[K\] \} : never \}\[K\] \}\>\>
 
 A function that receives table references and returns the join condition
 
@@ -531,7 +531,7 @@ The type of join: 'inner', 'left', 'right', or 'full' (defaults to 'left')
 
 #### Returns
 
-[`QueryBuilder`](../type-aliases/QueryBuilder.md)\<`MergeContextWithJoinType`\<`TContext`, `SchemaFromSource`\<`TSource`\>, `TJoinType`\>\>
+[`QueryBuilder`](../type-aliases/QueryBuilder.md)\<[`MergeContextWithJoinType`](../type-aliases/MergeContextWithJoinType.md)\<`TContext`, [`SchemaFromSource`](../type-aliases/SchemaFromSource.md)\<`TSource`\>, `TJoinType`\>\>
 
 A QueryBuilder with the joined table available
 
@@ -583,13 +583,13 @@ An object with a single key-value pair where the key is the table alias and the
 
 ##### onCallback
 
-`JoinOnCallback`\<`MergeContextForJoinCallback`\<`TContext`, \{ \[K in string \| number \| symbol\]: \{ \[K in string \| number \| symbol\]: TSource\[K\] extends CollectionImpl\<any, any, any, any, any\> ? InferCollectionType\<any\[any\]\> : TSource\[K\] extends QueryBuilder\<TContext\> ? \{ \[K in string \| number \| symbol\]: ((...)\[(...)\] extends object ? any\[any\] : (...) extends (...) ? (...) : (...))\[K\] \} : never \}\[K\] \}\>\>
+[`JoinOnCallback`](../type-aliases/JoinOnCallback.md)\<[`MergeContextForJoinCallback`](../type-aliases/MergeContextForJoinCallback.md)\<`TContext`, \{ \[K in string \| number \| symbol\]: \{ \[K in string \| number \| symbol\]: TSource\[K\] extends CollectionImpl\<any, any, any, any, any\> ? InferCollectionType\<any\[any\]\> : TSource\[K\] extends QueryBuilder\<TContext\> ? \{ \[K in string \| number \| symbol\]: ((...)\[(...)\] extends object ? any\[any\] : (...) extends (...) ? (...) : (...))\[K\] \} : never \}\[K\] \}\>\>
 
 A function that receives table references and returns the join condition
 
 #### Returns
 
-[`QueryBuilder`](../type-aliases/QueryBuilder.md)\<`MergeContextWithJoinType`\<`TContext`, `SchemaFromSource`\<`TSource`\>, `"left"`\>\>
+[`QueryBuilder`](../type-aliases/QueryBuilder.md)\<[`MergeContextWithJoinType`](../type-aliases/MergeContextWithJoinType.md)\<`TContext`, [`SchemaFromSource`](../type-aliases/SchemaFromSource.md)\<`TSource`\>, `"left"`\>\>
 
 A QueryBuilder with the left joined table available
 
@@ -693,7 +693,7 @@ Sort the query results by one or more columns
 
 ##### callback
 
-`OrderByCallback`\<`TContext`\>
+[`OrderByCallback`](../type-aliases/OrderByCallback.md)\<`TContext`\>
 
 A function that receives table references and returns the field to sort by
 
@@ -755,13 +755,13 @@ An object with a single key-value pair where the key is the table alias and the
 
 ##### onCallback
 
-`JoinOnCallback`\<`MergeContextForJoinCallback`\<`TContext`, \{ \[K in string \| number \| symbol\]: \{ \[K in string \| number \| symbol\]: TSource\[K\] extends CollectionImpl\<any, any, any, any, any\> ? InferCollectionType\<any\[any\]\> : TSource\[K\] extends QueryBuilder\<TContext\> ? \{ \[K in string \| number \| symbol\]: ((...)\[(...)\] extends object ? any\[any\] : (...) extends (...) ? (...) : (...))\[K\] \} : never \}\[K\] \}\>\>
+[`JoinOnCallback`](../type-aliases/JoinOnCallback.md)\<[`MergeContextForJoinCallback`](../type-aliases/MergeContextForJoinCallback.md)\<`TContext`, \{ \[K in string \| number \| symbol\]: \{ \[K in string \| number \| symbol\]: TSource\[K\] extends CollectionImpl\<any, any, any, any, any\> ? InferCollectionType\<any\[any\]\> : TSource\[K\] extends QueryBuilder\<TContext\> ? \{ \[K in string \| number \| symbol\]: ((...)\[(...)\] extends object ? any\[any\] : (...) extends (...) ? (...) : (...))\[K\] \} : never \}\[K\] \}\>\>
 
 A function that receives table references and returns the join condition
 
 #### Returns
 
-[`QueryBuilder`](../type-aliases/QueryBuilder.md)\<`MergeContextWithJoinType`\<`TContext`, `SchemaFromSource`\<`TSource`\>, `"right"`\>\>
+[`QueryBuilder`](../type-aliases/QueryBuilder.md)\<[`MergeContextWithJoinType`](../type-aliases/MergeContextWithJoinType.md)\<`TContext`, [`SchemaFromSource`](../type-aliases/SchemaFromSource.md)\<`TSource`\>, `"right"`\>\>
 
 A QueryBuilder with the right joined table available
 
@@ -802,7 +802,7 @@ A function that receives table references and returns an object with selected fi
 
 #### Returns
 
-[`QueryBuilder`](../type-aliases/QueryBuilder.md)\<`WithResult`\<`TContext`, `ResultTypeFromSelect`\<`TSelectObject`\>\>\>
+[`QueryBuilder`](../type-aliases/QueryBuilder.md)\<[`WithResult`](../type-aliases/WithResult.md)\<`TContext`, [`ResultTypeFromSelect`](../type-aliases/ResultTypeFromSelect.md)\<`TSelectObject`\>\>\>
 
 A QueryBuilder that returns only the selected fields
 
@@ -851,7 +851,7 @@ Filter rows based on a condition
 
 ##### callback
 
-`WhereCallback`\<`TContext`\>
+[`WhereCallback`](../type-aliases/WhereCallback.md)\<`TContext`\>
 
 A function that receives table references and returns an expression
 
diff --git a/docs/reference/index.md b/docs/reference/index.md
index 326486e10..d2387c6e3 100644
--- a/docs/reference/index.md
+++ b/docs/reference/index.md
@@ -152,6 +152,7 @@ title: "@tanstack/db"
 
 ## Type Aliases
 
+- [ApplyJoinOptionalityToMergedSchema](type-aliases/ApplyJoinOptionalityToMergedSchema.md)
 - [ChangeListener](type-aliases/ChangeListener.md)
 - [ChangeMessageOrDeleteKeyMessage](type-aliases/ChangeMessageOrDeleteKeyMessage.md)
 - [ChangesPayload](type-aliases/ChangesPayload.md)
@@ -159,6 +160,7 @@ title: "@tanstack/db"
 - [ClearStorageFn](type-aliases/ClearStorageFn.md)
 - [CollectionConfigSingleRowOption](type-aliases/CollectionConfigSingleRowOption.md)
 - [CollectionStatus](type-aliases/CollectionStatus.md)
+- [ContextSchema](type-aliases/ContextSchema.md)
 - [CursorExpressions](type-aliases/CursorExpressions.md)
 - [DeleteKeyMessage](type-aliases/DeleteKeyMessage.md)
 - [DeleteMutationFn](type-aliases/DeleteMutationFn.md)
@@ -166,11 +168,14 @@ title: "@tanstack/db"
 - [ExtractContext](type-aliases/ExtractContext.md)
 - [FieldPath](type-aliases/FieldPath.md)
 - [Fn](type-aliases/Fn.md)
+- [FunctionalHavingRow](type-aliases/FunctionalHavingRow.md)
 - [GetResult](type-aliases/GetResult.md)
 - [GetStorageSizeFn](type-aliases/GetStorageSizeFn.md)
+- [GroupByCallback](type-aliases/GroupByCallback.md)
 - [IndexConstructor](type-aliases/IndexConstructor.md)
 - [IndexOperation](type-aliases/IndexOperation.md)
 - [IndexResolver](type-aliases/IndexResolver.md)
+- [InferCollectionType](type-aliases/InferCollectionType.md)
 - [InferResultType](type-aliases/InferResultType.md)
 - [InferSchemaInput](type-aliases/InferSchemaInput.md)
 - [InferSchemaOutput](type-aliases/InferSchemaOutput.md)
@@ -178,6 +183,7 @@ title: "@tanstack/db"
 - [InputRow](type-aliases/InputRow.md)
 - [InsertMutationFn](type-aliases/InsertMutationFn.md)
 - [InsertMutationFnParams](type-aliases/InsertMutationFnParams.md)
+- [JoinOnCallback](type-aliases/JoinOnCallback.md)
 - [KeyedNamespacedRow](type-aliases/KeyedNamespacedRow.md)
 - [KeyedStream](type-aliases/KeyedStream.md)
 - [LiveQueryCollectionUtils](type-aliases/LiveQueryCollectionUtils.md)
@@ -185,6 +191,8 @@ title: "@tanstack/db"
 - [LoadSubsetOptions](type-aliases/LoadSubsetOptions.md)
 - [MakeOptional](type-aliases/MakeOptional.md)
 - [MaybeSingleResult](type-aliases/MaybeSingleResult.md)
+- [MergeContextForJoinCallback](type-aliases/MergeContextForJoinCallback.md)
+- [MergeContextWithJoinType](type-aliases/MergeContextWithJoinType.md)
 - [MutationFn](type-aliases/MutationFn.md)
 - [MutationFnParams](type-aliases/MutationFnParams.md)
 - [NamespacedAndKeyedStream](type-aliases/NamespacedAndKeyedStream.md)
@@ -194,12 +202,18 @@ title: "@tanstack/db"
 - [OperationType](type-aliases/OperationType.md)
 - [OperatorName](type-aliases/OperatorName.md)
 - [OptimisticChangeMessage](type-aliases/OptimisticChangeMessage.md)
+- [OrderByCallback](type-aliases/OrderByCallback.md)
+- [Prettify](type-aliases/Prettify.md)
 - [QueryBuilder](type-aliases/QueryBuilder.md)
 - [QueryResult](type-aliases/QueryResult.md)
 - [Ref](type-aliases/Ref.md)
+- [RefsForContext](type-aliases/RefsForContext.md)
 - [ResolveTransactionChanges](type-aliases/ResolveTransactionChanges.md)
 - [ResultStream](type-aliases/ResultStream.md)
+- [ResultTypeFromSelect](type-aliases/ResultTypeFromSelect.md)
 - [Row](type-aliases/Row.md)
+- [SchemaFromSource](type-aliases/SchemaFromSource.md)
+- [SelectObject](type-aliases/SelectObject.md)
 - [SingleResult](type-aliases/SingleResult.md)
 - [Source](type-aliases/Source.md)
 - [StandardSchema](type-aliases/StandardSchema.md)
@@ -219,6 +233,8 @@ title: "@tanstack/db"
 - [UpdateMutationFn](type-aliases/UpdateMutationFn.md)
 - [UpdateMutationFnParams](type-aliases/UpdateMutationFnParams.md)
 - [UtilsRecord](type-aliases/UtilsRecord.md)
+- [WhereCallback](type-aliases/WhereCallback.md)
+- [WithResult](type-aliases/WithResult.md)
 - [WritableDeep](type-aliases/WritableDeep.md)
 
 ## Variables
diff --git a/docs/reference/query-db-collection/interfaces/QueryCollectionMeta.md b/docs/reference/query-db-collection/interfaces/QueryCollectionMeta.md
index 7c2527c39..6d27f6bac 100644
--- a/docs/reference/query-db-collection/interfaces/QueryCollectionMeta.md
+++ b/docs/reference/query-db-collection/interfaces/QueryCollectionMeta.md
@@ -34,10 +34,10 @@ declare module "@tanstack/query-db-collection" {
 
 ## Properties
 
-### loadSubsetOptions
+### loadSubsetOptions?
 
 ```ts
-loadSubsetOptions: LoadSubsetOptions;
+optional loadSubsetOptions: LoadSubsetOptions;
 ```
 
 Defined in: [packages/query-db-collection/src/global.ts:31](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/global.ts#L31)
diff --git a/docs/reference/type-aliases/ApplyJoinOptionalityToMergedSchema.md b/docs/reference/type-aliases/ApplyJoinOptionalityToMergedSchema.md
new file mode 100644
index 000000000..372c4c51c
--- /dev/null
+++ b/docs/reference/type-aliases/ApplyJoinOptionalityToMergedSchema.md
@@ -0,0 +1,54 @@
+---
+id: ApplyJoinOptionalityToMergedSchema
+title: ApplyJoinOptionalityToMergedSchema
+---
+
+# Type Alias: ApplyJoinOptionalityToMergedSchema\<TExistingSchema, TNewSchema, TJoinType, TFromSourceName\>
+
+```ts
+type ApplyJoinOptionalityToMergedSchema<TExistingSchema, TNewSchema, TJoinType, TFromSourceName> = { [K in keyof TExistingSchema]: K extends TFromSourceName ? TJoinType extends "right" | "full" ? TExistingSchema[K] | undefined : TExistingSchema[K] : TExistingSchema[K] } & { [K in keyof TNewSchema]: TJoinType extends "left" | "full" ? TNewSchema[K] | undefined : TNewSchema[K] };
+```
+
+Defined in: [packages/db/src/query/builder/types.ts:622](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/types.ts#L622)
+
+ApplyJoinOptionalityToMergedSchema - Applies optionality rules when merging schemas
+
+This type implements the SQL join optionality semantics:
+
+**For Existing Tables**:
+- `RIGHT JOIN` or `FULL JOIN`: Main table (from fromSourceName) becomes optional
+- Other join types: Existing tables keep their current optionality
+- Previously joined tables: Keep their already-applied optionality
+
+**For New Tables**:
+- `LEFT JOIN` or `FULL JOIN`: New table becomes optional
+- `INNER JOIN` or `RIGHT JOIN`: New table remains required
+
+**Examples**:
+```sql
+FROM users LEFT JOIN orders  -- orders becomes optional
+FROM users RIGHT JOIN orders -- users becomes optional
+FROM users FULL JOIN orders  -- both become optional
+FROM users INNER JOIN orders -- both remain required
+```
+
+The intersection (&) ensures both existing and new schemas are merged
+into a single type while preserving all table references.
+
+## Type Parameters
+
+### TExistingSchema
+
+`TExistingSchema` *extends* [`ContextSchema`](ContextSchema.md)
+
+### TNewSchema
+
+`TNewSchema` *extends* [`ContextSchema`](ContextSchema.md)
+
+### TJoinType
+
+`TJoinType` *extends* `"inner"` \| `"left"` \| `"right"` \| `"full"` \| `"outer"` \| `"cross"`
+
+### TFromSourceName
+
+`TFromSourceName` *extends* `string`
diff --git a/docs/reference/type-aliases/ContextSchema.md b/docs/reference/type-aliases/ContextSchema.md
new file mode 100644
index 000000000..ef1f4f00c
--- /dev/null
+++ b/docs/reference/type-aliases/ContextSchema.md
@@ -0,0 +1,20 @@
+---
+id: ContextSchema
+title: ContextSchema
+---
+
+# Type Alias: ContextSchema
+
+```ts
+type ContextSchema = Record<string, unknown>;
+```
+
+Defined in: [packages/db/src/query/builder/types.ts:64](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/types.ts#L64)
+
+ContextSchema - The shape of available tables/collections in a query context
+
+This is simply a record mapping table aliases to their TypeScript types.
+It evolves as the query progresses:
+- Initial: Just the `from()` table
+- After joins: Includes all joined tables with proper optionality
+- In subqueries: May be a subset of the outer query's schema
diff --git a/docs/reference/type-aliases/FunctionalHavingRow.md b/docs/reference/type-aliases/FunctionalHavingRow.md
new file mode 100644
index 000000000..279104ac3
--- /dev/null
+++ b/docs/reference/type-aliases/FunctionalHavingRow.md
@@ -0,0 +1,34 @@
+---
+id: FunctionalHavingRow
+title: FunctionalHavingRow
+---
+
+# Type Alias: FunctionalHavingRow\<TContext\>
+
+```ts
+type FunctionalHavingRow<TContext> = TContext["schema"] & TContext["result"] extends object ? object : object;
+```
+
+Defined in: [packages/db/src/query/builder/types.ts:365](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/types.ts#L365)
+
+FunctionalHavingRow - Type for the row parameter in functional having callbacks
+
+Functional having callbacks receive a namespaced row that includes:
+- Table data from the schema (when available)
+- $selected: The SELECT result fields (when select() has been called)
+
+After `select()` is called, this type includes `$selected` which provides access
+to the SELECT result fields via `$selected.fieldName` syntax.
+
+Note: When used with GROUP BY, functional having receives `{ $selected: ... }` with the
+aggregated SELECT results. When used without GROUP BY, it receives the full namespaced row
+which includes both table data and `$selected`.
+
+Example: `({ $selected }) => $selected.sessionCount > 2`
+Example (no GROUP BY): `(row) => row.user.salary > 70000 && row.$selected.user_count > 2`
+
+## Type Parameters
+
+### TContext
+
+`TContext` *extends* [`Context`](../interfaces/Context.md)
diff --git a/docs/reference/type-aliases/GroupByCallback.md b/docs/reference/type-aliases/GroupByCallback.md
new file mode 100644
index 000000000..0ca5fd004
--- /dev/null
+++ b/docs/reference/type-aliases/GroupByCallback.md
@@ -0,0 +1,35 @@
+---
+id: GroupByCallback
+title: GroupByCallback
+---
+
+# Type Alias: GroupByCallback()\<TContext\>
+
+```ts
+type GroupByCallback<TContext> = (refs) => any;
+```
+
+Defined in: [packages/db/src/query/builder/types.ts:328](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/types.ts#L328)
+
+GroupByCallback - Type for groupBy clause callback functions
+
+These callbacks receive refs for all available tables and should return
+expressions that will be used for grouping query results.
+
+Example: `(refs) => refs.orders.status`
+
+## Type Parameters
+
+### TContext
+
+`TContext` *extends* [`Context`](../interfaces/Context.md)
+
+## Parameters
+
+### refs
+
+[`RefsForContext`](RefsForContext.md)\<`TContext`\>
+
+## Returns
+
+`any`
diff --git a/docs/reference/type-aliases/InferCollectionType.md b/docs/reference/type-aliases/InferCollectionType.md
new file mode 100644
index 000000000..0c804f43d
--- /dev/null
+++ b/docs/reference/type-aliases/InferCollectionType.md
@@ -0,0 +1,23 @@
+---
+id: InferCollectionType
+title: InferCollectionType
+---
+
+# Type Alias: InferCollectionType\<T\>
+
+```ts
+type InferCollectionType<T> = T extends CollectionImpl<infer TOutput, any, any, any, any> ? TOutput : never;
+```
+
+Defined in: [packages/db/src/query/builder/types.ts:85](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/types.ts#L85)
+
+InferCollectionType - Extracts the TypeScript type from a CollectionImpl
+
+This helper ensures we get the same type that was used when creating the collection itself.
+This can be an explicit type passed by the user or the schema output type.
+
+## Type Parameters
+
+### T
+
+`T`
diff --git a/docs/reference/type-aliases/JoinOnCallback.md b/docs/reference/type-aliases/JoinOnCallback.md
new file mode 100644
index 000000000..b7db28bfa
--- /dev/null
+++ b/docs/reference/type-aliases/JoinOnCallback.md
@@ -0,0 +1,39 @@
+---
+id: JoinOnCallback
+title: JoinOnCallback
+---
+
+# Type Alias: JoinOnCallback()\<TContext\>
+
+```ts
+type JoinOnCallback<TContext> = (refs) => any;
+```
+
+Defined in: [packages/db/src/query/builder/types.ts:344](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/types.ts#L344)
+
+JoinOnCallback - Type for join condition callback functions
+
+These callbacks receive refs for all available tables (including the newly
+joined table) and should return a boolean expression defining the join condition.
+
+Important: The newly joined table is NOT marked as optional in this callback,
+even for left/right/full joins, because optionality is applied AFTER the join
+condition is evaluated.
+
+Example: `(refs) => eq(refs.users.id, refs.orders.userId)`
+
+## Type Parameters
+
+### TContext
+
+`TContext` *extends* [`Context`](../interfaces/Context.md)
+
+## Parameters
+
+### refs
+
+[`RefsForContext`](RefsForContext.md)\<`TContext`\>
+
+## Returns
+
+`any`
diff --git a/docs/reference/type-aliases/MergeContextForJoinCallback.md b/docs/reference/type-aliases/MergeContextForJoinCallback.md
new file mode 100644
index 000000000..bfc431752
--- /dev/null
+++ b/docs/reference/type-aliases/MergeContextForJoinCallback.md
@@ -0,0 +1,108 @@
+---
+id: MergeContextForJoinCallback
+title: MergeContextForJoinCallback
+---
+
+# Type Alias: MergeContextForJoinCallback\<TContext, TNewSchema\>
+
+```ts
+type MergeContextForJoinCallback<TContext, TNewSchema> = object;
+```
+
+Defined in: [packages/db/src/query/builder/types.ts:807](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/types.ts#L807)
+
+MergeContextForJoinCallback - Special context for join condition callbacks
+
+This type creates a context specifically for the `onCallback` parameter of join operations.
+The key difference from `MergeContextWithJoinType` is that NO optionality is applied here.
+
+**Why No Optionality?**
+In SQL, join conditions are evaluated BEFORE optionality is determined. Both tables
+must be treated as available (non-optional) within the join condition itself.
+Optionality is only applied to the result AFTER the join logic executes.
+
+**Example**:
+```typescript
+.from({ users })
+.leftJoin({ orders }, ({ users, orders }) => {
+  // users is NOT optional here - we can access users.id directly
+  // orders is NOT optional here - we can access orders.userId directly
+  return eq(users.id, orders.userId)
+})
+.where(({ orders }) => {
+  // NOW orders is optional because it's after the LEFT JOIN
+  return orders?.status === 'pending'
+})
+```
+
+The simple intersection (&) merges schemas without any optionality transformation.
+
+## Type Parameters
+
+### TContext
+
+`TContext` *extends* [`Context`](../interfaces/Context.md)
+
+### TNewSchema
+
+`TNewSchema` *extends* [`ContextSchema`](ContextSchema.md)
+
+## Properties
+
+### baseSchema
+
+```ts
+baseSchema: TContext["baseSchema"];
+```
+
+Defined in: [packages/db/src/query/builder/types.ts:811](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/types.ts#L811)
+
+***
+
+### fromSourceName
+
+```ts
+fromSourceName: TContext["fromSourceName"];
+```
+
+Defined in: [packages/db/src/query/builder/types.ts:814](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/types.ts#L814)
+
+***
+
+### hasJoins
+
+```ts
+hasJoins: true;
+```
+
+Defined in: [packages/db/src/query/builder/types.ts:815](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/types.ts#L815)
+
+***
+
+### joinTypes
+
+```ts
+joinTypes: TContext["joinTypes"] extends Record<string, any> ? TContext["joinTypes"] : object;
+```
+
+Defined in: [packages/db/src/query/builder/types.ts:816](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/types.ts#L816)
+
+***
+
+### result
+
+```ts
+result: TContext["result"];
+```
+
+Defined in: [packages/db/src/query/builder/types.ts:819](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/types.ts#L819)
+
+***
+
+### schema
+
+```ts
+schema: TContext["schema"] & TNewSchema;
+```
+
+Defined in: [packages/db/src/query/builder/types.ts:813](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/types.ts#L813)
diff --git a/docs/reference/type-aliases/MergeContextWithJoinType.md b/docs/reference/type-aliases/MergeContextWithJoinType.md
new file mode 100644
index 000000000..0bac1b7db
--- /dev/null
+++ b/docs/reference/type-aliases/MergeContextWithJoinType.md
@@ -0,0 +1,86 @@
+---
+id: MergeContextWithJoinType
+title: MergeContextWithJoinType
+---
+
+# Type Alias: MergeContextWithJoinType\<TContext, TNewSchema, TJoinType\>
+
+```ts
+type MergeContextWithJoinType<TContext, TNewSchema, TJoinType> = object & PreserveSingleResultFlag<TContext["singleResult"]>;
+```
+
+Defined in: [packages/db/src/query/builder/types.ts:573](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/types.ts#L573)
+
+MergeContextWithJoinType - Creates a new context after a join operation
+
+This is the core type that handles the complex logic of merging schemas
+when tables are joined, applying the correct optionality based on join type.
+
+**Key Responsibilities**:
+1. **Schema Merging**: Combines existing schema with newly joined tables
+2. **Optionality Logic**: Applies join-specific optionality rules:
+   - `LEFT JOIN`: New table becomes optional
+   - `RIGHT JOIN`: Existing tables become optional
+   - `FULL JOIN`: Both existing and new become optional
+   - `INNER JOIN`: No tables become optional
+3. **State Tracking**: Updates hasJoins and joinTypes for future operations
+
+**Context Evolution**:
+- `baseSchema`: Unchanged (always the original `from()` tables)
+- `schema`: Expanded with new tables and proper optionality
+- `hasJoins`: Set to true
+- `joinTypes`: Updated to track this join type
+- `result`: Preserved from previous operations
+- `singleResult`: Preserved only if already true (via PreserveSingleResultFlag)
+
+## Type Declaration
+
+### baseSchema
+
+```ts
+baseSchema: TContext["baseSchema"];
+```
+
+### fromSourceName
+
+```ts
+fromSourceName: TContext["fromSourceName"];
+```
+
+### hasJoins
+
+```ts
+hasJoins: true;
+```
+
+### joinTypes
+
+```ts
+joinTypes: TContext["joinTypes"] extends Record<string, any> ? TContext["joinTypes"] : object & { [K in keyof TNewSchema & string]: TJoinType };
+```
+
+### result
+
+```ts
+result: TContext["result"];
+```
+
+### schema
+
+```ts
+schema: ApplyJoinOptionalityToMergedSchema<TContext["schema"], TNewSchema, TJoinType, TContext["fromSourceName"]>;
+```
+
+## Type Parameters
+
+### TContext
+
+`TContext` *extends* [`Context`](../interfaces/Context.md)
+
+### TNewSchema
+
+`TNewSchema` *extends* [`ContextSchema`](ContextSchema.md)
+
+### TJoinType
+
+`TJoinType` *extends* `"inner"` \| `"left"` \| `"right"` \| `"full"` \| `"outer"` \| `"cross"`
diff --git a/docs/reference/type-aliases/OrderByCallback.md b/docs/reference/type-aliases/OrderByCallback.md
new file mode 100644
index 000000000..6810877b3
--- /dev/null
+++ b/docs/reference/type-aliases/OrderByCallback.md
@@ -0,0 +1,35 @@
+---
+id: OrderByCallback
+title: OrderByCallback
+---
+
+# Type Alias: OrderByCallback()\<TContext\>
+
+```ts
+type OrderByCallback<TContext> = (refs) => any;
+```
+
+Defined in: [packages/db/src/query/builder/types.ts:292](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/types.ts#L292)
+
+OrderByCallback - Type for orderBy clause callback functions
+
+Similar to WhereCallback, these receive refs for all available tables
+and should return expressions that will be used for sorting.
+
+Example: `(refs) => refs.users.createdAt`
+
+## Type Parameters
+
+### TContext
+
+`TContext` *extends* [`Context`](../interfaces/Context.md)
+
+## Parameters
+
+### refs
+
+[`RefsForContext`](RefsForContext.md)\<`TContext`\>
+
+## Returns
+
+`any`
diff --git a/docs/reference/type-aliases/Prettify.md b/docs/reference/type-aliases/Prettify.md
new file mode 100644
index 000000000..5700563ec
--- /dev/null
+++ b/docs/reference/type-aliases/Prettify.md
@@ -0,0 +1,20 @@
+---
+id: Prettify
+title: Prettify
+---
+
+# Type Alias: Prettify\<T\>
+
+```ts
+type Prettify<T> = { [K in keyof T]: T[K] } & object;
+```
+
+Defined in: [packages/db/src/query/builder/types.ts:845](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/types.ts#L845)
+
+Prettify - Utility type for clean IDE display
+
+## Type Parameters
+
+### T
+
+`T`
diff --git a/docs/reference/type-aliases/RefsForContext.md b/docs/reference/type-aliases/RefsForContext.md
new file mode 100644
index 000000000..b4540de81
--- /dev/null
+++ b/docs/reference/type-aliases/RefsForContext.md
@@ -0,0 +1,40 @@
+---
+id: RefsForContext
+title: RefsForContext
+---
+
+# Type Alias: RefsForContext\<TContext\>
+
+```ts
+type RefsForContext<TContext> = { [K in keyof TContext["schema"]]: IsNonExactOptional<TContext["schema"][K]> extends true ? IsNonExactNullable<TContext["schema"][K]> extends true ? Ref<NonNullable<TContext["schema"][K]>> | undefined : Ref<NonUndefined<TContext["schema"][K]>> | undefined : IsNonExactNullable<TContext["schema"][K]> extends true ? Ref<NonNull<TContext["schema"][K]>> | null : Ref<TContext["schema"][K]> } & TContext["result"] extends object ? object : object;
+```
+
+Defined in: [packages/db/src/query/builder/types.ts:391](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/types.ts#L391)
+
+RefProxyForContext - Creates ref proxies for all tables/collections in a query context
+
+This is the main entry point for creating ref objects in query builder callbacks.
+It handles optionality by placing undefined/null OUTSIDE the RefProxy to enable
+JavaScript's optional chaining operator (?.):
+
+Examples:
+- Required field: `RefProxy<User>` → user.name works
+- Optional field: `RefProxy<User> | undefined` → user?.name works
+- Nullable field: `RefProxy<User> | null` → user?.name works
+- Both optional and nullable: `RefProxy<User> | undefined` → user?.name works
+
+The key insight is that `RefProxy<User | undefined>` would NOT allow `user?.name`
+because the undefined is "inside" the proxy, but `RefProxy<User> | undefined`
+does allow it because the undefined is "outside" the proxy.
+
+The logic prioritizes optional chaining by always placing `undefined` outside when
+a type is both optional and nullable (e.g., `string | null | undefined`).
+
+After `select()` is called, this type also includes `$selected` which provides access
+to the SELECT result fields via `$selected.fieldName` syntax.
+
+## Type Parameters
+
+### TContext
+
+`TContext` *extends* [`Context`](../interfaces/Context.md)
diff --git a/docs/reference/type-aliases/ResultTypeFromSelect.md b/docs/reference/type-aliases/ResultTypeFromSelect.md
new file mode 100644
index 000000000..0bbf59cab
--- /dev/null
+++ b/docs/reference/type-aliases/ResultTypeFromSelect.md
@@ -0,0 +1,53 @@
+---
+id: ResultTypeFromSelect
+title: ResultTypeFromSelect
+---
+
+# Type Alias: ResultTypeFromSelect\<TSelectObject\>
+
+```ts
+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<(...)> | undefined ? ExtractRef<(...)> | undefined : (...)[(...)] extends (...) | (...) ? (...) | (...) : (...) extends (...) ? (...) : (...) }>>;
+```
+
+Defined in: [packages/db/src/query/builder/types.ts:226](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/types.ts#L226)
+
+ResultTypeFromSelect - Infers the result type from a select object
+
+This complex type transforms the input to `select()` into the actual TypeScript
+type that the query will return. It handles all the different kinds of values
+that can appear in a select clause:
+
+**Ref/RefProxy Extraction**:
+- `RefProxy<T>` → `T`: Extracts the underlying type
+- `Ref<T> | undefined` → `T | undefined`: Preserves optionality
+- `Ref<T> | null` → `T | null`: Preserves nullability
+
+**Expression Types**:
+- `BasicExpression<T>` → `T`: Function results like `upper()` → `string`
+- `Aggregate<T>` → `T`: Aggregation results like `count()` → `number`
+
+**JavaScript Literals** (pass through as-is):
+- `string` → `string`: String literals remain strings
+- `number` → `number`: Numeric literals remain numbers
+- `boolean` → `boolean`: Boolean literals remain booleans
+- `null` → `null`: Explicit null remains null
+- `undefined` → `undefined`: Direct undefined values
+
+**Nested Objects** (recursive):
+- Plain objects are recursively processed to handle nested projections
+- RefProxy objects are detected and their types extracted
+
+Example transformation:
+```typescript
+// Input:
+{ id: Ref<number>, name: Ref<string>, status: 'active', count: 42, profile: { bio: Ref<string> } }
+
+// Output:
+{ id: number, name: string, status: 'active', count: 42, profile: { bio: string } }
+```
+
+## Type Parameters
+
+### TSelectObject
+
+`TSelectObject`
diff --git a/docs/reference/type-aliases/SchemaFromSource.md b/docs/reference/type-aliases/SchemaFromSource.md
new file mode 100644
index 000000000..ee81b1c0e
--- /dev/null
+++ b/docs/reference/type-aliases/SchemaFromSource.md
@@ -0,0 +1,27 @@
+---
+id: SchemaFromSource
+title: SchemaFromSource
+---
+
+# Type Alias: SchemaFromSource\<T\>
+
+```ts
+type SchemaFromSource<T> = Prettify<{ [K in keyof T]: T[K] extends CollectionImpl<any, any, any, any, any> ? InferCollectionType<T[K]> : T[K] extends QueryBuilder<infer TContext> ? GetResult<TContext> : never }>;
+```
+
+Defined in: [packages/db/src/query/builder/types.ts:98](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/types.ts#L98)
+
+SchemaFromSource - Converts a Source definition into a ContextSchema
+
+This transforms the input to `from()` into the schema format used throughout
+the query builder. For each alias in the source:
+- Collections → their inferred TypeScript type
+- Subqueries → their result type (what they would return if executed)
+
+The `Prettify` wrapper ensures clean type display in IDEs.
+
+## Type Parameters
+
+### T
+
+`T` *extends* [`Source`](Source.md)
diff --git a/docs/reference/type-aliases/SelectObject.md b/docs/reference/type-aliases/SelectObject.md
new file mode 100644
index 000000000..b3ccc1877
--- /dev/null
+++ b/docs/reference/type-aliases/SelectObject.md
@@ -0,0 +1,24 @@
+---
+id: SelectObject
+title: SelectObject
+---
+
+# Type Alias: SelectObject\<T\>
+
+```ts
+type SelectObject<T> = T;
+```
+
+Defined in: [packages/db/src/query/builder/types.ts:188](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/types.ts#L188)
+
+SelectObject - Wrapper type for select clause objects
+
+This ensures that objects passed to `select()` have valid SelectValue types
+for all their properties. It's a simple wrapper that provides better error
+messages when invalid selections are attempted.
+
+## Type Parameters
+
+### T
+
+`T` *extends* `SelectShape` = `SelectShape`
diff --git a/docs/reference/type-aliases/WhereCallback.md b/docs/reference/type-aliases/WhereCallback.md
new file mode 100644
index 000000000..2905e7677
--- /dev/null
+++ b/docs/reference/type-aliases/WhereCallback.md
@@ -0,0 +1,36 @@
+---
+id: WhereCallback
+title: WhereCallback
+---
+
+# Type Alias: WhereCallback()\<TContext\>
+
+```ts
+type WhereCallback<TContext> = (refs) => any;
+```
+
+Defined in: [packages/db/src/query/builder/types.ts:123](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/types.ts#L123)
+
+WhereCallback - Type for where/having clause callback functions
+
+These callbacks receive a `refs` object containing RefProxy instances for
+all available tables. The callback should return a boolean expression
+that will be used to filter query results.
+
+Example: `(refs) => eq(refs.users.age, 25)`
+
+## Type Parameters
+
+### TContext
+
+`TContext` *extends* [`Context`](../interfaces/Context.md)
+
+## Parameters
+
+### refs
+
+[`RefsForContext`](RefsForContext.md)\<`TContext`\>
+
+## Returns
+
+`any`
diff --git a/docs/reference/type-aliases/WithResult.md b/docs/reference/type-aliases/WithResult.md
new file mode 100644
index 000000000..cb968175c
--- /dev/null
+++ b/docs/reference/type-aliases/WithResult.md
@@ -0,0 +1,35 @@
+---
+id: WithResult
+title: WithResult
+---
+
+# Type Alias: WithResult\<TContext, TResult\>
+
+```ts
+type WithResult<TContext, TResult> = Prettify<Omit<TContext, "result"> & object>;
+```
+
+Defined in: [packages/db/src/query/builder/types.ts:836](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/types.ts#L836)
+
+WithResult - Updates a context with a new result type after select()
+
+This utility type is used internally when the `select()` method is called
+to update the context with the projected result type. It preserves all
+other context properties while replacing the `result` field.
+
+**Usage**:
+When `select()` is called, the query builder uses this type to create
+a new context where `result` contains the shape of the selected fields.
+
+The double `Prettify` ensures both the overall context and the nested
+result type display cleanly in IDEs.
+
+## Type Parameters
+
+### TContext
+
+`TContext` *extends* [`Context`](../interfaces/Context.md)
+
+### TResult
+
+`TResult`