@tanstack/db 0.5.30 → 0.5.32

package/src/query/builder/types.ts

@@ -227,18 +227,28 @@ export type ResultTypeFromSelect<TSelectObject> = WithoutRefBrand<
   Prettify<{
     [K in keyof TSelectObject]: NeedsExtraction<TSelectObject[K]> extends true
       ? ExtractExpressionType<TSelectObject[K]>
-      : TSelectObject[K] extends Ref<infer _T>
+      : // Ref (full object ref or spread with RefBrand) - recursively process properties
+        TSelectObject[K] extends Ref<infer _T>
         ? ExtractRef<TSelectObject[K]>
-        : TSelectObject[K] extends RefLeaf<infer T>
-          ? T
-          : TSelectObject[K] extends RefLeaf<infer T> | undefined
+        : // RefLeaf (simple property ref like user.name)
+          TSelectObject[K] extends RefLeaf<infer T>
+          ? IsNullableRef<TSelectObject[K]> extends true
             ? 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
+            : T
+          : // RefLeaf | undefined (schema-optional field)
+            TSelectObject[K] extends RefLeaf<infer T> | undefined
+            ? T | undefined
+            : // RefLeaf | null (schema-nullable field)
+              TSelectObject[K] extends RefLeaf<infer T> | null
+              ? IsNullableRef<Exclude<TSelectObject[K], null>> extends true
+                ? T | null | undefined
+                : T | null
+              : // Ref | undefined (optional object-type schema field)
+                TSelectObject[K] extends Ref<infer _T> | undefined
+                ? ExtractRef<Exclude<TSelectObject[K], undefined>> | undefined
+                : // Ref | null (nullable object-type schema field)
+                  TSelectObject[K] extends Ref<infer _T> | null
+                  ? ExtractRef<Exclude<TSelectObject[K], null>> | null
                   : TSelectObject[K] extends Aggregate<infer T>
                     ? T
                     : TSelectObject[K] extends
@@ -366,24 +376,17 @@ export type FunctionalHavingRow<TContext extends Context> = TContext[`schema`] &
   (TContext[`result`] extends object ? { $selected: TContext[`result`] } : {})
 
 /**
- * RefProxyForContext - Creates ref proxies for all tables/collections in a query context
+ * RefsForContext - 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 (?.):
+ * For nullable join sides (left/right/full joins), it produces `Ref<T, true>` instead
+ * of `Ref<T> | undefined`. This accurately reflects that the proxy object is always
+ * present at build time (it's a truthy proxy that records property access paths),
+ * while the `Nullable` flag ensures the result type correctly includes `| undefined`.
  *
  * 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`).
+ * - Required field: `Ref<User>` → user.name works, result is T
+ * - Nullable join side: `Ref<User, true>` → user.name works, result is T | undefined
  *
  * After `select()` is called, this type also includes `$selected` which provides access
  * to the SELECT result fields via `$selected.fieldName` syntax.
@@ -394,17 +397,17 @@ export type RefsForContext<TContext extends Context> = {
   > extends true
     ? IsNonExactNullable<TContext[`schema`][K]> extends true
       ? // T is both non-exact optional and non-exact nullable (e.g., string | null | undefined)
-          // Extract the non-undefined and non-null part and place undefined outside
-          Ref<NonNullable<TContext[`schema`][K]>> | undefined
+        // Extract the non-undefined and non-null part, mark as nullable ref
+        Ref<NonNullable<TContext[`schema`][K]>, true>
       : // T is optional (T | undefined) but not exactly undefined, and not nullable
-          // Extract the non-undefined part and place undefined outside
-          Ref<NonUndefined<TContext[`schema`][K]>> | undefined
+        // Extract the non-undefined part, mark as nullable ref
+        Ref<NonUndefined<TContext[`schema`][K]>, true>
     : IsNonExactNullable<TContext[`schema`][K]> extends true
       ? // T is nullable (T | null) but not exactly null, and not optional
-        // Extract the non-null part and place null outside
-        Ref<NonNull<TContext[`schema`][K]>> | null
+        // Extract the non-null part, mark as nullable ref
+        Ref<NonNull<TContext[`schema`][K]>, true>
       : // T is exactly undefined, exactly null, or neither optional nor nullable
-        // Wrap in RefProxy as-is (includes exact undefined, exact null, and normal types)
+        // Wrap in Ref as-is (includes exact undefined, exact null, and normal types)
         Ref<TContext[`schema`][K]>
 } & (TContext[`result`] extends object
   ? { $selected: Ref<TContext[`result`]> }
@@ -479,41 +482,44 @@ type NonNull<T> = T extends null ? never : T
  * It provides a recursive interface that allows nested property access while
  * preserving optionality and nullability correctly.
  *
- * When spread in select clauses, it correctly produces the underlying data type
- * without Ref wrappers, enabling clean spread operations.
+ * The `Nullable` parameter indicates whether this ref comes from a nullable
+ * join side (left/right/full). When `true`, the `Nullable` flag propagates
+ * through all nested property accesses, ensuring the result type includes
+ * `| undefined` for all fields accessed through this ref.
  *
  * Example usage:
  * ```typescript
- * // Clean interface - no internal properties visible
- * const users: Ref<{ id: number; profile?: { bio: string } }> = { ... }
- * users.id // Ref<number> - clean display
- * users.profile?.bio // Ref<string> - nested optional access works
+ * // Non-nullable ref (inner join or from table):
+ * select(({ user }) => ({ name: user.name })) // result: string
+ *
+ * // Nullable ref (left join right side):
+ * select(({ dept }) => ({ name: dept.name })) // result: string | undefined
  *
  * // Spread operations work cleanly:
  * select(({ user }) => ({ ...user })) // Returns User type, not Ref types
  * ```
  */
-export type Ref<T = any> = {
+export type Ref<T = any, Nullable extends boolean = false> = {
   [K in keyof T]: IsNonExactOptional<T[K]> extends true
     ? IsNonExactNullable<T[K]> extends true
       ? // Both optional and nullable
         IsPlainObject<NonNullable<T[K]>> extends true
-        ? Ref<NonNullable<T[K]>> | undefined
-        : RefLeaf<NonNullable<T[K]>> | undefined
+        ? Ref<NonNullable<T[K]>, Nullable> | undefined
+        : RefLeaf<NonNullable<T[K]>, Nullable> | undefined
       : // Optional only
         IsPlainObject<NonUndefined<T[K]>> extends true
-        ? Ref<NonUndefined<T[K]>> | undefined
-        : RefLeaf<NonUndefined<T[K]>> | undefined
+        ? Ref<NonUndefined<T[K]>, Nullable> | undefined
+        : RefLeaf<NonUndefined<T[K]>, Nullable> | undefined
     : IsNonExactNullable<T[K]> extends true
       ? // Nullable only
         IsPlainObject<NonNull<T[K]>> extends true
-        ? Ref<NonNull<T[K]>> | null
-        : RefLeaf<NonNull<T[K]>> | null
+        ? Ref<NonNull<T[K]>, Nullable> | null
+        : RefLeaf<NonNull<T[K]>, Nullable> | null
       : // Required
         IsPlainObject<T[K]> extends true
-        ? Ref<T[K]>
-        : RefLeaf<T[K]>
-} & RefLeaf<T>
+        ? Ref<T[K], Nullable>
+        : RefLeaf<T[K], Nullable>
+} & RefLeaf<T, Nullable>
 
 /**
  * Ref - The user-facing ref type with clean IDE display
@@ -527,11 +533,19 @@ export type Ref<T = any> = {
  * - No internal properties like __refProxy, __path, __type are visible
  */
 declare const RefBrand: unique symbol
-export type RefLeaf<T = any> = { readonly [RefBrand]?: T }
+declare const NullableBrand: unique symbol
+export type RefLeaf<T = any, Nullable extends boolean = false> = {
+  readonly [RefBrand]?: T
+} & ([Nullable] extends [true] ? { readonly [NullableBrand]?: true } : {})
+
+// Detect NullableBrand by checking for the key's presence
+type IsNullableRef<T> = typeof NullableBrand extends keyof T ? true : false
 
-// Helper type to remove RefBrand from objects
+// Helper type to remove RefBrand and NullableBrand from objects
 type WithoutRefBrand<T> =
-  T extends Record<string, any> ? Omit<T, typeof RefBrand> : T
+  T extends Record<string, any>
+    ? Omit<T, typeof RefBrand | typeof NullableBrand>
+    : T
 
 /**
  * PreserveSingleResultFlag - Conditionally includes the singleResult flag

package/src/query/compiler/index.ts

@@ -4,6 +4,7 @@ import {
   CollectionInputNotFoundError,
   DistinctRequiresSelectError,
   DuplicateAliasInSubqueryError,
+  FnSelectWithGroupByError,
   HavingRequiresGroupByError,
   LimitOffsetRequireOrderByError,
   UnsupportedFromTypeError,
@@ -218,6 +219,10 @@ export function compileQuery(
     throw new DistinctRequiresSelectError()
   }
 
+  if (query.fnSelect && query.groupBy && query.groupBy.length > 0) {
+    throw new FnSelectWithGroupByError()
+  }
+
   // Process the SELECT clause early - always create $selected
   // This eliminates duplication and allows for DISTINCT implementation
   if (query.fnSelect) {

package/src/query/index.ts

@@ -74,6 +74,9 @@ export {
   liveQueryCollectionOptions,
 } from './live-query-collection.js'
 
+// One-shot query execution
+export { queryOnce, type QueryOnceConfig } from './query-once.js'
+
 export { type LiveQueryCollectionConfig } from './live/types.js'
 export { type LiveQueryCollectionUtils } from './live/collection-config-builder.js'
 

package/src/query/query-once.ts

@@ -0,0 +1,115 @@
+import { createLiveQueryCollection } from './live-query-collection.js'
+import type { InitialQueryBuilder, QueryBuilder } from './builder/index.js'
+import type { Context, InferResultType } from './builder/types.js'
+
+/**
+ * Configuration options for queryOnce
+ */
+export interface QueryOnceConfig<TContext extends Context> {
+  /**
+   * Query builder function that defines the query
+   */
+  query:
+    | ((q: InitialQueryBuilder) => QueryBuilder<TContext>)
+    | QueryBuilder<TContext>
+  // Future: timeout, signal, etc.
+}
+
+// Overload 1: Simple query function returning array (non-single result)
+/**
+ * Executes a one-shot query and returns the results as an array.
+ *
+ * This function creates a live query collection, preloads it, extracts the results,
+ * and automatically cleans up the collection. It's ideal for:
+ * - AI/LLM context building
+ * - Data export
+ * - Background processing
+ * - Testing
+ *
+ * @param queryFn - A function that receives the query builder and returns a query
+ * @returns A promise that resolves to an array of query results
+ *
+ * @example
+ * ```typescript
+ * // Basic query
+ * const users = await queryOnce((q) =>
+ *   q.from({ user: usersCollection })
+ * )
+ *
+ * // With filtering and projection
+ * const activeUserNames = await queryOnce((q) =>
+ *   q.from({ user: usersCollection })
+ *    .where(({ user }) => eq(user.active, true))
+ *    .select(({ user }) => ({ name: user.name }))
+ * )
+ * ```
+ */
+export function queryOnce<TContext extends Context>(
+  queryFn: (q: InitialQueryBuilder) => QueryBuilder<TContext>,
+): Promise<InferResultType<TContext>>
+
+// Overload 2: Config object form returning array (non-single result)
+/**
+ * Executes a one-shot query using a configuration object.
+ *
+ * @param config - Configuration object with the query function
+ * @returns A promise that resolves to an array of query results
+ *
+ * @example
+ * ```typescript
+ * const recentOrders = await queryOnce({
+ *   query: (q) =>
+ *     q.from({ order: ordersCollection })
+ *      .orderBy(({ order }) => desc(order.createdAt))
+ *      .limit(100),
+ * })
+ * ```
+ */
+export function queryOnce<TContext extends Context>(
+  config: QueryOnceConfig<TContext>,
+): Promise<InferResultType<TContext>>
+
+// Implementation
+export async function queryOnce<TContext extends Context>(
+  configOrQuery:
+    | QueryOnceConfig<TContext>
+    | ((q: InitialQueryBuilder) => QueryBuilder<TContext>),
+): Promise<InferResultType<TContext>> {
+  // Normalize input
+  const config: QueryOnceConfig<TContext> =
+    typeof configOrQuery === `function`
+      ? { query: configOrQuery }
+      : configOrQuery
+
+  const query = (q: InitialQueryBuilder) => {
+    const queryConfig = config.query
+    return typeof queryConfig === `function` ? queryConfig(q) : queryConfig
+  }
+
+  // Create collection with minimal GC time; preload handles sync start
+  const collection = createLiveQueryCollection({
+    query,
+    gcTime: 1, // Cleanup in next tick when no subscribers (0 disables GC)
+  })
+
+  try {
+    // Wait for initial data load
+    await collection.preload()
+
+    // Check if this is a single-result query (findOne was called)
+    const isSingleResult =
+      (collection.config as { singleResult?: boolean }).singleResult === true
+
+    // Extract and return results
+    if (isSingleResult) {
+      const first = collection.values().next().value as
+        | InferResultType<TContext>
+        | undefined
+      return first as InferResultType<TContext>
+    }
+    return collection.toArray as InferResultType<TContext>
+  } finally {
+    // Always cleanup, even on error
+    await collection.cleanup()
+  }
+}

package/src/query/subset-dedupe.ts

@@ -126,28 +126,29 @@ export class DeduplicatedLoadSubset {
       return prom
     }
 
-    // Not fully covered by existing data
-    // Compute the subset of data that is not covered by the existing data
-    // such that we only have to load that subset of missing data
-    const clonedOptions = cloneOptions(options)
+    // Not fully covered by existing data — load the missing subset.
+    // We need two clones: trackingOptions preserves the original predicate for
+    // accurate tracking (e.g., where=undefined means "all data"), while loadOptions
+    // may be narrowed with a difference expression for the actual backend request.
+    const trackingOptions = cloneOptions(options)
+    const loadOptions = cloneOptions(options)
     if (this.unlimitedWhere !== undefined && options.limit === undefined) {
       // Compute difference to get only the missing data
       // We can only do this for unlimited queries
       // and we can only remove data that was loaded from unlimited queries
       // because with limited queries we have no way to express that we already loaded part of the matching data
-      clonedOptions.where =
-        minusWherePredicates(clonedOptions.where, this.unlimitedWhere) ??
-        clonedOptions.where
+      loadOptions.where =
+        minusWherePredicates(loadOptions.where, this.unlimitedWhere) ??
+        loadOptions.where
     }
 
     // Call underlying loadSubset to load the missing data
-    const resultPromise = this._loadSubset(clonedOptions)
+    const resultPromise = this._loadSubset(loadOptions)
 
     // Handle both sync (true) and async (Promise<void>) return values
     if (resultPromise === true) {
-      // Sync return - update tracking synchronously
-      // Clone options before storing to protect against caller mutation
-      this.updateTracking(clonedOptions)
+      // Sync return - update tracking with the original predicate
+      this.updateTracking(trackingOptions)
       return true
     } else {
       // Async return - track the promise and update tracking after it resolves
@@ -158,16 +159,14 @@ export class DeduplicatedLoadSubset {
 
       // We need to create a reference to the in-flight entry so we can remove it later
       const inflightEntry = {
-        options: clonedOptions, // Store cloned options for subset matching
+        options: loadOptions, // Store load options for subset matching of in-flight requests
         promise: resultPromise
           .then((result) => {
             // Only update tracking if this request is still from the current generation
             // If reset() was called, the generation will have incremented and we should
             // not repopulate the state that was just cleared
             if (capturedGeneration === this.generation) {
-              // Use the cloned options that we captured before any caller mutations
-              // This ensures we track exactly what was loaded, not what the caller changed
-              this.updateTracking(clonedOptions)
+              this.updateTracking(trackingOptions)
             }
             return result
           })