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

The previous implementation used NonNullable<ExtractType<T>> on just the
first arg, stripping null from the return type unconditionally. This was
unsound because the runtime evaluator returns null when all args are null.

New behavior:
- Strip null only when at least one arg is statically guaranteed non-null
  (does not include null | undefined in its type)
- Keep null in the result type when all args could be null/undefined

Examples:
  coalesce(user.name, 'Unknown')     → BasicExpression<string>   (non-null literal fallback)
  coalesce(user.department_id)       → BasicExpression<number | null>  (nullable only)
  coalesce(user.department_id, 0)    → BasicExpression<number>   (0 is guaranteed non-null)
  coalesce(user.department_id, dept?.id) → BasicExpression<number | null>  (dept?.id can be undefined)

Added type tests for the nullable-only and guaranteed-non-null cases.

Addresses review feedback from samwillis.

Author: sleitor

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

@@ -285,14 +285,37 @@ export function concat(
   )
 }
 
-export function coalesce<T extends ExpressionLike>(
-  first: T,
-  ...rest: Array<ExpressionLike>
-): BasicExpression<NonNullable<ExtractType<T>>> {
+// 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]>
+    ? undefined extends ExtractType<T[K]>
+      ? false
+      : 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`,
-    [first, ...rest].map((arg) => toExpression(arg)),
-  ) as BasicExpression<NonNullable<ExtractType<T>>>
+    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

@@ -152,6 +152,18 @@ describe(`Query Builder Callback Types`, () => {
         expectTypeOf(coalesce(user.name, `Unknown`)).toEqualTypeOf<
           BasicExpression<string>
         >()
+        // nullable-only args: null retained in result
+        expectTypeOf(coalesce(user.department_id)).toEqualTypeOf<
+          BasicExpression<number | null>
+        >()
+        // nullable args only: null retained (dept?.id can be undefined)
+        expectTypeOf(
+          coalesce(user.department_id, user.department_id),
+        ).toEqualTypeOf<BasicExpression<number | null>>()
+        // guaranteed non-null fallback: null stripped
+        expectTypeOf(coalesce(user.department_id, 0)).toEqualTypeOf<
+          BasicExpression<number>
+        >()
 
         return {
           upper_name: upper(user.name),