feat!: remove coroutine dependency when building cache

Author: tim-romel-kr

.github/workflows/pull_request.yml

@@ -14,6 +14,6 @@ jobs:
         with:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           github_configuration_owner: 'krogerco'
-          github_configuration_repo: 'Shared-CI-Action-Android'
+          github_configuration_repo: 'Shared-CI-Workflow-Android'
           github_configuration_path: '.github/config/pr-title-checker-config.json'
           github_configuration_ref: 'v1.0.0'

README.md

@@ -37,26 +37,27 @@ val fileCache = SnapshotFileCacheBuilder.from(
     filename = "cacheFile.json", // cache file created in application's cache directory
     keySerializer = String.serializer(), // serializer for cache keys
     valueSerializer = String.serializer(), // serializer for cache values
-).build().getOrThrow()
+).build()
 ```
 
 Once the `fileCache` is created a `MemoryCacheManager` can then be created that utilizes it.
 ```kotlin
 cache = MemoryCacheManagerBuilder.from(
     context, // application context
-    scope, // CoroutineScope used to periodically save the cache
     fileCache, // persistent cache to periodically save cache entries to
-).build()
+)
+    .coroutineScope(coroutineScope) // CoroutineScope used to periodically save the cache
+    .build()
 ```
 
 Use the `cache`.
 
 ```kotlin
 // add a value to the cache
-cache["newKey"] = computeExpensiveValue()
+cache.put("newKey", computeExpensiveValue())
 
 // ...somewhere else retrieve and use the value
