Generate connectionTypes and embeddedFields in Cache object. (#230)

* Generate connectionTypes and embeddedFields in Cache object.

* Make TypePolicy and EmbeddedFields inline value classes.

* Doc: remove mention of `paginationArgs` (deprecated) and use `FieldKeyGenerator` instead

* Revert bad .md change

* Formatting

* Fix test

* Fix tests

* Update Changelog

Author: BoD

CHANGELOG.md

@@ -2,6 +2,11 @@
 
 PUT_CHANGELOG_HERE
 
+- Pagination API tweaks (#230)
+  - Configuring connection fields with `@typePolicy(connectionFields: "...")` is deprecated. Instead, apply `@connection` to the connection types.
+  - Configuring pagination arguments with `@fieldPolicy(forField: "...", paginationArgs: "...")` is deprecated. Instead, configure a `FieldKeyGenerator` on your cache.
+  - The API of `EmbeddedFieldsProvider` has been tweaked to allow determining if fields should be embedded field by field, rather than all at once based on the type.
+
 # v1.0.0-alpha.6
 _2025-08-21_
 

Writerside/topics/expiration.md

@@ -89,7 +89,7 @@ To declare the maximum age of types and fields in the schema, use the `@cacheCon
 ```
 # First import the directives
 extend schema @link(
-  url: "https://specs.apollo.dev/cache/v0.1",
+  url: "https://specs.apollo.dev/cache/v0.3",
   import: ["@cacheControl", "@cacheControlField"]
 )
 
@@ -113,5 +113,5 @@ cacheResolver = CacheControlCacheResolver(
     maxAges = Cache.maxAges,
     defaultMaxAge = 1.hours,
   )
-),
+)
 ```

Writerside/topics/pagination/pagination-other.md

@@ -5,17 +5,36 @@ with more configuration needed.
 
 #### Pagination arguments
 
-The `@fieldPolicy` directive has a `paginationArgs` argument that can be used to specify the arguments that should be omitted from the field key.
+Arguments that should be omitted from the field key can be specified programmatically by configuring your cache with a [`FieldKeyGenerator`](https://apollographql.github.io/apollo-kotlin-normalized-cache/kdoc/normalized-cache/com.apollographql.cache.normalized.api/-field-key-generator/index.html?query=interface%20FieldKeyGenerator) implementation:
 
-Going back to [the example](pagination-home.md) with `usersPage`:
-
-
-```graphql
-extend type Query
-@fieldPolicy(forField: "usersPage" paginationArgs: "page")
+```kotlin
+object MyFieldKeyGenerator : FieldKeyGenerator {
+  override fun getFieldKey(context: FieldKeyContext): String {
+    return if (context.parentType == "Query" && context.field.name == "usersPage") {
+      context.field.newBuilder()
+          .arguments(
+              context.field.arguments.filter { argument ->
+                argument.definition.name != "page" // Omit the `page` argument from the field key
+              }
+          )
+          .build()
+          .nameWithArguments(context.variables)
+    } else {
+      DefaultFieldKeyGenerator.getFieldKey(context)
+    }
+  }
+}
 ```
 
