Add generateInputBuilders (#5146)

* add generateInputBuilders

* update doc

Author: martinbonnin

docs/source/advanced/plugin-configuration.mdx

@@ -295,6 +295,9 @@ apollo {
     generateModelBuilders.set(true)
     // Whether to generate fields as primitive types (`int`, `double`, `boolean`) instead of their boxed types (`Integer`, `Double`, etc..)
     generatePrimitiveTypes.set(true)
+    // Opt-in Builders for Operations, Fragments and Input types. Builders are more ergonomic than default arguments when there are a lot of
+    // optional arguments.
+    generateInputBuilders.set(true)
     // The style to use for fields that are nullable in the Java generated code
     nullableFieldStyle.set("apolloOptional")
     // Whether to decapitalize field names in the generated models (for instance `FooBar` -> `fooBar`)

libraries/apollo-compiler/api/apollo-compiler.api

@@ -127,8 +127,8 @@ public final class com/apollographql/apollo3/compiler/JavaNullable$Companion {
 }
 
 public final class com/apollographql/apollo3/compiler/KotlinCodegenOptions {
-	public fun <init> (Lcom/apollographql/apollo3/compiler/TargetLanguage;Ljava/util/List;ZZLcom/apollographql/apollo3/compiler/hooks/ApolloCompilerKotlinHooks;ZLjava/lang/String;Z)V
-	public synthetic fun <init> (Lcom/apollographql/apollo3/compiler/TargetLanguage;Ljava/util/List;ZZLcom/apollographql/apollo3/compiler/hooks/ApolloCompilerKotlinHooks;ZLjava/lang/String;ZILkotlin/jvm/internal/DefaultConstructorMarker;)V
+	public fun <init> (Lcom/apollographql/apollo3/compiler/TargetLanguage;Ljava/util/List;ZZLcom/apollographql/apollo3/compiler/hooks/ApolloCompilerKotlinHooks;ZLjava/lang/String;ZZ)V
+	public synthetic fun <init> (Lcom/apollographql/apollo3/compiler/TargetLanguage;Ljava/util/List;ZZLcom/apollographql/apollo3/compiler/hooks/ApolloCompilerKotlinHooks;ZLjava/lang/String;ZZILkotlin/jvm/internal/DefaultConstructorMarker;)V
 	public final fun getAddJvmOverloads ()Z
 	public final fun getGenerateAsInternal ()Z
 	public final fun getGenerateFilterNotNull ()Z
@@ -185,6 +185,7 @@ public final class com/apollographql/apollo3/compiler/OptionsKt {
 	public static final field defaultGenerateDataBuilders Z
 	public static final field defaultGenerateFilterNotNull Z
 	public static final field defaultGenerateFragmentImplementations Z
+	public static final field defaultGenerateInputBuilders Z
 	public static final field defaultGenerateModelBuilders Z
 	public static final field defaultGenerateOptionalOperationVariables Z
 	public static final field defaultGeneratePrimitiveTypes Z

libraries/apollo-compiler/src/main/kotlin/com/apollographql/apollo3/compiler/ApolloCompiler.kt

@@ -394,6 +394,7 @@ object ApolloCompiler {
       addJvmOverloads: Boolean = defaultAddJvmOverloads,
       requiresOptInAnnotation: String = defaultRequiresOptInAnnotation,
       compilerKotlinHooks: ApolloCompilerKotlinHooks = defaultCompilerKotlinHooks,
+      generateInputBuilders: Boolean = false
   ): CodegenMetadata {
     /**
      * Inject all built-in scalars
@@ -484,7 +485,8 @@ object ApolloCompiler {
             addJvmOverloads = addJvmOverloads,
             requiresOptInAnnotation = requiresOptInAnnotation,
             compilerKotlinHooks = compilerKotlinHooks,
-            languageVersion = targetLanguage
+            languageVersion = targetLanguage,
+            generateInputBuilders = generateInputBuilders
         )
         writeKotlin(
             commonCodegenOptions = commonCodegenOptions,

libraries/apollo-compiler/src/main/kotlin/com/apollographql/apollo3/compiler/Options.kt

@@ -247,6 +247,7 @@ class KotlinCodegenOptions(
      */
     val addJvmOverloads: Boolean = false,
     val requiresOptInAnnotation: String?,
+
     /**
      * Whether to add the [JsExport] annotation to generated models. This is useful to be able to cast JSON parsed
      * responses into Kotlin classes using [unsafeCast].
@@ -255,6 +256,16 @@ class KotlinCodegenOptions(
      */
     @ApolloExperimental
     val jsExport: Boolean = false,
+
+    /**
+     * Whether to generate builders in addition to constructors for operations and input types.
+     * Constructors are more concise but require passing an instance of `Optional` always, making them more verbose
+     * for the cases where there are a lot of optional input parameters.
+     *
+     * Default: false
+     */
+    @ApolloExperimental
+    val generateInputBuilders: Boolean = false
 )
 
 class JavaCodegenOptions(
@@ -369,6 +380,7 @@ const val defaultAddJvmOverloads = false
 const val defaultFieldsOnDisjointTypesMustMerge = true
 const val defaultGeneratePrimitiveTypes = false
 const val defaultJsExport = false
+const val defaultGenerateInputBuilders = false
 val defaultNullableFieldStyle = JavaNullable.NONE
 const val defaultDecapitalizeFields = false
 val defaultCompilerKotlinHooks = ApolloCompilerKotlinHooks.Identity

libraries/apollo-compiler/src/main/kotlin/com/apollographql/apollo3/compiler/codegen/kotlin/KotlinCodeGen.kt

@@ -72,6 +72,7 @@ internal object KotlinCodeGen {
     val hooks = kotlinCodegenOptions.compilerKotlinHooks
     val generateSchema = commonCodegenOptions.generateSchema || generateDataBuilders
     val outputDir = commonCodegenOptions.outputDir
+    val generateInputBuilders = kotlinCodegenOptions.generateInputBuilders
 
     val upstreamResolver = resolverInfos.fold(null as KotlinResolver?) { acc, resolverInfo ->
       KotlinResolver(resolverInfo.entries, acc, scalarMapping, requiresOptInAnnotation, hooks)
@@ -108,7 +109,7 @@ internal object KotlinCodeGen {
         builders.add(EnumResponseAdapterBuilder(context, irEnum))
       }
       irSchema.irInputObjects.forEach { irInputObject ->
-        builders.add(InputObjectBuilder(context, irInputObject))
+        builders.add(InputObjectBuilder(context, irInputObject, generateInputBuilders))
         builders.add(InputObjectAdapterBuilder(context, irInputObject))
       }
       irSchema.irUnions.forEach {irUnion ->
@@ -156,7 +157,8 @@ internal object KotlinCodeGen {
                     fragment,
                     flatten,
                     addJvmOverloads,
-                    generateDataBuilders
+                    generateDataBuilders,
+                    generateInputBuilders,
                 )
             )
             if (fragment.variables.isNotEmpty()) {
@@ -184,6 +186,7 @@ internal object KotlinCodeGen {
                   flatten,
                   addJvmOverloads,
                   generateDataBuilders,
+                  generateInputBuilders
               )
           )
         }

libraries/apollo-compiler/src/main/kotlin/com/apollographql/apollo3/compiler/codegen/kotlin/KotlinSymbols.kt

@@ -61,6 +61,7 @@ internal object KotlinSymbols {
   val MapBuilder = ClassNames.MapBuilder.toKotlinPoetClassName()
   val StubbedProperty = ClassNames.StubbedProperty.toKotlinPoetClassName()
   val MandatoryTypenameProperty = ClassNames.MandatoryTypenameProperty.toKotlinPoetClassName()
+  val Builder = ClassName("", "Builder")
 
   /**
    * Kotlin class names

libraries/apollo-compiler/src/main/kotlin/com/apollographql/apollo3/compiler/codegen/kotlin/file/FragmentBuilder.kt

@@ -26,6 +26,7 @@ internal class FragmentBuilder(
     flatten: Boolean,
     private val addJvmOverloads: Boolean,
     private val generateDataBuilders: Boolean,
+    private val generateInputBuilders: Boolean,
 ) : CgFileBuilder {
   private val layout = context.layout
   private val packageName = layout.fragmentPackageName(fragment.filePath)
@@ -67,16 +68,23 @@ internal class FragmentBuilder(
   }
 
   private fun IrFragmentDefinition.typeSpec(): TypeSpec {
+    val namedTypes = variables.map { it.toNamedType() }
+
     return TypeSpec.classBuilder(simpleName)
         .addSuperinterface(superInterfaceType())
         .maybeAddDescription(description)
-        .makeDataClass(variables.map { it.toNamedType().toParameterSpec(context) }, addJvmOverloads)
+        .makeDataClass(namedTypes.map { it.toParameterSpec(context) }, addJvmOverloads)
         .addFunction(serializeVariablesFunSpec())
         .addFunction(adapterFunSpec(context, dataProperty))
         .addFunction(rootFieldFunSpec())
         // Fragments can have multiple data shapes
         .addTypes(dataTypeSpecs())
         .maybeAddJsExport(context)
+        .apply {
+          if (namedTypes.isNotEmpty() && generateInputBuilders) {
+            addType(namedTypes.builderTypeSpec(context, ClassName(packageName, simpleName)))
+          }
+        }
         .applyIf(generateDataBuilders) {
           addType(
               TypeSpec.companionObjectBuilder()

libraries/apollo-compiler/src/main/kotlin/com/apollographql/apollo3/compiler/codegen/kotlin/file/InputObjectBuilder.kt

@@ -1,22 +1,33 @@
 package com.apollographql.apollo3.compiler.codegen.kotlin.file
 
+import com.apollographql.apollo3.compiler.codegen.Identifier
+import com.apollographql.apollo3.compiler.codegen.Identifier.Builder
 import com.apollographql.apollo3.compiler.codegen.kotlin.CgFile
 import com.apollographql.apollo3.compiler.codegen.kotlin.CgFileBuilder
 import com.apollographql.apollo3.compiler.codegen.kotlin.KotlinContext
+import com.apollographql.apollo3.compiler.codegen.kotlin.helpers.NamedType
 import com.apollographql.apollo3.compiler.codegen.kotlin.helpers.makeDataClass
 import com.apollographql.apollo3.compiler.codegen.kotlin.helpers.maybeAddDescription
 import com.apollographql.apollo3.compiler.codegen.kotlin.helpers.toNamedType
 import com.apollographql.apollo3.compiler.codegen.kotlin.helpers.toParameterSpec
+import com.apollographql.apollo3.compiler.codegen.kotlin.helpers.toPropertySpec
+import com.apollographql.apollo3.compiler.codegen.kotlin.helpers.toSetterFunSpec
 import com.apollographql.apollo3.compiler.ir.IrInputObject
+import com.apollographql.apollo3.compiler.ir.IrNonNullType
+import com.apollographql.apollo3.compiler.ir.IrOptionalType
 import com.squareup.kotlinpoet.ClassName
+import com.squareup.kotlinpoet.CodeBlock
+import com.squareup.kotlinpoet.FunSpec
 import com.squareup.kotlinpoet.TypeSpec
 
 internal class InputObjectBuilder(
     val context: KotlinContext,
     val inputObject: IrInputObject,
+    val generateInputBuilders: Boolean,
 ) : CgFileBuilder {
   private val packageName = context.layout.typePackageName()
   private val simpleName = context.layout.inputObjectName(inputObject.name)
+  private val className = ClassName(packageName, simpleName)
 
   override fun build(): CgFile {
     return CgFile(
@@ -29,16 +40,60 @@ internal class InputObjectBuilder(
   override fun prepare() {
     context.resolver.registerSchemaType(
         inputObject.name,
-        ClassName(packageName, simpleName)
+        className
     )
   }
 
-  private fun IrInputObject.typeSpec() =
-      TypeSpec
-          .classBuilder(simpleName)
-          .maybeAddDescription(description)
-          .makeDataClass(fields.map {
-            it.toNamedType().toParameterSpec(context)
-          })
-          .build()
+  private fun IrInputObject.typeSpec(): TypeSpec {
+    val namedTypes = fields.map {
+      it.toNamedType()
+    }
+    return TypeSpec
+        .classBuilder(simpleName)
+        .maybeAddDescription(description)
+        .makeDataClass(namedTypes.map { it.toParameterSpec(context) })
+        .apply {
+          if (namedTypes.isNotEmpty() && generateInputBuilders) {
+            addType(namedTypes.builderTypeSpec(context, className))
+          }
+        }
+        .build()
+  }
 }
+
+
+internal fun List<NamedType>.builderTypeSpec(context: KotlinContext, returnedClassName: ClassName): TypeSpec {
+  return TypeSpec.classBuilder(Builder)
+      .apply {
+        forEach {
+          addProperty(it.toPropertySpec(context))
+          addFunction(it.toSetterFunSpec(context))
+        }
+      }
+      .addFunction(toBuildFunSpec(context, returnedClassName))
+      .build()
+}
+
+private fun List<NamedType>.toBuildFunSpec(context: KotlinContext, returnedClassName: ClassName): FunSpec {
+  return FunSpec.builder(Identifier.build)
+      .returns(returnedClassName)
+      .addCode(
+          CodeBlock.builder()
+              .add("return·%T(\n", returnedClassName)
+              .indent()
+              .apply {
+                forEach {
+                  val propertyName = context.layout.propertyName(it.graphQlName)
+                  add("%L·=·%L", propertyName, propertyName)
+                  if (it.type is IrNonNullType && it.type.ofType !is IrOptionalType) {
+                    add("·?:·error(\"missing·value·for·$propertyName\")")
+                  }
+                  add(",\n")
+                }
+              }
+              .unindent()
+              .add(")")
+              .build()
+      )
+      .build()
+}

libraries/apollo-compiler/src/main/kotlin/com/apollographql/apollo3/compiler/codegen/kotlin/file/OperationBuilder.kt

@@ -40,6 +40,7 @@ internal class OperationBuilder(
     flatten: Boolean,
     private val addJvmOverloads: Boolean,
     val generateDataBuilders: Boolean,
+    val generateInputBuilders: Boolean
 ) : CgFileBuilder {
   private val layout = context.layout
   private val packageName = layout.operationPackageName(operation.filePath)
@@ -90,11 +91,17 @@ internal class OperationBuilder(
   }
 
   fun typeSpec(): TypeSpec {
+    val namedTypes = operation.variables.map { it.toNamedType() }
     return TypeSpec.classBuilder(layout.operationName(operation))
         .addSuperinterface(superInterfaceType())
         .maybeAddDescription(operation.description)
-        .makeDataClass(operation.variables.map { it.toNamedType().toParameterSpec(context) }, addJvmOverloads)
+        .makeDataClass(namedTypes.map { it.toParameterSpec(context) }, addJvmOverloads)
         .maybeAddJsExport(context)
+        .apply {
+          if (namedTypes.isNotEmpty() && generateInputBuilders) {
+            addType(namedTypes.builderTypeSpec(context, ClassName(packageName, simpleName)))
+          }
+        }
         .addFunction(operationIdFunSpec())
         .addFunction(queryDocumentFunSpec(generateQueryDocument))
         .addFunction(nameFunSpec())

libraries/apollo-compiler/src/main/kotlin/com/apollographql/apollo3/compiler/codegen/kotlin/helpers/KDoc.kt

@@ -36,6 +36,14 @@ internal fun ParameterSpec.Builder.maybeAddDescription(description: String?): Pa
   return addKdoc("%L", description)
 }
 
+internal fun FunSpec.Builder.maybeAddDescription(description: String?): FunSpec.Builder {
+  if (description.isNullOrBlank()) {
+    return this
+  }
+
+  return addKdoc("%L", description)
+}
+
 
 internal fun TypeSpec.Builder.maybeAddDeprecation(deprecationReason: String?): TypeSpec.Builder {
   if (deprecationReason.isNullOrBlank()) {
@@ -61,6 +69,14 @@ internal fun ParameterSpec.Builder.maybeAddDeprecation(deprecationReason: String
   return addAnnotation(deprecatedAnnotation(deprecationReason))
 }
 
+internal fun FunSpec.Builder.maybeAddDeprecation(deprecationReason: String?): FunSpec.Builder {
+  if (deprecationReason.isNullOrBlank()) {
+    return this
+  }
+
+  return addAnnotation(deprecatedAnnotation(deprecationReason))
+}
+
 internal fun TypeSpec.Builder.maybeAddRequiresOptIn(resolver: KotlinResolver, optInFeature: String?): TypeSpec.Builder {
   if (optInFeature.isNullOrBlank()) {
     return this
@@ -88,6 +104,15 @@ internal fun ParameterSpec.Builder.maybeAddRequiresOptIn(resolver: KotlinResolve
   return addAnnotation(AnnotationSpec.builder(annotation).build())
 }
 
+internal fun FunSpec.Builder.maybeAddRequiresOptIn(resolver: KotlinResolver, optInFeature: String?): FunSpec.Builder {
+  if (optInFeature.isNullOrBlank()) {
+    return this
+  }
+
+  val annotation = resolver.resolveRequiresOptInAnnotation() ?: return this
+  return addAnnotation(AnnotationSpec.builder(annotation).build())
+}
+
 internal val suppressDeprecationAnnotationSpec = AnnotationSpec.builder(KotlinSymbols.Suppress)
     .addMember("%S", "DEPRECATION")
     .build()