-val expensiveValue = cache["newKey"]
+val expensiveValue = cache.get("newKey")
 println(expensiveValue)
 ```
 
@@ -107,9 +108,10 @@ A `MemoryCacheManager` can be created using one of the builder factory functions
 ```kotlin
 val cache = MemoryCacheManagerBuilder.from(
     context, // application context
-    coroutineScope,
     snapshotPersistentCache = fileCache, // see Cache Configuration section for an example
-).build()
+)
+    .coroutineScope(coroutineScope)
+    .build()
 ```
 
 When retrieving an entry from the `Cache` an expired entry will never be returned.

android/src/main/java/com/kroger/cache/android/extensions/MemoryCacheManagerBuilderExtensions.kt

@@ -28,7 +28,6 @@ import com.kroger.cache.MemoryCacheManagerBuilder
 import com.kroger.cache.SnapshotPersistentCache
 import com.kroger.cache.android.internal.AndroidMemoryLevelNotifier
 import com.kroger.cache.internal.CacheEntry
-import kotlinx.coroutines.CoroutineScope
 
 /**
  * Creates a [MemoryCacheManagerBuilder] that uses [AndroidMemoryLevelNotifier] to trim
@@ -37,8 +36,6 @@ import kotlinx.coroutines.CoroutineScope
  */
 public fun <K, V> MemoryCacheManagerBuilder.Companion.from(
     context: Context,
-    coroutineScope: CoroutineScope,
-    snapshotPersistentCache: SnapshotPersistentCache<List<CacheEntry<K, V>>>?,
-): MemoryCacheManagerBuilder<K, V> =
-    from(coroutineScope, snapshotPersistentCache)
-        .memoryLevelNotifier(AndroidMemoryLevelNotifier(context))
+    snapshotPersistentCache: SnapshotPersistentCache<List<CacheEntry<K, V>>>? = null,
+): MemoryCacheManagerBuilder<K, V> = from(snapshotPersistentCache)
+    .memoryLevelNotifier(AndroidMemoryLevelNotifier(context))

android/src/test/java/com/kroger/cache/android/extensions/SnapshotFileCacheBuilderExtensionsTest.kt

@@ -24,12 +24,10 @@
 package com.kroger.cache.android.extensions
 
 import android.content.Context
-import com.google.common.truth.Truth.assertThat
 import com.kroger.cache.SnapshotFileCacheBuilder
 import io.mockk.every
 import io.mockk.mockk
 import io.mockk.verify
-import kotlinx.coroutines.runBlocking
 import kotlinx.serialization.builtins.serializer
 import org.junit.jupiter.api.Test
 import org.junit.jupiter.api.io.TempDir
@@ -40,32 +38,30 @@ internal class SnapshotFileCacheBuilderExtensionsTest {
     private lateinit var tempDir: File
 
     @Test
-    fun whenGenericTypeBuilderUsedThenCacheCreatedSuccessfully() = runBlocking {
+    fun whenGenericTypeBuilderUsedThenCacheCreatedSuccessfully() {
         val context = mockk<Context>()
         every { context.cacheDir } returns tempDir
 
-        val cacheResult = SnapshotFileCacheBuilder.from(
+        SnapshotFileCacheBuilder.from(
             context,
             "com.kroger.cache.android.test",
             { "" },
             { it.orEmpty().encodeToByteArray() },
         ).build()
-        assertThat(cacheResult.isSuccess).isTrue()
         verify(exactly = 1) { context.cacheDir }
     }
 
     @Test
-    fun whenGenericCacheEntryBuilderUsedThenCacheCreatedSuccessfully() = runBlocking {
+    fun whenGenericCacheEntryBuilderUsedThenCacheCreatedSuccessfully() {
         val context = mockk<Context>()
         every { context.cacheDir } returns tempDir
-        val cacheResult = SnapshotFileCacheBuilder.from(
+        SnapshotFileCacheBuilder.from(
             context,
             "com.kroger.cache.android.test",
             String.serializer(),
             String.serializer(),
         ).build()
 
-        assertThat(cacheResult.isSuccess).isTrue()
         verify(exactly = 1) { context.cacheDir }
     }
 }

cache/src/main/java/com/kroger/cache/Cache.kt

@@ -30,42 +30,29 @@ public interface Cache<K, V> {
     /**
      * @return the value corresponding with the given [key], or null if the key is not present or the value is expired.
      */
-    public fun get(key: K): V?
+    public suspend fun get(key: K): V?
 
     /**
      * Associates the given [key] with the given [value].
      * If [key] is already in the [Cache] the value will be overwritten by [value].
      */
-    public fun put(key: K, value: V)
+    public suspend fun put(key: K, value: V)
 
     /**
      * Each pair will be inserted into the cache associating the [Pair.first] element with [Pair.second].
      * If [Pair.first] is already in the [Cache] the value will be overwritten by [Pair.second].
      *
      * @param pairs the key value pairs to insert into the cache.
      */
-    public fun putAll(pairs: Iterable<Pair<K, V>>)
+    public suspend fun putAll(pairs: Iterable<Pair<K, V>>)
 
     /**
      * Removes the entry for [key] from the [Cache].
      */
-    public fun remove(key: K)
+    public suspend fun remove(key: K)
 
     /**
      * Removes all entries from the [Cache].
      */
-    public fun clear()
+    public suspend fun clear()
 }
-
-/**
- * @see [Cache.put]
- */
-public operator fun <K, V> Cache<K, V>.set(key: K, value: V) {
-    put(key, value)
-}
-
-/**
- * @see [Cache.get]
- */
-public operator fun <K, V> Cache<K, V>.get(key: K): V? =
-    get(key)

cache/src/main/java/com/kroger/cache/MemoryCacheManagerBuilder.kt

@@ -33,9 +33,10 @@ import kotlin.time.Duration
 /**
  * Builder for a thread safe [Cache] that internally manages a [MemoryCache][com.kroger.cache.internal.MemoryCache].
  * The cache will periodically persist its data to a [SnapshotPersistentCache] and will enforce the given [CachePolicy].
+ * Once the [Cache] is no longer in use its [coroutineScope] should be cancelled.
  */
 public interface MemoryCacheManagerBuilder<K, V> {
-    public suspend fun build(): Cache<K, V>
+    public fun build(): Cache<K, V>
 
     /**
      * The [CachePolicy] to apply to the [MemoryCache][com.kroger.cache.internal.MemoryCache] and its entries.
@@ -69,21 +70,25 @@ public interface MemoryCacheManagerBuilder<K, V> {
      */
     public fun dispatcher(dispatcher: CoroutineDispatcher): MemoryCacheManagerBuilder<K, V>
 
+    /**
+     * It is important that the provided [coroutineScope] live as long as the
+     * [MemoryCache][com.kroger.cache.internal.MemoryCache] is in use. Once the [coroutineScope]
+     * is cancelled no further changes to the [Cache] will be saved to the [SnapshotPersistentCache].
+     *
+     * @param coroutineScope scope to use when periodically updating the [SnapshotPersistentCache].
+     */
+    public fun coroutineScope(coroutineScope: CoroutineScope): MemoryCacheManagerBuilder<K, V>
+
     public companion object {
         /**
-         * Creates a [MemoryCacheManagerBuilder] using the given [coroutineScope] and [snapshotPersistentCache].
-         * It is important that the provided [coroutineScope] live as long as the
-         * [MemoryCache][com.kroger.cache.internal.MemoryCache] is in use. Once the [coroutineScope]
-         * is cancelled no further changes to the [Cache] will be saved to the [snapshotPersistentCache].
+         * Creates a [MemoryCacheManagerBuilder] using the given [snapshotPersistentCache].
          *
-         * @param coroutineScope scope to use when periodically updating the [snapshotPersistentCache].
          * @param snapshotPersistentCache [SnapshotPersistentCache] where entries are periodically saved
          */
         public fun <K, V> from(
-            coroutineScope: CoroutineScope,
-            snapshotPersistentCache: SnapshotPersistentCache<List<CacheEntry<K, V>>>?,
+            snapshotPersistentCache: SnapshotPersistentCache<List<CacheEntry<K, V>>>? = null,
         ): MemoryCacheManagerBuilder<K, V> =
-            RealMemoryCacheManagerBuilder(coroutineScope, snapshotPersistentCache) {
+            RealMemoryCacheManagerBuilder(snapshotPersistentCache) {
                 System.currentTimeMillis()
             }
     }

cache/src/main/java/com/kroger/cache/SnapshotFileCacheBuilder.kt

@@ -40,7 +40,7 @@ import java.io.File
  * For any single [File] only one [SnapshotPersistentCache] should exist at a time.
  */
 public interface SnapshotFileCacheBuilder<T> {
-    public suspend fun build(): Result<SnapshotPersistentCache<T>>
+    public fun build(): SnapshotPersistentCache<T>
 
     /**
      * The [CoroutineDispatcher] to use when doing [File] I/O.

cache/src/main/java/com/kroger/cache/internal/MemoryCache.kt

@@ -44,23 +44,23 @@ internal class MemoryCache<K, V>(
     constructor(initialCapacity: Int = DEFAULT_INITIAL_CAPACITY) :
         this(initialCapacity, false)
 
-    override fun get(key: K): V? {
+    override suspend fun get(key: K): V? {
         return cacheMap[key]
     }
 
-    override fun put(key: K, value: V) {
+    override suspend fun put(key: K, value: V) {
         cacheMap[key] = value
     }
 
-    override fun putAll(pairs: Iterable<Pair<K, V>>) {
+    override suspend fun putAll(pairs: Iterable<Pair<K, V>>) {
         cacheMap.putAll(pairs)
     }
 
-    override fun remove(key: K) {
+    override suspend fun remove(key: K) {
         cacheMap.remove(key)
     }
 
-    override fun clear() {
+    override suspend fun clear() {
         cacheMap.clear()
     }