fix(db): infer non-nullable return type from first arg in coalesce() (#1342)

* fix(db): infer type in coalesce() instead of returning BasicExpression<any>

Previously coalesce() always returned BasicExpression<any>, losing type
information. Now it uses a generic to infer the non-nullable union of all
argument types, matching the semantic of SQL COALESCE.

Fixes #1341

* fix(db): preserve null in coalesce() when no guaranteed non-null arg

- Use HasGuaranteedNonNull<T> helper to track whether any arg statically
  cannot be null/undefined
- Return CoalesceArgTypes<T> | null unless a non-null arg guarantees it
- Update tests to use spread args (varargs) instead of array
- Update changeset description

Addresses samwillis review feedback and kevin-dp ExpressionLike concerns

* ci: apply automated fixes

---------

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>

Author: sleitor

.changeset/fix-coalesce-type.md

@@ -0,0 +1,7 @@
+---
+'@tanstack/db': patch
+---
+
+fix(db): preserve null in coalesce() return type when no guaranteed non-null arg is present
+
+`coalesce()` was typed as returning `BasicExpression<any>`, losing all type information. The signature now infers types from all arguments via tuple generics, returns the union of non-null arg types, and only removes nullability when at least one argument is statically guaranteed non-null.

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

@@ -286,11 +286,35 @@ export function concat(
   )
 }
 
-export function coalesce(...args: Array<ExpressionLike>): BasicExpression<any> {
+// Helper type for coalesce: extracts non-nullish value types from all args
+type CoalesceArgTypes<T extends Array<ExpressionLike>> = {
+  [K in keyof T]: NonNullable<ExtractType<T[K]>>
+}[number]
+
+// Whether any arg in the tuple is statically guaranteed non-null (i.e., does not include null | undefined)
+type HasGuaranteedNonNull<T extends Array<ExpressionLike>> = {
+  [K in keyof T]: null extends ExtractType<T[K]>
+    ? false
+    : undefined extends ExtractType<T[K]>
+      ? false
+      : true
+}[number] extends false
+  ? false
+  : true
+
+// coalesce() return type: union of all non-null arg types; null included unless a guaranteed non-null arg exists
+type CoalesceReturnType<T extends Array<ExpressionLike>> =
+  HasGuaranteedNonNull<T> extends true
+    ? BasicExpression<CoalesceArgTypes<T>>
+    : BasicExpression<CoalesceArgTypes<T> | null>
+
+export function coalesce<T extends [ExpressionLike, ...Array<ExpressionLike>]>(
+  ...args: T
+): CoalesceReturnType<T> {
   return new Func(
     `coalesce`,
     args.map((arg) => toExpression(arg)),
-  )
+  ) as CoalesceReturnType<T>
 }
 
 export function add<T1 extends ExpressionLike, T2 extends ExpressionLike>(

packages/db/tests/query/builder/callback-types.test-d.ts

@@ -148,7 +148,19 @@ describe(`Query Builder Callback Types`, () => {
           BasicExpression<number>
         >()
         expectTypeOf(coalesce(user.name, `Unknown`)).toEqualTypeOf<
-          BasicExpression<any>
+          BasicExpression<string>
+        >()
+        // nullable-only: coalesce(nullable, nullable) → keeps null in return type
+        expectTypeOf(
+          coalesce(user.department_id, user.department_id),
+        ).toEqualTypeOf<BasicExpression<number | null>>()
+        // nullable + nullable literal null → keeps null
+        expectTypeOf(coalesce(user.department_id, null)).toEqualTypeOf<
+          BasicExpression<number | null>
+        >()
+        // nullable + guaranteed non-null → strips null
+        expectTypeOf(coalesce(user.department_id, 0)).toEqualTypeOf<
+          BasicExpression<number>
         >()
 
         return {

packages/db/tests/query/builder/functions.test.ts

@@ -196,7 +196,7 @@ describe(`QueryBuilder Functions`, () => {
         .from({ employees: employeesCollection })
         .select(({ employees }) => ({
           id: employees.id,
-          name_or_default: coalesce([employees.name, `Unknown`]),
+          name_or_default: coalesce(employees.name, `Unknown`),
         }))
 
       const builtQuery = getQueryIR(query)