Add support for distinguishing explicit and implicit null in ArgBuilders

core/src/main/scala-2/caliban/schema/ArgBuilderDerivation.scala

@@ -31,7 +31,7 @@ trait ArgBuilderDerivation {
         input match {
           case InputValue.ObjectValue(fields) =>
             val label = p.annotations.collectFirst { case GQLName(name) => name }.getOrElse(p.label)
-            p.typeclass.build(fields.getOrElse(label, NullValue))
+            fields.get(label).fold(p.typeclass.buildMissing)(p.typeclass.build)
           case value                          => p.typeclass.build(value)
         }
       }

core/src/main/scala-3/caliban/schema/ArgBuilderDerivation.scala

@@ -51,14 +51,12 @@ trait ArgBuilderDerivation {
         new ArgBuilder[A] {
           def build(input: InputValue): Either[ExecutionError, A] = {
             fields.map { (label, _, builder) =>
-              val newInput =
-                input match {
-                  case InputValue.ObjectValue(fields) =>
-                    val finalLabel = annotations.getOrElse(label, Nil).collectFirst { case GQLName(name) => name }.getOrElse(label)
-                    fields.getOrElse(finalLabel, NullValue)
-                  case value => value
-                }
-              builder.build(newInput)
+              input match {
+                case InputValue.ObjectValue(fields) =>
+                  val finalLabel = annotations.getOrElse(label, Nil).collectFirst { case GQLName(name) => name }.getOrElse(label)
+                  fields.get(finalLabel).fold(builder.buildMissing)(builder.build)
+                case value => builder.build(value)
+              }
             }.foldRight[Either[ExecutionError, Tuple]](Right(EmptyTuple)) { case (item, acc) =>
               item match {
                 case error: Left[ExecutionError, Any] => error.asInstanceOf[Left[ExecutionError, Tuple]]

core/src/main/scala/caliban/schema/ArgBuilder.scala

@@ -33,6 +33,13 @@ trait ArgBuilder[T] { self =>
    */
   def build(input: InputValue): Either[ExecutionError, T]
 
+  /**
+   * Builds a value of type `T` from a missing input value.
+   * By default, this delegates to [[build]], passing it NullValue.
+   * Fails with an [[caliban.CalibanError.ExecutionError]] if it was impossible to build the value.
+   */
+  def buildMissing: Either[ExecutionError, T] = build(NullValue)
+
   /**
    * Builds a new `ArgBuilder` of `A` from an existing `ArgBuilder` of `T` and a function from `T` to `A`.
    * @param f a function from `T` to `A`.

core/src/test/scala-2/caliban/Scala2SpecificSpec.scala

@@ -1,8 +1,12 @@
 package caliban
 
+import caliban.CalibanError.ExecutionError
 import caliban.GraphQL._
+import caliban.InputValue.ObjectValue
 import caliban.TestUtils._
+import caliban.Value.{ NullValue, StringValue }
 import caliban.introspection.adt.__DeprecatedArgs
+import caliban.schema.ArgBuilder
 import caliban.schema.SchemaSpec.introspect
 import zio.test.Assertion._
 import zio.test._
@@ -39,6 +43,30 @@ object Scala2SpecificSpec extends DefaultRunnableSpec {
             """{"events":[{"organizationId":7,"title":"Frida Kahlo exhibition"}],"painters":[{"name":"Claude Monet","movement":"Impressionism"}]}"""
           )
         )
+      },
+      test("Scala 2 buildMissing") {
+        sealed abstract class Nullable[+T]
+        case class SomeNullable[+T](t: T) extends Nullable[T]
+        case object NullNullable          extends Nullable[Nothing]
+        case object MissingNullable       extends Nullable[Nothing]
+
+        implicit def nullableArgBuilder[A](implicit ev: ArgBuilder[A]): ArgBuilder[Nullable[A]] =
+          new ArgBuilder[Nullable[A]] {
+            def build(input: InputValue): Either[ExecutionError, Nullable[A]] = input match {
+              case NullValue => Right(NullNullable)
+              case _         => ev.build(input).map(SomeNullable(_))
+            }
+
+            override def buildMissing: Either[ExecutionError, Nullable[A]] = Right(MissingNullable)
+          }
+
+        case class Wrapper(a: Nullable[String])
+
+        val deriviedAB = implicitly[ArgBuilder[Wrapper]]
+
+        assert(deriviedAB.build(ObjectValue(Map())))(equalTo(Right(Wrapper(MissingNullable)))) &&
+        assert(deriviedAB.build(ObjectValue(Map("a" -> NullValue))))(equalTo(Right(Wrapper(NullNullable)))) &&
+        assert(deriviedAB.build(ObjectValue(Map("a" -> StringValue("x")))))(equalTo(Right(Wrapper(SomeNullable("x")))))
       }
     )
 }

core/src/test/scala-3/caliban/Scala3SpecificSpec.scala

@@ -1,7 +1,11 @@
 package caliban
 
+import caliban.CalibanError.ExecutionError
 import caliban.GraphQL._
+import caliban.InputValue.ObjectValue
+import caliban.Value.{ NullValue, StringValue }
 import caliban.schema.Annotations.GQLInterface
+import caliban.schema.ArgBuilder
 import zio.test.Assertion._
 import zio.test._
 import zio.test.environment.TestEnvironment
@@ -69,6 +73,30 @@ object Scala3SpecificSpec extends DefaultRunnableSpec {
         assertM(interpreter.flatMap(_.execute(query)).map(_.data.toString))(
           equalTo("""{"item":{"a":1}}""")
         )
+      },
+      test("Scala 3 buildMissing") {
+        sealed abstract class Nullable[+T]
+        case class SomeNullable[+T](t: T) extends Nullable[T]
+        case object NullNullable          extends Nullable[Nothing]
+        case object MissingNullable       extends Nullable[Nothing]
+
+        implicit def nullableArgBuilder[A](implicit ev: ArgBuilder[A]): ArgBuilder[Nullable[A]] =
+          new ArgBuilder[Nullable[A]] {
+            def build(input: InputValue): Either[ExecutionError, Nullable[A]] = input match {
+              case NullValue => Right(NullNullable)
+              case _         => ev.build(input).map(SomeNullable(_))
+            }
+
+            override def buildMissing: Either[ExecutionError, Nullable[A]] = Right(MissingNullable)
+          }
+
+        case class Wrapper(a: Nullable[String])
+
+        val deriviedAB = implicitly[ArgBuilder[Wrapper]]
+
+        assert(deriviedAB.build(ObjectValue(Map())))(equalTo(Right(Wrapper(MissingNullable)))) &&
+        assert(deriviedAB.build(ObjectValue(Map("a" -> NullValue))))(equalTo(Right(Wrapper(NullNullable)))) &&
+        assert(deriviedAB.build(ObjectValue(Map("a" -> StringValue("x")))))(equalTo(Right(Wrapper(SomeNullable("x")))))
       }
     )
 }