apollographql · BoD · Apr 9, 2025 · Apr 9, 2025
@@ -1,5 +1,11 @@
 # Next version (unreleased)
 
+- Removing "incubating" from the repository and artifacts name. With a stable API on the horizon, now is a great time to try the library in your projects and give us feedback.
+  The artifacts are now:
+  - `com.apollographql.cache:normalized-cache` for the memory cache
+  - `com.apollographql.cache:normalized-cache-sqlite` for the SQL cache.
+
+  The package names are unchanged.
 - Records are now rooted per operation type (QUERY_ROOT, MUTATION_ROOT, SUBSCRIPTION_ROOT) (#109)
 - `ApolloClient.apolloStore` is deprecated in favor of `ApolloClient.store` for consistency.
 - Individual `ApolloStore` methods no longer accept a `CustomScalarAdapters`. Instead it can be passed to the `ApolloStore` constructor.

@@ -7,26 +7,26 @@
 [![Discourse](https://img.shields.io/discourse/topics?label=Discourse&server=https%3A%2F%2Fcommunity.apollographql.com&logo=discourse&color=467B95&style=flat-square)](http://community.apollographql.com/new-topic?category=Help&tags=mobile,client)
 [![Slack](https://img.shields.io/static/v1?label=kotlinlang&message=apollo-kotlin&color=A97BFF&logo=slack&style=flat-square)](https://app.slack.com/client/T09229ZC6/C01A6KM1SBZ)
 
-[![Maven Central](https://img.shields.io/maven-central/v/com.apollographql.cache/normalized-cache-incubating?style=flat-square)](https://central.sonatype.com/namespace/com.apollographql.cache)
-[![OSS Snapshots](https://img.shields.io/nexus/s/com.apollographql.cache/normalized-cache-incubating?server=https%3A%2F%2Fs01.oss.sonatype.org&label=oss-snapshots&style=flat-square)](https://s01.oss.sonatype.org/content/repositories/snapshots/com/apollographql/cache/)
+[![Maven Central](https://img.shields.io/maven-central/v/com.apollographql.cache/normalized-cache?style=flat-square)](https://central.sonatype.com/namespace/com.apollographql.cache)
+[![OSS Snapshots](https://img.shields.io/nexus/s/com.apollographql.cache/normalized-cache?server=https%3A%2F%2Fs01.oss.sonatype.org&label=oss-snapshots&style=flat-square)](https://s01.oss.sonatype.org/content/repositories/snapshots/com/apollographql/cache/)
 
 </div>
 
-## 🚀 Apollo Kotlin Normalized Cache Incubating
+## 🚀 Apollo Kotlin Normalized Cache
 
-This repository serves as a place to experiment with [Apollo Kotlin](https://github.com/apollographql/apollo-kotlin)'s normalized cache without impacting the main stable repository.
+This repository hosts [Apollo Kotlin](https://github.com/apollographql/apollo-kotlin)'s new normalized cache, aiming to replace the main repository version.
 
 ## 📚 Documentation
 
 See the project website for documentation:<br/>
-[https://apollographql.github.io/apollo-kotlin-normalized-cache-incubating/](https://apollographql.github.io/apollo-kotlin-normalized-cache-incubating/)
+[https://apollographql.github.io/apollo-kotlin-normalized-cache/](https://apollographql.github.io/apollo-kotlin-normalized-cache/)
 
 The Kdoc API reference can be found at:<br/>
-[https://apollographql.github.io/apollo-kotlin-normalized-cache-incubating/kdoc](https://apollographql.github.io/apollo-kotlin-normalized-cache-incubating/kdoc)
+[https://apollographql.github.io/apollo-kotlin-normalized-cache/kdoc](https://apollographql.github.io/apollo-kotlin-normalized-cache/kdoc)
 
 ## ⚠️ Disclaimer
 
-The incubating version of the normalized cache is not stable and is subject to change. It is recommended to experiment with it in
+This version is not yet stable and is subject to change. It is recommended to experiment with it in
 non-critical projects/modules, or behind a feature flag.
 
 In particular,

@@ -9,10 +9,10 @@
       <custom-favicons>favicon-96x96.png,favicon-192x192.png</custom-favicons>
       <noindex-content>true</noindex-content>
       <download-title>GitHub</download-title>
-      <download-page>https://github.com/apollographql/apollo-kotlin-normalized-cache-incubating/</download-page>
+      <download-page>https://github.com/apollographql/apollo-kotlin-normalized-cache/</download-page>
       <showDownloadButton>true</showDownloadButton>
       <enable-browser-edits>true</enable-browser-edits>
-      <browser-edits-url>https://github.com/apollographql/apollo-kotlin-normalized-cache-incubating/edit/main/Writerside/
+      <browser-edits-url>https://github.com/apollographql/apollo-kotlin-normalized-cache/edit/main/Writerside/
       </browser-edits-url>
       <custom-css>custom.css</custom-css>
     </variables>

@@ -3,12 +3,12 @@
 
 <instance-profile
     id="doc"
-    name="apollo-kotlin-normalized-cache-incubating"
+    name="apollo-kotlin-normalized-cache"
     start-page="welcome.md"
 >
 
-  <toc-element toc-title="GitHub" href="https://github.com/apollographql/apollo-kotlin-normalized-cache-incubating" />
-  <toc-element toc-title="Kdoc" href="https://apollographql.github.io/apollo-kotlin-normalized-cache-incubating/kdoc" />
+  <toc-element toc-title="GitHub" href="https://github.com/apollographql/apollo-kotlin-normalized-cache" />
+  <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="pagination-home.md">

@@ -10,7 +10,8 @@ When receiving a response from the server, the [`Cache-Control` HTTP header](htt
 
 > 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 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-incubating/kdoc/normalized-cache-incubating/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-incubating/kdoc/normalized-cache-incubating/com.apollographql.cache.normalized.api/-cache-control-cache-resolver/index.html):
+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):
 
 ```kotlin
 val apolloClient = ApolloClient.builder()
@@ -29,8 +30,8 @@ val apolloClient = ApolloClient.builder()
 
 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**.
 
-To store the **received date** of fields, call [`.storeReceivedDate(true)`](https://apollographql.github.io/apollo-kotlin-normalized-cache-incubating/kdoc/normalized-cache-incubating/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-incubating/kdoc/normalized-cache-incubating/com.apollographql.cache.normalized.api/-cache-control-cache-resolver/index.html):
+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):
 
 ```kotlin
 val apolloClient = ApolloClient.builder()
@@ -45,11 +46,11 @@ 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-incubating/kdoc/normalized-cache-incubating/com.apollographql.cache.normalized.api/-max-age-provider/index.html?query=interface%20MaxAgeProvider) to the `CacheControlCacheResolver`.
+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`.
 
 ### Global max age
 
-To set a global maximum age for all fields, pass a [`GlobalMaxAgeProvider`](https://apollographql.github.io/apollo-kotlin-normalized-cache-incubating/kdoc/normalized-cache-incubating/com.apollographql.cache.normalized.api/-global-max-age-provider/index.html?query=class%20GlobalMaxAgeProvider(maxAge:%20Duration)%20:%20MaxAgeProvider) to the `CacheControlCacheResolver`:
+To set a global maximum age for all fields, pass a [`GlobalMaxAgeProvider`](https://apollographql.github.io/apollo-kotlin-normalized-cache/kdoc/normalized-cache/com.apollographql.cache.normalized.api/-global-max-age-provider/index.html?query=class%20GlobalMaxAgeProvider(maxAge:%20Duration)%20:%20MaxAgeProvider) to the `CacheControlCacheResolver`:
 
 ```kotlin
     cacheResolver = CacheControlCacheResolver(GlobalMaxAgeProvider(1.hours)),
@@ -59,7 +60,7 @@ To set a global maximum age for all fields, pass a [`GlobalMaxAgeProvider`](http
 
 #### Programmatically
 
-Use a [`SchemaCoordinatesMaxAgeProvider`](https://apollographql.github.io/apollo-kotlin-normalized-cache-incubating/kdoc/normalized-cache-incubating/com.apollographql.cache.normalized.api/-schema-coordinates-max-age-provider/index.html?query=class%20SchemaCoordinatesMaxAgeProvider(maxAges:%20Map%3CString,%20MaxAge%3E,%20defaultMaxAge:%20Duration)%20:%20MaxAgeProvider) to specify a max age per type and/or field:
+Use a [`SchemaCoordinatesMaxAgeProvider`](https://apollographql.github.io/apollo-kotlin-normalized-cache/kdoc/normalized-cache/com.apollographql.cache.normalized.api/-schema-coordinates-max-age-provider/index.html?query=class%20SchemaCoordinatesMaxAgeProvider(maxAges:%20Map%3CString,%20MaxAge%3E,%20defaultMaxAge:%20Duration)%20:%20MaxAgeProvider) to specify a max age per type and/or field:
 
 ```kotlin
 cacheResolver = CacheControlCacheResolver(
@@ -128,7 +129,7 @@ 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-incubating/kdoc/normalized-cache-incubating/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:
+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())
@@ -139,7 +140,7 @@ val response = client.query(MyQuery())
 
 ### `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-incubating/kdoc/normalized-cache-incubating/com.apollographql.cache.normalized/-cache-info/is-stale.html):
+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) {

@@ -9,7 +9,7 @@ A field is considered stale if its **received date** is older than its (client c
 
 See [](cache-control.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-incubating/kdoc/normalized-cache-incubating/com.apollographql.cache.normalized/remove-stale-fields.html) function.
+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.
 
 If all fields of a record are stale, the record itself is removed.
 
@@ -20,10 +20,11 @@ Note: when a record is removed, any reference to it will become a [dangling refe
 A **dangling reference** is a field whose value is a reference to a cache key that does not exist in the cache.
 
 This can happen when:
-- manually deleting records with [`ApolloStore.remove()`](https://apollographql.github.io/apollo-kotlin-normalized-cache-incubating/kdoc/normalized-cache-incubating/com.apollographql.cache.normalized/-apollo-store/remove.html)
+
+- manually deleting records with [`ApolloStore.remove()`](https://apollographql.github.io/apollo-kotlin-normalized-cache/kdoc/normalized-cache/com.apollographql.cache.normalized/-apollo-store/remove.html)
 - records get deleted because all their fields are [stale](#stale-fields)
 
-Dangling references can be removed from the cache by calling the [`ApolloStore.removeDanglingReferences()`](https://apollographql.github.io/apollo-kotlin-normalized-cache-incubating/kdoc/normalized-cache-incubating/com.apollographql.cache.normalized/remove-dangling-references.html) function.
+Dangling references can be removed from the cache by calling the [`ApolloStore.removeDanglingReferences()`](https://apollographql.github.io/apollo-kotlin-normalized-cache/kdoc/normalized-cache/com.apollographql.cache.normalized/remove-dangling-references.html) function.
 
 If all fields of a record are dangling references, the record itself is removed.
 
@@ -36,12 +37,12 @@ A record is **unreachable** if there exists no chain of references from the root
 
 This can happen when:
 - data that was previously returned by the server is no longer returned by a subsequent query
-- manually adding records with [`ApolloStore.writeFragment()`](https://apollographql.github.io/apollo-kotlin-normalized-cache-incubating/kdoc/normalized-cache-incubating/com.apollographql.cache.normalized/-apollo-store/write-fragment.html)
-- manually deleting records with [`ApolloStore.remove()`](https://apollographql.github.io/apollo-kotlin-normalized-cache-incubating/kdoc/normalized-cache-incubating/com.apollographql.cache.normalized/-apollo-store/remove.html) and `cascade = false`: the deleted record could be the only one referencing others
+- manually adding records with [`ApolloStore.writeFragment()`](https://apollographql.github.io/apollo-kotlin-normalized-cache/kdoc/normalized-cache/com.apollographql.cache.normalized/-apollo-store/write-fragment.html)
+- manually deleting records with [`ApolloStore.remove()`](https://apollographql.github.io/apollo-kotlin-normalized-cache/kdoc/normalized-cache/com.apollographql.cache.normalized/-apollo-store/remove.html) and `cascade = false`: the deleted record could be the only one referencing others
 - references get deleted because they're [stale](#stale-fields)
 
-Unreachable records can be removed from the cache by calling the [`ApolloStore.removeUnreachableRecords()`](https://apollographql.github.io/apollo-kotlin-normalized-cache-incubating/kdoc/normalized-cache-incubating/com.apollographql.cache.normalized/remove-unreachable-records.html) function.
+Unreachable records can be removed from the cache by calling the [`ApolloStore.removeUnreachableRecords()`](https://apollographql.github.io/apollo-kotlin-normalized-cache/kdoc/normalized-cache/com.apollographql.cache.normalized/remove-unreachable-records.html) function.
 
 ## `ApolloStore.garbageCollect()`
 
-The [`ApolloStore.garbageCollect()`](https://apollographql.github.io/apollo-kotlin-normalized-cache-incubating/kdoc/normalized-cache-incubating/com.apollographql.cache.normalized/garbage-collect.html) function is a convenience to remove all stale fields, dangling references, and unreachable records from the cache.
+The [`ApolloStore.garbageCollect()`](https://apollographql.github.io/apollo-kotlin-normalized-cache/kdoc/normalized-cache/com.apollographql.cache.normalized/garbage-collect.html) function is a convenience to remove all stale fields, dangling references, and unreachable records from the cache.