-> This can also be done programmatically by configuring your cache with a [`FieldKeyGenerator`](https://apollographql.github.io/apollo-kotlin-normalized-cache/kdoc/normalized-cache/com.apollographql.cache.normalized.api/-field-key-generator/index.html?query=interface%20FieldKeyGenerator) implementation.
+```kotlin
+val client = ApolloClient.Builder()
+    // ...
+    .normalizedCache(
+        normalizedCacheFactory = cacheFactory,
+        fieldKeyGenerator = MyFieldKeyGenerator, // Configure the cache with the custom field key generator
+    )
+    .build()
+```
 
 With that in place, after fetching the first page, the cache will look like this:
 
@@ -91,11 +110,25 @@ Fields in records can have arbitrary metadata attached to them, in addition to t
 
 Let's go back to the [example](pagination-relay-style.md) where Relay-style pagination is used.
 
-Configure the `paginationArgs` as seen previously:
+Configure the `fieldKeyGenerator` as seen previously:
 
-```graphql
-extend type Query
-@fieldPolicy(forField: "usersConnection" paginationArgs: "first,after,last,before")
+```kotlin
+object MyFieldKeyGenerator : FieldKeyGenerator {
+  override fun getFieldKey(context: FieldKeyContext): String {
+    return if (context.field.type.rawType().name == "UserConnection") {
+      context.field.newBuilder()
+          .arguments(
+              context.field.arguments.filter { argument ->
+                argument.definition.name !in setOf("first", "after", "last", "before") // Omit pagination arguments from the field key
+              }
+          )
+          .build()
+          .nameWithArguments(context.variables)
+    } else {
+      DefaultFieldKeyGenerator.getFieldKey(context)
+    }
+  }
+}
 ```
 
 Now let's store in the metadata of each `UserConnection` field the values of the `before` and `after` arguments of the field returning it,

Writerside/topics/pagination/pagination-relay-style.md

@@ -48,23 +48,25 @@ query UsersConnection($first: Int, $after: String, $last: Int, $before: String)
 }
 ```
 
-If your schema uses this pagination style, the library supports it out of the box: use the `connectionFields` argument to specify the fields
-that return a connection:
+If your schema uses this pagination style, the library supports it out of the box: use the `@connection` directive on Connection types:
 
 ```graphql
-extend type Query @typePolicy(connectionFields: "usersConnection")
+# First import the directive
+extend schema @link(
+  url: "https://specs.apollo.dev/cache/v0.3",
+  import: ["@connection"]
+)
+
+# Then extend your types
+extend type UserConnection @connection
 ```
 
-In Kotlin, configure the cache like this, using the generated `Pagination` object:
+In Kotlin, configure the cache like this, using the generated `cache()` function:
 
 ```kotlin
 val client = ApolloClient.Builder()
     // ...
-    .normalizedCache(
-        normalizedCacheFactory = cacheFactory,
-        metadataGenerator = ConnectionMetadataGenerator(Pagination.connectionTypes),
-        recordMerger = ConnectionRecordMerger
-    )
+    .cache(cacheFactory)
     .build()
 ```
 

normalized-cache-apollo-compiler-plugin/src/main/kotlin/com/apollographql/cache/apollocompilerplugin/ApolloCacheCompilerPlugin.kt

@@ -3,20 +3,19 @@
 package com.apollographql.cache.apollocompilerplugin
 
 import com.apollographql.apollo.annotations.ApolloExperimental
-import com.apollographql.apollo.ast.ForeignSchema
 import com.apollographql.apollo.compiler.ApolloCompilerPlugin
 import com.apollographql.apollo.compiler.ApolloCompilerPluginEnvironment
 import com.apollographql.apollo.compiler.ApolloCompilerRegistry
 import com.apollographql.cache.apollocompilerplugin.internal.AddKeyFieldsExecutableDocumentTransform
 import com.apollographql.cache.apollocompilerplugin.internal.CacheSchemaCodeGenerator
-import com.apollographql.cache.apollocompilerplugin.internal.cacheGQLDefinitions
+import com.apollographql.cache.apollocompilerplugin.internal.cacheForeignSchema
 
 class ApolloCacheCompilerPlugin : ApolloCompilerPlugin {
   override fun beforeCompilationStep(
       environment: ApolloCompilerPluginEnvironment,
       registry: ApolloCompilerRegistry,
   ) {
-    registry.registerForeignSchemas(listOf(ForeignSchema("cache", "v0.1", cacheGQLDefinitions)))
+    registry.registerForeignSchemas(listOf(cacheForeignSchema))
     registry.registerExecutableDocumentTransform("com.apollographql.cache.addKeyFields", transform = AddKeyFieldsExecutableDocumentTransform)
     registry.registerSchemaCodeGenerator(CacheSchemaCodeGenerator(environment))
   }

normalized-cache-apollo-compiler-plugin/src/main/kotlin/com/apollographql/cache/apollocompilerplugin/internal/CacheSchemaCodeGenerator.kt

@@ -4,12 +4,7 @@ package com.apollographql.cache.apollocompilerplugin.internal
 
 import com.apollographql.apollo.annotations.ApolloExperimental
 import com.apollographql.apollo.ast.GQLDocument
-import com.apollographql.apollo.ast.GQLInterfaceTypeDefinition
-import com.apollographql.apollo.ast.GQLObjectTypeDefinition
-import com.apollographql.apollo.ast.GQLStringValue
-import com.apollographql.apollo.ast.GQLUnionTypeDefinition
 import com.apollographql.apollo.ast.Schema
-import com.apollographql.apollo.ast.Schema.Companion.TYPE_POLICY
 import com.apollographql.apollo.ast.toSchema
 import com.apollographql.apollo.compiler.ApolloCompiler
 import com.apollographql.apollo.compiler.ApolloCompilerPluginEnvironment
@@ -40,6 +35,7 @@ private object Symbols {
   val MaxAgeDuration = MaxAge.nestedClass("Duration")
   val Seconds = MemberName(Duration.Companion::class.asTypeName(), "seconds", isExtension = true)
   val TypePolicy = ClassName("com.apollographql.cache.normalized.api", "TypePolicy")
+  val EmbeddedFields = ClassName("com.apollographql.cache.normalized.api", "EmbeddedFields")
   val ApolloClientBuilder = ClassName("com.apollographql.apollo", "ApolloClient", "Builder")
   val NormalizedCacheFactory = ClassName("com.apollographql.cache.normalized.api", "NormalizedCacheFactory")
   val CacheKeyScope = ClassName("com.apollographql.cache.normalized.api", "CacheKey", "Scope")
@@ -59,16 +55,20 @@ internal class CacheSchemaCodeGenerator(
     }
     val packageName = (
         environment.arguments["com.apollographql.cache.packageName"] as? String
-            // Fallback to the old argument name for compatibility with pre-v1.0.0 versions
+        // Fallback to the old argument name for compatibility with pre-v1.0.0 versions
             ?: environment.arguments["packageName"] as? String
             ?: throw IllegalArgumentException("com.apollographql.cache.packageName argument is required and must be a String")) + ".cache"
+    val typePolicies = validSchema.getTypePolicies()
+    val connectionTypes = validSchema.getConnectionTypes()
+    val embeddedFields = validSchema.getEmbeddedFields(typePolicies, connectionTypes)
     val file = FileSpec.builder(packageName, "Cache")
         .addType(
             TypeSpec.objectBuilder("Cache")
                 .addProperty(maxAgeProperty(validSchema))
-                .addProperty(typePoliciesProperty(validSchema))
-                .addProperty(connectionTypesProperty(validSchema, packageName))
-                .addFunction(cacheFunction(validSchema))
+                .addProperty(typePoliciesProperty(typePolicies))
+                .addProperty(embeddedFieldsProperty(embeddedFields))
+                .addProperty(connectionTypesProperty(connectionTypes))
+                .addFunction(cacheFunction())
                 .build()
         )
         .addFileComment(
@@ -108,50 +108,58 @@ internal class CacheSchemaCodeGenerator(
 
   private fun maxAgeProperty(schema: Schema): PropertySpec {
     val maxAges = schema.getMaxAges(environment.logger())
-    val initializer = CodeBlock.builder().apply {
-      add("mapOf(\n")
-      withIndent {
-        maxAges.forEach { (field, duration) ->
-          if (duration == -1) {
-            addStatement("%S to %T,", field, Symbols.MaxAgeInherit)
-          } else {
-            addStatement("%S to %T(%L.%M),", field, Symbols.MaxAgeDuration, duration, Symbols.Seconds)
+    val initializer = if (maxAges.isEmpty()) {
+      CodeBlock.of("emptyMap()")
+    } else {
+      CodeBlock.builder().apply {
+        add("mapOf(\n")
+        withIndent {
+          maxAges.forEach { (field, duration) ->
+            if (duration == -1) {
+              addStatement("%S to %T,", field, Symbols.MaxAgeInherit)
+            } else {
+              addStatement("%S to %T(%L.%M),", field, Symbols.MaxAgeDuration, duration, Symbols.Seconds)
+            }
           }
         }
+        add(")")
       }
-      add(")")
+          .build()
     }
-        .build()
-    return PropertySpec.Companion.builder(
+    return PropertySpec.builder(
         name = "maxAges",
         type = MAP.parameterizedBy(STRING, Symbols.MaxAge)
     )
         .initializer(initializer)
         .build()
   }
 
-  private fun typePoliciesProperty(schema: Schema): PropertySpec {
-    val typePolicies = schema.getTypePolicies()
-    val initializer = CodeBlock.builder().apply {
-      add("mapOf(\n")
-      withIndent {
-        typePolicies.forEach { (type, typePolicy) ->
-          addStatement("%S to %T(", type, Symbols.TypePolicy)
-          withIndent {
-            addStatement("keyFields = setOf(")
+  private fun typePoliciesProperty(typePolicies: Map<String, TypePolicy>): PropertySpec {
+    val typePolicies = typePolicies.filter { it.value.keyFields.isNotEmpty() }
+    val initializer = if (typePolicies.isEmpty()) {
+      CodeBlock.of("emptyMap()")
+    } else {
+      CodeBlock.builder().apply {
+        add("mapOf(\n")
+        withIndent {
+          typePolicies.forEach { (type, typePolicy) ->
+            addStatement("%S to %T(", type, Symbols.TypePolicy)
             withIndent {
-              typePolicy.keyFields.forEach { keyField ->
-                addStatement("%S, ", keyField)
+              addStatement("keyFields = setOf(")
+              withIndent {
+                typePolicy.keyFields.forEach { keyField ->
+                  addStatement("%S, ", keyField)
+                }
               }
+              add("),\n")
             }
-            add("),\n")
+            addStatement("),")
           }
-          addStatement("),")
         }
+        add(")")
       }
-      add(")")
+          .build()
     }
-        .build()
     return PropertySpec.builder(
         name = "typePolicies",
         type = MAP.parameterizedBy(STRING, Symbols.TypePolicy)
@@ -160,14 +168,20 @@ internal class CacheSchemaCodeGenerator(
         .build()
   }
 
-  private fun connectionTypesProperty(schema: Schema, packageName: String): PropertySpec {
-    // TODO: connectionTypes is generated by the Apollo compiler for now, and we just reference it. Instead we should generate it here.
-    val hasPagination = schema.hasConnectionFields()
-    val initializer = if (hasPagination) {
-      val paginationPackageName = packageName.substringBeforeLast(".") + ".pagination"
-      CodeBlock.of("%T.connectionTypes", ClassName(paginationPackageName, "Pagination"))
-    } else {
+  private fun connectionTypesProperty(connectionTypes: Set<String>): PropertySpec {
+    val initializer = if (connectionTypes.isEmpty()) {
       CodeBlock.of("emptySet()")
+    } else {
+      CodeBlock.builder().apply {
+        add("setOf(\n")
+        withIndent {
+          connectionTypes.forEach { connectionType ->
+            addStatement("%S,", connectionType)
+          }
+        }
+        add(")")
+      }
+          .build()
     }
     return PropertySpec.builder(
         name = "connectionTypes",
@@ -177,8 +191,40 @@ internal class CacheSchemaCodeGenerator(
         .build()
   }
 
-  private fun cacheFunction(validSchema: Schema): FunSpec {
-    validSchema.hasConnectionFields()
+  private fun embeddedFieldsProperty(embeddedFields: Map<String, EmbeddedFields>): PropertySpec {
+    val initializer = if (embeddedFields.isEmpty()) {
+      CodeBlock.of("emptyMap()")
+    } else {
+      CodeBlock.builder().apply {
+        add("mapOf(\n")
+        withIndent {
+          embeddedFields.forEach { (type, embeddedField) ->
+            addStatement("%S to %T(", type, Symbols.EmbeddedFields)
+            withIndent {
+              addStatement("embeddedFields = setOf(")
+              withIndent {
+                embeddedField.embeddedFields.forEach { embeddedField ->
+                  addStatement("%S, ", embeddedField)
+                }
+              }
+              add("),\n")
+            }
+            addStatement("),")
+          }
+        }
+        add(")")
+      }
+          .build()
+    }
+    return PropertySpec.builder(
+        name = "embeddedFields",
+        type = MAP.parameterizedBy(STRING, Symbols.EmbeddedFields)
+    )
+        .initializer(initializer)
+        .build()
+  }
+
+  private fun cacheFunction(): FunSpec {
     return FunSpec.builder("cache")
         .receiver(Symbols.ApolloClientBuilder)
         .addParameter("normalizedCacheFactory", Symbols.NormalizedCacheFactory)
@@ -205,6 +251,7 @@ internal class CacheSchemaCodeGenerator(
                         "normalizedCacheFactory = normalizedCacheFactory,\n" +
                         "typePolicies = typePolicies,\n" +
                         "connectionTypes = connectionTypes, \n" +
+                        "embeddedFields = embeddedFields, \n" +
                         "maxAges = maxAges,\n" +
                         "defaultMaxAge = defaultMaxAge,\n" +
                         "keyScope = keyScope,\n" +
@@ -217,16 +264,4 @@ internal class CacheSchemaCodeGenerator(
         )
         .build()
   }
-
-  private fun Schema.hasConnectionFields(): Boolean {
-    val directives = typeDefinitions.values.filterIsInstance<GQLObjectTypeDefinition>().flatMap { it.directives } +
-        typeDefinitions.values.filterIsInstance<GQLInterfaceTypeDefinition>().flatMap { it.directives } +
-        typeDefinitions.values.filterIsInstance<GQLUnionTypeDefinition>().flatMap { it.directives }
-    return directives.any {
-      originalDirectiveName(it.name) == TYPE_POLICY &&
-          it.arguments.any { arg ->
-            arg.name == "connectionFields" && !(arg.value as? GQLStringValue)?.value.isNullOrBlank()
-          }
-    }
-  }
 }