Add documentation for cache-control options. (#212)

* Move cache-control up

* favor present

* Add documentation for cache options

* Update Writerside/topics/options.md

Co-authored-by: Benoit 'BoD' Lubek <[email protected]>

* Update Writerside/topics/options.md

Co-authored-by: Benoit 'BoD' Lubek <[email protected]>

* Rename allowCachedErrors -> serverErrorsAsCacheMisses and allowCachePartialResults -> throwOnCacheMiss

* Rename cache control -> expiration

---------

Co-authored-by: Benoit 'BoD' Lubek <[email protected]>

Author: martinbonnin

CHANGELOG.md

@@ -108,7 +108,7 @@ _2024-12-18_
 # Version 0.0.4
 _2024-11-07_
 
-- Cache control support (see [the documentation](https://apollographql.github.io/apollo-kotlin-normalized-cache-incubating/cache-control.html) for details)
+- Expiration support (see [the documentation](https://apollographql.github.io/apollo-kotlin-normalized-cache-incubating/expiration.html) for details)
 - Compatibility with the IntelliJ plugin cache viewer (#42)
 - For consistency, `MemoryCacheFactory` and `MemoryCache` are now in the `com.apollographql.cache.normalized.memory` package 
 - Remove deprecated symbols

README.md

@@ -19,7 +19,7 @@ This repository hosts [Apollo Kotlin](https://github.com/apollographql/apollo-ko
 Compared to the previous version, this new normalized cache brings:
 
 - [Pagination support](https://apollographql.github.io/apollo-kotlin-normalized-cache/pagination-home.html)
-- [Cache control](https://apollographql.github.io/apollo-kotlin-normalized-cache/cache-control.html) (a.k.a. Time to live or expiration)
+- [Expiration](https://apollographql.github.io/apollo-kotlin-normalized-cache/expiration.html) (a.k.a. Time to live)
 - [Garbage collection](https://apollographql.github.io/apollo-kotlin-normalized-cache/garbage-collection.html), and [trimming](https://apollographql.github.io/apollo-kotlin-normalized-cache/trimming.html)
 - Partial results from the cache
 - API simplifications

Writerside/doc.tree

@@ -11,12 +11,13 @@
   <toc-element toc-title="Kdoc" href="https://apollographql.github.io/apollo-kotlin-normalized-cache/kdoc" />
   <toc-element topic="welcome.md" />
   <toc-element topic="migration-guide.md" />
+  <toc-element topic="expiration.md" />
+  <toc-element topic="options.md" />
   <toc-element topic="pagination-home.md">
     <toc-element topic="pagination-relay-style.md" />
     <toc-element topic="pagination-other.md" />
     <toc-element topic="pagination-manual.md" />
   </toc-element>
-  <toc-element topic="cache-control.md" />
   <toc-element topic="garbage-collection.md" />
   <toc-element topic="trimming.md" />
   <toc-element topic="partial-cache-reads.md" />

Writerside/topics/compiler-plugin.md

@@ -30,7 +30,7 @@ apollo {
 }
 </code-block>
 
-This plugin generates some code to support the Normalized Cache features, such as declarative cache IDs, pagination and cache control.
+This plugin generates some code to support the Normalized Cache features, such as declarative cache IDs, pagination and expiration.
 
 ## Declarative cache IDs (`@typePolicy`)
 

Writerside/topics/cache-control.md renamed to Writerside/topics/expiration.md

@@ -1,15 +1,18 @@
-# Cache control
+# Expiration
 
-The cache control feature takes the freshness of fields into consideration when accessing the cache. This is also sometimes referred to as TTL (Time To Live) or expiration.
+The cache can be configured to store expiration information using a max-age. This is also sometimes referred to as TTL (Time To Live) or freshness.
 
-Freshness can be configured by the server, by the client, or both.
+Max-age can be configured by the server, by the client, or both.
 
-## Server-controlled
+## Server-controlled max-age
 
-When receiving a response from the server, the [`Cache-Control` HTTP header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control) can be used to determine the **expiration date** of the fields in the response.
+When receiving a response from the server, the [`Cache-Control` HTTP header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control) can be used to determine the **max age** of the fields in the response.
 
 > Apollo Server can be configured to include the `Cache-Control` header in responses. See the [caching documentation](https://www.apollographql.com/docs/apollo-server/performance/caching/) for more information.
 
+> The [`Expires` HTTP header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Expires) is not supported. Only `Cache-Control` is.
+{style="note"}
+
 The cache can be configured to store the **expiration date** of the received fields in the corresponding records. To do so, call [`.storeExpirationDate(true)`](https://apollographql.github.io/apollo-kotlin-normalized-cache/kdoc/normalized-cache/com.apollographql.cache.normalized/store-expiration-date.html?query=fun%20%3CT%3E%20MutableExecutionOptions%3CT%3E.storeExpirationDate(storeExpirationDate:%20Boolean):%20T), and set your client's cache resolver to [
 `CacheControlCacheResolver`](https://apollographql.github.io/apollo-kotlin-normalized-cache/kdoc/normalized-cache/com.apollographql.cache.normalized.api/-cache-control-cache-resolver/index.html):
 
@@ -24,11 +27,11 @@ val apolloClient = ApolloClient.builder()
   .build()
 ```
 
-**Expiration dates** will be stored and when a field is resolved, the cache resolver will check if the field is stale. If so, it will throw a `CacheMissException`.
+**Expiration dates** are stored and when a field is resolved, the cache resolver will check if the field is stale. If so, it will return an error..
 
-## Client-controlled
+## Client-controlled max-age
 
-When storing fields, the cache can also store their **received date**. This date can then be compared to the current date when resolving a field to determine if its age is above its **maximum age**.
+When storing fields, the cache can also store their **received date**. This date can then be compared to the current date when resolving a field to determine if its age is above its **max age**.
 
 To store the **received date** of fields, call [`.storeReceivedDate(true)`](https://apollographql.github.io/apollo-kotlin-normalized-cache/kdoc/normalized-cache/com.apollographql.cache.normalized/store-receive-date.html?query=fun%20%3CT%3E%20MutableExecutionOptions%3CT%3E.storeReceivedDate(storeReceivedDate:%20Boolean):%20T), and set your client's cache resolver to [
 `CacheControlCacheResolver`](https://apollographql.github.io/apollo-kotlin-normalized-cache/kdoc/normalized-cache/com.apollographql.cache.normalized.api/-cache-control-cache-resolver/index.html):
@@ -46,7 +49,7 @@ val apolloClient = ApolloClient.builder()
 
 > Expiration dates and received dates can be both stored to combine server-controlled and client-controlled expiration strategies.
 
-The **maximum age** of fields can be configured either programmatically, or declaratively in the schema. This is done by passing a [`MaxAgeProvider`](https://apollographql.github.io/apollo-kotlin-normalized-cache/kdoc/normalized-cache/com.apollographql.cache.normalized.api/-max-age-provider/index.html?query=interface%20MaxAgeProvider) to the `CacheControlCacheResolver`.
+The **max age** of fields can be configured either programmatically, or declaratively in the schema. This is done by passing a [`MaxAgeProvider`](https://apollographql.github.io/apollo-kotlin-normalized-cache/kdoc/normalized-cache/com.apollographql.cache.normalized.api/-max-age-provider/index.html?query=interface%20MaxAgeProvider) to the `CacheControlCacheResolver`.
 
 ### Global max age
 
@@ -102,7 +105,7 @@ extend type Book @cacheControlField(name: "cachedTitle", maxAge: 30)
 extend type Reader @cacheControlField(name: "book", inheritMaxAge: true)
 ```
 
-This will generate a map in `yourpackage.cache.Cache.maxAges`, that you can pass to the `SchemaCoordinatesMaxAgeProvider`:
+This generates a map in `yourpackage.cache.Cache.maxAges`, that you can pass to the `SchemaCoordinatesMaxAgeProvider`:
 
 ```kotlin
 cacheResolver = CacheControlCacheResolver(
@@ -112,24 +115,3 @@ cacheResolver = CacheControlCacheResolver(
   )
 ),
 ```
-
-## Maximum staleness
-
-If stale fields are acceptable up to a certain value, you can set a maximum staleness duration. This duration is the maximum time that a stale field will be resolved without resulting in a cache miss. To set this duration, call [`.maxStale(Duration)`](https://apollographql.github.io/apollo-kotlin-normalized-cache/kdoc/normalized-cache/com.apollographql.cache.normalized/max-stale.html?query=fun%20%3CT%3E%20MutableExecutionOptions%3CT%3E.maxStale(maxStale:%20Duration):%20T) either globally on your client, or per operation:
-
-```kotlin
-val response = client.query(MyQuery())
-    .fetchPolicy(FetchPolicy.CacheOnly)
-    .maxStale(1.hours)
-    .execute()
-```
-
-### `isStale`
-
-With `maxStale`, it is possible to get data from the cache even if it is stale. To know if the response contains stale fields, you can check [`CacheInfo.isStale`](https://apollographql.github.io/apollo-kotlin-normalized-cache/kdoc/normalized-cache/com.apollographql.cache.normalized/-cache-info/is-stale.html):
-
-```kotlin
-if (response.cacheInfo?.isStale == true) {
-  // The response contains at least one stale field
-}
-```

Writerside/topics/garbage-collection.md

@@ -7,7 +7,7 @@ The garbage collection feature allows to remove unused data from the cache to re
 A field is considered stale if its **received date** is older than its (client controlled) max age, or if its (server controlled)
 **expiration date** has passed.
 
-See [](cache-control.md) for more information about staleness.
+See [](expiration.md) for more information about staleness.
 
 Stale fields can be removed from the cache by calling the [`ApolloStore.removeStaleFields()`](https://apollographql.github.io/apollo-kotlin-normalized-cache/kdoc/normalized-cache/com.apollographql.cache.normalized/remove-stale-fields.html) function.
 

Writerside/topics/migration-guide.md

@@ -196,7 +196,7 @@ interface CacheResolver {
 
 `resolveField` can also now return a `ResolvedValue` when metadata should be returned with the resolved value (e.g. staleness).
 
-If you wish to use the [Cache Control](cache-control.md) feature, a [`CacheControlCacheResolver`](https://apollographql.github.io/apollo-kotlin-normalized-cache/kdoc/normalized-cache/com.apollographql.cache.normalized.api/-cache-control-cache-resolver/index.html) should be used.
+If you wish to use the [Expiration](expiration.md) feature, a [`CacheControlCacheResolver`](https://apollographql.github.io/apollo-kotlin-normalized-cache/kdoc/normalized-cache/com.apollographql.cache.normalized.api/-cache-control-cache-resolver/index.html) should be used.
 You can call the generated `cache()` extension on `ApolloClient.Builder` which will use it by default if max ages are configured in the schema.
 
 ### `TypePolicyCacheKeyGenerator`

Writerside/topics/options.md

@@ -0,0 +1,54 @@
+# Query options
+
+When you execute a query, options control how the query is executed. `ApolloClient` returns an `ApolloResponse` that satisfies the options or an exceptional response otherwise (`response.exception` is not null).
+
+## `fetchPolicy`
+
+Fetch policy controls how and if the cache is used. The default is `CacheFirst`.
+
+### `CacheFirst`
+
+A response is fetched from the cache first. If no valid response cannot be found, the network is queried.
+
+### `CacheOnly`
+
+The response is fetched from the cache. If no valid response cannot be found, `response.exception` is set.
+
+### `NetworkOnly`
+
+The response is fetched from the network. If no valid response cannot be found, `response.exception` is set.
+
+### `NetworkFirst`
+
+A response is fetched from the network first. If no valid response cannot be found, the cache is queried.
+
+## `serverErrorsAsCacheMisses`
+
+Sets whether GraphQL errors in the cache should be treated as cache misses. When true (the default), if any field is an Error in the cache, the returned response will have a null data and a non-null exception of type `ApolloGraphQLException`.
+
+## `throwOnCacheMiss`
+
+Sets whether missing fields from the cache should result in an exception. When true (the default), if any field is missing in the cache, the returned response will have a null data and a non-null exception of type `CacheMissException`.
+
+Set this to false to allow partial responses from the cache, where _some_ or _all_ of the fields may be missing.
+
+## `maxStale`
+
+If stale fields are acceptable up to a certain value, you can set a maximum staleness duration. This duration is the maximum time that a stale field will be resolved without resulting in a cache miss. To set this duration, call [`.maxStale(Duration)`](https://apollographql.github.io/apollo-kotlin-normalized-cache/kdoc/normalized-cache/com.apollographql.cache.normalized/max-stale.html?query=fun%20%3CT%3E%20MutableExecutionOptions%3CT%3E.maxStale(maxStale:%20Duration):%20T) either globally on your client, or per operation:
+
+```kotlin
+val response = client.query(MyQuery())
+    .fetchPolicy(FetchPolicy.CacheOnly)
+    .maxStale(1.hours)
+    .execute()
+```
+
+### `isStale`
+
+With `maxStale`, it is possible to get data from the cache even if it is stale. To know if the response contains stale fields, you can check [`CacheInfo.isStale`](https://apollographql.github.io/apollo-kotlin-normalized-cache/kdoc/normalized-cache/com.apollographql.cache.normalized/-cache-info/is-stale.html):
+
+```kotlin
+if (response.cacheInfo?.isStale == true) {
+  // The response contains at least one stale field
+}
+```

Writerside/topics/partial-cache-reads.md

@@ -1,7 +1,7 @@
 # Partial cache reads
 
 The cache supports partial cache reads, in a similar way to how GraphQL supports partial responses.
-This means that if some fields are missing from the cache, the cache will return the available data along with any errors for the missing fields.
+This means that if some fields are missing from the cache, the cache returns the available data along with any errors for the missing fields.
 
 ## With `ApolloStore`
 

Writerside/topics/trimming.md

@@ -1,6 +1,6 @@
 # Trimming the cache
 
-By default, if you don't use [cache control](cache-control.md) and [garbage collection](garbage-collection.md),
+By default, if you don't use [expiration](expiration.md) and [garbage collection](garbage-collection.md),
 the cache will grow indefinitely as more data is written to it.
 
 To prevent this, a few APIs are available: