feat: support concat(toArray(...)) scalar includes (#1384)

* feat: support concat over scalar toArray includes

Add scalar child select materialization for toArray() and concat(toArray()) so includes can produce scalar arrays and concatenated strings without widening the supported root query surface.

Made-with: Cursor

* fix(db): tighten scalar select boundaries

Reject unsupported top-level scalar selects at root consumers while preserving scalar subquery composability and limiting direct ref returns to alias-level spread semantics.

Made-with: Cursor

---------

Co-authored-by: Sam Willis <sam.willis@gmail.com>

Author: KyleAMathews

packages/db/src/errors.ts

@@ -444,6 +444,15 @@ export class FnSelectWithGroupByError extends QueryCompilationError {
   }
 }
 
+export class UnsupportedRootScalarSelectError extends QueryCompilationError {
+  constructor() {
+    super(
+      `Top-level scalar select() is not supported by createLiveQueryCollection() or queryOnce(). ` +
+        `Return an object from .select(), or use the scalar query inside toArray(...) or concat(toArray(...)).`,
+    )
+  }
+}
+
 export class HavingRequiresGroupByError extends QueryCompilationError {
   constructor() {
     super(`HAVING clause requires GROUP BY clause`)

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

@@ -2,7 +2,12 @@ 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 { Context, GetResult, RefLeaf } from './types.js'
+import type {
+  Context,
+  GetRawResult,
+  RefLeaf,
+  StringifiableScalar,
+} from './types.js'
 import type { QueryBuilder } from './index.js'
 
 type StringRef =
@@ -38,8 +43,20 @@ type ComparisonOperandPrimitive<T extends string | number | boolean> =
   | undefined
   | null
 
-// Helper type for any expression-like value
-type ExpressionLike = BasicExpression | RefProxy<any> | RefLeaf<any> | any
+// Helper type for values that can be lowered to expressions.
+type ExpressionLike =
+  | Aggregate
+  | BasicExpression
+  | RefProxy<any>
+  | RefLeaf<any>
+  | string
+  | number
+  | boolean
+  | bigint
+  | Date
+  | null
+  | undefined
+  | Array<unknown>
 
 // Helper type to extract the underlying type from various expression types
 type ExtractType<T> =
@@ -277,9 +294,26 @@ export function length<T extends ExpressionLike>(
   return new Func(`length`, [toExpression(arg)]) as NumericFunctionReturnType<T>
 }
 
+export function concat<T extends StringifiableScalar>(
+  arg: ToArrayWrapper<T>,
+): ConcatToArrayWrapper<T>
+export function concat(...args: Array<ExpressionLike>): BasicExpression<string>
 export function concat(
-  ...args: Array<ExpressionLike>
-): BasicExpression<string> {
+  ...args: Array<ExpressionLike | ToArrayWrapper<any>>
+): BasicExpression<string> | ConcatToArrayWrapper<any> {
+  const toArrayArg = args.find(
+    (arg): arg is ToArrayWrapper<any> => arg instanceof ToArrayWrapper,
+  )
+
+  if (toArrayArg) {
+    if (args.length !== 1) {
+      throw new Error(
+        `concat(toArray(...)) currently supports only a single toArray(...) argument`,
+      )
+    }
+    return new ConcatToArrayWrapper(toArrayArg.query)
+  }
+
   return new Func(
     `concat`,
     args.map((arg) => toExpression(arg)),
@@ -402,13 +436,20 @@ export const operators = [
 
 export type OperatorName = (typeof operators)[number]
 
-export class ToArrayWrapper<T = any> {
-  declare readonly _type: T
+export class ToArrayWrapper<_T = unknown> {
+  declare readonly _type: `toArray`
+  declare readonly _result: _T
+  constructor(public readonly query: QueryBuilder<any>) {}
+}
+
+export class ConcatToArrayWrapper<_T = unknown> {
+  declare readonly _type: `concatToArray`
+  declare readonly _result: _T
   constructor(public readonly query: QueryBuilder<any>) {}
 }
 
 export function toArray<TContext extends Context>(
   query: QueryBuilder<TContext>,
-): ToArrayWrapper<GetResult<TContext>> {
+): ToArrayWrapper<GetRawResult<TContext>> {
   return new ToArrayWrapper(query)
 }

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

@@ -3,6 +3,7 @@ import {
   Aggregate as AggregateExpr,
   CollectionRef,
   Func as FuncExpr,
+  INCLUDES_SCALAR_FIELD,
   IncludesSubquery,
   PropRef,
   QueryRef,
@@ -24,11 +25,12 @@ import {
   isRefProxy,
   toExpression,
 } from './ref-proxy.js'
-import { ToArrayWrapper } from './functions.js'
+import { ConcatToArrayWrapper, ToArrayWrapper } from './functions.js'
 import type { NamespacedRow, SingleResult } from '../../types.js'
 import type {
   Aggregate,
   BasicExpression,
+  IncludesMaterialization,
   JoinClause,
   OrderBy,
   OrderByDirection,
@@ -44,10 +46,13 @@ import type {
   JoinOnCallback,
   MergeContextForJoinCallback,
   MergeContextWithJoinType,
+  NonScalarSelectObject,
   OrderByCallback,
   OrderByOptions,
   RefsForContext,
   ResultTypeFromSelect,
+  ResultTypeFromSelectValue,
+  ScalarSelectValue,
   SchemaFromSource,
   SelectObject,
   Source,
@@ -489,11 +494,29 @@ export class BaseQueryBuilder<TContext extends Context = Context> {
    * ```
    */
   select<TSelectObject extends SelectObject>(
-    callback: (refs: RefsForContext<TContext>) => TSelectObject,
-  ): QueryBuilder<WithResult<TContext, ResultTypeFromSelect<TSelectObject>>> {
+    callback: (
+      refs: RefsForContext<TContext>,
+    ) => NonScalarSelectObject<TSelectObject>,
+  ): QueryBuilder<WithResult<TContext, ResultTypeFromSelect<TSelectObject>>>
+  select<TSelectValue extends ScalarSelectValue>(
+    callback: (refs: RefsForContext<TContext>) => TSelectValue,
+  ): QueryBuilder<WithResult<TContext, ResultTypeFromSelectValue<TSelectValue>>>
+  select(
+    callback: (
+      refs: RefsForContext<TContext>,
+    ) => SelectObject | ScalarSelectValue,
+  ) {
     const aliases = this._getCurrentAliases()
     const refProxy = createRefProxy(aliases) as RefsForContext<TContext>
-    const selectObject = callback(refProxy)
+    let selectObject = callback(refProxy)
+
+    // Returning a top-level alias directly is equivalent to spreading it.
+    // Leaf refs like `row.name` must remain scalar selections.
+    if (isRefProxy(selectObject) && selectObject.__path.length === 1) {
+      const sentinelKey = `__SPREAD_SENTINEL__${selectObject.__path[0]}__0`
+      selectObject = { [sentinelKey]: true }
+    }
+
     const select = buildNestedSelect(selectObject, aliases)
 
     return new BaseQueryBuilder({
@@ -679,7 +702,7 @@ export class BaseQueryBuilder<TContext extends Context = Context> {
    * // Get countries our users are from
    * query
    *   .from({ users: usersCollection })
-   *   .select(({users}) => users.country)
+   *   .select(({users}) => ({ country: users.country }))
    *   .distinct()
    * ```
    */
@@ -709,7 +732,7 @@ export class BaseQueryBuilder<TContext extends Context = Context> {
       // TODO: enforcing return only one result with also a default orderBy if none is specified
       // limit: 1,
       singleResult: true,
-    })
+    }) as any
   }
 
   // Helper methods
@@ -772,7 +795,7 @@ export class BaseQueryBuilder<TContext extends Context = Context> {
           ...builder.query,
           select: undefined, // remove the select clause if it exists
           fnSelect: callback,
-        })
+        }) as any
       },
       /**
        * Filter rows using a function that operates on each row
@@ -880,14 +903,21 @@ function buildNestedSelect(obj: any, parentAliases: Array<string> = []): any {
       continue
     }
     if (v instanceof BaseQueryBuilder) {
-      out[k] = buildIncludesSubquery(v, k, parentAliases, false)
+      out[k] = buildIncludesSubquery(v, k, parentAliases, `collection`)
       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)
+      out[k] = buildIncludesSubquery(v.query, k, parentAliases, `array`)
+      continue
+    }
+    if (v instanceof ConcatToArrayWrapper) {
+      if (!(v.query instanceof BaseQueryBuilder)) {
+        throw new Error(`concat(toArray(...)) must wrap a subquery builder`)
+      }
+      out[k] = buildIncludesSubquery(v.query, k, parentAliases, `concat`)
       continue
     }
     out[k] = buildNestedSelect(v, parentAliases)
@@ -937,7 +967,7 @@ function buildIncludesSubquery(
   childBuilder: BaseQueryBuilder,
   fieldName: string,
   parentAliases: Array<string>,
-  materializeAsArray: boolean,
+  materialization: IncludesMaterialization,
 ): IncludesSubquery {
   const childQuery = childBuilder._getQuery()
 
@@ -1093,14 +1123,45 @@ function buildIncludesSubquery(
     where: pureChildWhere.length > 0 ? pureChildWhere : undefined,
   }
 
+  const rawChildSelect = modifiedQuery.select as any
+  const hasObjectSelect =
+    rawChildSelect === undefined || isPlainObject(rawChildSelect)
+  let includesQuery = modifiedQuery
+  let scalarField: string | undefined
+
+  if (materialization === `concat`) {
+    if (rawChildSelect === undefined || hasObjectSelect) {
+      throw new Error(
+        `concat(toArray(...)) for "${fieldName}" requires the subquery to select a scalar value`,
+      )
+    }
+  }
+
+  if (!hasObjectSelect) {
+    if (materialization === `collection`) {
+      throw new Error(
+        `Includes subquery for "${fieldName}" must select an object when materializing as a Collection`,
+      )
+    }
+
+    scalarField = INCLUDES_SCALAR_FIELD
+    includesQuery = {
+      ...modifiedQuery,
+      select: {
+        [scalarField]: rawChildSelect,
+      },
+    }
+  }
+
   return new IncludesSubquery(
-    modifiedQuery,
+    includesQuery,
     parentRef,
     childRef,
     fieldName,
     parentFilters.length > 0 ? parentFilters : undefined,
     parentProjection,
-    materializeAsArray,
+    materialization,
+    scalarField,
   )
 }