From 4dd1b6f9980e809cb7e6754df78001e7012d6ed7 Mon Sep 17 00:00:00 2001 From: BoD Date: Wed, 23 Apr 2025 11:52:07 +0200 Subject: [PATCH] Clarify the need to call publish for watchers to be notified --- .../cache/normalized/ApolloStore.kt | 47 ++++++++++++++----- .../cache/normalized/ClientCacheExtensions.kt | 5 +- 2 files changed, 40 insertions(+), 12 deletions(-) diff --git a/normalized-cache/src/commonMain/kotlin/com/apollographql/cache/normalized/ApolloStore.kt b/normalized-cache/src/commonMain/kotlin/com/apollographql/cache/normalized/ApolloStore.kt index 0ece78f2..069d20ee 100644 --- a/normalized-cache/src/commonMain/kotlin/com/apollographql/cache/normalized/ApolloStore.kt +++ b/normalized-cache/src/commonMain/kotlin/com/apollographql/cache/normalized/ApolloStore.kt @@ -36,15 +36,21 @@ import kotlinx.coroutines.flow.SharedFlow import kotlin.reflect.KClass /** - * ApolloStore exposes a thread-safe api to access a [com.apollographql.cache.normalized.api.NormalizedCache]. + * ApolloStore exposes a high-level API to access a [com.apollographql.cache.normalized.api.NormalizedCache]. * * Note that most operations are synchronous and might block if the underlying cache is doing IO - calling them from the main thread * should be avoided. + * + * Note that changes are not automatically published - call [publish] to notify any watchers. */ interface ApolloStore { /** - * Exposes the keys of records that have changed. - * A special key [ALL_KEYS] is used to indicate that all records have changed. + * Exposes the record field keys that have changed. This is collected internally to notify watchers. + * + * A special value [ALL_KEYS] indicates that all records have changed. + * + * @see publish + * @see watch */ val changedKeys: SharedFlow> @@ -102,10 +108,12 @@ interface ApolloStore { * * This is a synchronous operation that might block if the underlying cache is doing IO. * + * Call [publish] with the returned keys to notify any watchers. + * * @param operation the operation to write * @param data the operation data to write * @param errors the operation errors to write - * @return the changed keys + * @return the changed field keys * * @see publish */ @@ -122,9 +130,11 @@ interface ApolloStore { * * This is a synchronous operation that might block if the underlying cache is doing IO. * + * Call [publish] with the returned keys to notify any watchers. + * * @param operation the operation to write * @param dataWithErrors the operation data to write as a [DataWithErrors] object - * @return the changed keys + * @return the changed field keys * * @see publish */ @@ -140,10 +150,12 @@ interface ApolloStore { * * This is a synchronous operation that might block if the underlying cache is doing IO. * + * Call [publish] with the returned keys to notify any watchers. + * * @param fragment the fragment to write * @param cacheKey the root where to write the fragment data to * @param data the fragment data to write - * @return the changed keys + * @return the changed field keys * * @see publish */ @@ -160,10 +172,12 @@ interface ApolloStore { * * This is a synchronous operation that might block if the underlying cache is doing IO. * + * Call [publish] with the returned keys to notify any watchers. + * * @param operation the operation to write * @param data the operation data to write * @param mutationId a unique identifier for this optimistic update - * @return the changed keys + * @return the changed field keys * * @see publish */ @@ -179,11 +193,13 @@ interface ApolloStore { * * This is a synchronous operation that might block if the underlying cache is doing IO. * + * Call [publish] with the returned keys to notify any watchers. + * * @param fragment the fragment to write * @param cacheKey the root where to write the fragment data to * @param data the fragment data to write * @param mutationId a unique identifier for this optimistic update - * @return the changed keys + * @return the changed field keys * * @see publish */ @@ -200,8 +216,10 @@ interface ApolloStore { * * This is a synchronous operation that might block if the underlying cache is doing IO. * + * Call [publish] with the returned keys to notify any watchers. + * * @param mutationId the unique identifier of the optimistic update to rollback - * @return the changed keys + * @return the changed field keys * * @see publish */ @@ -214,6 +232,8 @@ interface ApolloStore { * * This is a synchronous operation that might block if the underlying cache is doing IO. * + * Call [publish] with [ALL_KEYS] to notify any watchers. + * * @return `true` if all records were successfully removed, `false` otherwise */ fun clearAll(): Boolean @@ -223,6 +243,8 @@ interface ApolloStore { * * This is a synchronous operation that might block if the underlying cache is doing IO. * + * Call [publish] with [ALL_KEYS] to notify any watchers. + * * @param cacheKey the key of the record to remove * @param cascade whether referenced records should also be removed * @return `true` if the record was successfully removed, `false` otherwise @@ -235,6 +257,8 @@ interface ApolloStore { * * This is a synchronous operation that might block if the underlying cache is doing IO. * + * Call [publish] with [ALL_KEYS] to notify any watchers. + * * @param cacheKeys the keys of the records to remove * @param cascade whether referenced records should also be removed * @return the number of records that have been removed @@ -264,13 +288,14 @@ interface ApolloStore { ): Map /** - * Publishes a set of keys that have changed. This will notify subscribers of [changedKeys]. + * Publishes a set of keys of record fields that have changed. This will notify watchers and any subscribers of [changedKeys]. * * Pass [ALL_KEYS] to indicate that all records have changed, for instance after a [clearAll] operation. * * @see changedKeys + * @see watch * - * @param keys A set of keys of [Record] which have changed. + * @param keys A set of keys of [Record] fields which have changed. */ suspend fun publish(keys: Set) diff --git a/normalized-cache/src/commonMain/kotlin/com/apollographql/cache/normalized/ClientCacheExtensions.kt b/normalized-cache/src/commonMain/kotlin/com/apollographql/cache/normalized/ClientCacheExtensions.kt index 1251f402..ff9063bf 100644 --- a/normalized-cache/src/commonMain/kotlin/com/apollographql/cache/normalized/ClientCacheExtensions.kt +++ b/normalized-cache/src/commonMain/kotlin/com/apollographql/cache/normalized/ClientCacheExtensions.kt @@ -148,10 +148,13 @@ fun ApolloClient.Builder.store(store: ApolloStore, writeToCacheAsynchronously: B /** * Gets initial response(s) then observes the cache for any changes. * - * There is a guarantee that the cache is subscribed before the initial response(s) finish emitting. Any update to the cache done after the initial response(s) are received will be received. + * There is a guarantee that the cache is subscribed before the initial response(s) finish emitting. + * Any update to the cache done after the initial response(s) are received will be received. * * [fetchPolicy] controls how the result is first queried, while [refetchPolicy] will control the subsequent fetches. * + * Note: when manually updating the cache through [ApolloStore], [ApolloStore.publish] must be called for watchers to be notified. + * * @see fetchPolicy * @see refetchPolicy */