docs: regenerate API documentation

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
 

docs/reference/index.md

@@ -152,39 +152,47 @@ 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)
 - [CleanupFn](type-aliases/CleanupFn.md)
 - [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)
 - [DeleteMutationFnParams](type-aliases/DeleteMutationFnParams.md)
 - [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)
 - [InitialQueryBuilder](type-aliases/InitialQueryBuilder.md)
 - [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)
 - [LoadSubsetFn](type-aliases/LoadSubsetFn.md)
 - [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

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)

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`

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

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)

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`