Add garbage collecting

CHANGELOG.md

@@ -1,6 +1,6 @@
 # Next version (unreleased)
 
-PUT_CHANGELOG_HERE
+- Add Garbage Collection support (see [the documentation](https://apollographql.github.io/apollo-kotlin-normalized-cache-incubating/garbage-collection.html) for details)
 
 # Version 0.0.4
 _2024-11-07_

Writerside/doc.tree

@@ -11,4 +11,5 @@
     <toc-element topic="welcome.md"/>
     <toc-element topic="pagination.md"/>
     <toc-element topic="cache-control.md"/>
+    <toc-element topic="garbage-collection.md"/>
 </instance-profile>

Writerside/topics/garbage-collection.md

@@ -0,0 +1,46 @@
+# Garbage collection
+
+The garbage collection feature allows to remove unused data from the cache to reduce its size.
+
+## Stale fields
+
+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.
+
+Stale fields can be removed from the cache by calling the `ApolloStore.removeStaleFields` function.
+
+If all fields of a record are stale, the record itself is removed.
+
+Note: when a record is removed, any reference to it will become a [dangling reference](#dangling-references).
+
+## Dangling references
+
+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)
+- records get deleted because all their fields are [stale](#stale-fields)
+
+Dangling references can be removed from the cache by calling the `ApolloStore.removeDanglingReferences` function.
+
+If all fields of a record are dangling references, the record itself is removed.
+
+Note: if a field's value is a list for which one or more elements are dangling references, the entire list is removed, which can result in
+[unreachable records](#unreachable-records).
+
+## Unreachable records
+
+A record is **unreachable** if there exists no chain of references from the root record to it.
+
+This can happen when:
+- 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
+- references get deleted because they're [stale](#stale-fields)
+
+Unreachable records can be removed from the cache by calling the `ApolloStore.removeUnreachableRecords` function.
+
+## `ApolloStore.garbageCollect()`
+
+The `ApolloStore.garbageCollect()` function is a convenience to remove all stale fields, dangling references, and unreachable records from the cache.

normalized-cache-incubating/api/normalized-cache-incubating.api

@@ -94,6 +94,30 @@ public final class com/apollographql/cache/normalized/FetchPolicyInterceptors {
 	public static final fun getNetworkOnlyInterceptor ()Lcom/apollographql/apollo/interceptor/ApolloInterceptor;
 }
 
+public final class com/apollographql/cache/normalized/GarbageCollectResult {
+	public fun <init> (Lcom/apollographql/cache/normalized/RemovedFieldsAndRecords;Lcom/apollographql/cache/normalized/RemovedFieldsAndRecords;Ljava/util/Set;)V
+	public final fun getRemovedDanglingReferences ()Lcom/apollographql/cache/normalized/RemovedFieldsAndRecords;
+	public final fun getRemovedStaleFields ()Lcom/apollographql/cache/normalized/RemovedFieldsAndRecords;
+	public final fun getRemovedUnreachableRecords ()Ljava/util/Set;
+}
+
+public final class com/apollographql/cache/normalized/GarbageCollectionKt {
+	public static final fun allRecords (Lcom/apollographql/cache/normalized/api/NormalizedCache;)Ljava/util/Map;
+	public static final fun garbageCollect-SxA4cEA (Lcom/apollographql/cache/normalized/ApolloStore;Lcom/apollographql/cache/normalized/api/MaxAgeProvider;J)Lcom/apollographql/cache/normalized/GarbageCollectResult;
+	public static final fun garbageCollect-SxA4cEA (Lcom/apollographql/cache/normalized/api/NormalizedCache;Lcom/apollographql/cache/normalized/api/MaxAgeProvider;J)Lcom/apollographql/cache/normalized/GarbageCollectResult;
+	public static synthetic fun garbageCollect-SxA4cEA$default (Lcom/apollographql/cache/normalized/ApolloStore;Lcom/apollographql/cache/normalized/api/MaxAgeProvider;JILjava/lang/Object;)Lcom/apollographql/cache/normalized/GarbageCollectResult;
+	public static synthetic fun garbageCollect-SxA4cEA$default (Lcom/apollographql/cache/normalized/api/NormalizedCache;Lcom/apollographql/cache/normalized/api/MaxAgeProvider;JILjava/lang/Object;)Lcom/apollographql/cache/normalized/GarbageCollectResult;
+	public static final fun getReachableCacheKeys (Lcom/apollographql/cache/normalized/api/NormalizedCache;)Ljava/util/Set;
+	public static final fun removeDanglingReferences (Lcom/apollographql/cache/normalized/ApolloStore;)Lcom/apollographql/cache/normalized/RemovedFieldsAndRecords;
+	public static final fun removeDanglingReferences (Lcom/apollographql/cache/normalized/api/NormalizedCache;)Lcom/apollographql/cache/normalized/RemovedFieldsAndRecords;
+	public static final fun removeStaleFields-SxA4cEA (Lcom/apollographql/cache/normalized/ApolloStore;Lcom/apollographql/cache/normalized/api/MaxAgeProvider;J)Lcom/apollographql/cache/normalized/RemovedFieldsAndRecords;
+	public static final fun removeStaleFields-SxA4cEA (Lcom/apollographql/cache/normalized/api/NormalizedCache;Lcom/apollographql/cache/normalized/api/MaxAgeProvider;J)Lcom/apollographql/cache/normalized/RemovedFieldsAndRecords;
+	public static synthetic fun removeStaleFields-SxA4cEA$default (Lcom/apollographql/cache/normalized/ApolloStore;Lcom/apollographql/cache/normalized/api/MaxAgeProvider;JILjava/lang/Object;)Lcom/apollographql/cache/normalized/RemovedFieldsAndRecords;
+	public static synthetic fun removeStaleFields-SxA4cEA$default (Lcom/apollographql/cache/normalized/api/NormalizedCache;Lcom/apollographql/cache/normalized/api/MaxAgeProvider;JILjava/lang/Object;)Lcom/apollographql/cache/normalized/RemovedFieldsAndRecords;
+	public static final fun removeUnreachableRecords (Lcom/apollographql/cache/normalized/ApolloStore;)Ljava/util/Set;
+	public static final fun removeUnreachableRecords (Lcom/apollographql/cache/normalized/api/NormalizedCache;)Ljava/util/Set;
+}
+
 public final class com/apollographql/cache/normalized/NormalizedCache {
 	public static final fun -logCacheMisses (Lcom/apollographql/apollo/ApolloClient$Builder;Lkotlin/jvm/functions/Function1;)Lcom/apollographql/apollo/ApolloClient$Builder;
 	public static synthetic fun -logCacheMisses$default (Lcom/apollographql/apollo/ApolloClient$Builder;Lkotlin/jvm/functions/Function1;ILjava/lang/Object;)Lcom/apollographql/apollo/ApolloClient$Builder;
@@ -132,6 +156,12 @@ public final class com/apollographql/cache/normalized/NormalizedCache {
 	public static final fun writeToCacheAsynchronously (Lcom/apollographql/apollo/api/MutableExecutionOptions;Z)Ljava/lang/Object;
 }
 
+public final class com/apollographql/cache/normalized/RemovedFieldsAndRecords {
+	public fun <init> (Ljava/util/Set;Ljava/util/Set;)V
+	public final fun getRemovedFields ()Ljava/util/Set;
+	public final fun getRemovedRecords ()Ljava/util/Set;
+}
+
 public final class com/apollographql/cache/normalized/VersionKt {
 	public static final field VERSION Ljava/lang/String;
 }
@@ -359,6 +389,13 @@ public final class com/apollographql/cache/normalized/api/MaxAgeContext {
 	public final fun getFieldPath ()Ljava/util/List;
 }
 
+public final class com/apollographql/cache/normalized/api/MaxAgeContext$Field {
+	public fun <init> (Ljava/lang/String;Ljava/lang/String;Z)V
+	public final fun getName ()Ljava/lang/String;
+	public final fun getType ()Ljava/lang/String;
+	public final fun isTypeComposite ()Z
+}
+
 public abstract interface class com/apollographql/cache/normalized/api/MaxAgeProvider {
 	public abstract fun getMaxAge-5sfh64U (Lcom/apollographql/cache/normalized/api/MaxAgeContext;)J
 }
@@ -383,6 +420,7 @@ public abstract interface class com/apollographql/cache/normalized/api/Normalize
 	public static fun prettifyDump (Ljava/util/Map;)Ljava/lang/String;
 	public abstract fun remove (Lcom/apollographql/cache/normalized/api/CacheKey;Z)Z
 	public abstract fun remove (Ljava/lang/String;)I
+	public abstract fun remove (Ljava/util/Collection;Z)I
 }
 
 public final class com/apollographql/cache/normalized/api/NormalizedCache$Companion {
@@ -515,6 +553,7 @@ public final class com/apollographql/cache/normalized/memory/MemoryCache : com/a
 	public fun merge (Ljava/util/Collection;Lcom/apollographql/cache/normalized/api/CacheHeaders;Lcom/apollographql/cache/normalized/api/RecordMerger;)Ljava/util/Set;
 	public fun remove (Lcom/apollographql/cache/normalized/api/CacheKey;Z)Z
 	public fun remove (Ljava/lang/String;)I
+	public fun remove (Ljava/util/Collection;Z)I
 }
 
 public final class com/apollographql/cache/normalized/memory/MemoryCacheFactory : com/apollographql/cache/normalized/api/NormalizedCacheFactory {