Introduce Mavericks core module

docs/_sidebar.md

@@ -3,6 +3,7 @@
 * [**Setting Up Mavericks**](setup.md)
 * [**What's new in Mavericks 2.0**](new-2x.md)
     * [**Upgrading from MvRx 1.x**](new-2x.md#upgrading)
+* [**What's new in Mavericks 3.0**](new-3x.md)
 ---
 * [**Async/Network/Db Operations**](async.md)
 * [**Debug Checks**](debug-checks.md)

docs/new-3x.md

@@ -0,0 +1,80 @@
+# What's new in Mavericks 3.0
+
+### Experimental MavericksRepository
+
+Mavericks 3.0 introduces an experimental module `mvrx-core` with new abstraction `MavericksRepository` designed to provide a base class for any statefull repository implementation that owns and manages its state. This module is pure Kotlin and has no Android dependencies. Primary goal of this module is to provide the same API and behaviour as `MavericksViewModel` in Android modules.
+
+
+### API Changes
+
+Mavericks 3.0 introduces one breaking change: `MavericksViewModelConfig.BlockExecutions` is extracted into  `MavericksBlockExecutions`. In order to migrate, you need to update your code to use `MavericksBlockExecutions` instead of `MavericksViewModelConfig.BlockExecutions`.
+
+### New Functionality
+
+#### `MavericksRepository`
+
+`MavericksRepository` behaves exactly like `MavericksViewModel` except it doesn't have any Android dependencies. Even more, under the hood `MavericksViewModel` uses `MavericksRepository` to manage its state. You can find that `MavericksRepository` and `MavericksViewModel` are very similar in terms of API and behaviour.
+As this is experimental module you have to opt in to use it by `-Xopt-in=com.airbnb.mvrx.InternalMavericksApi` compilation argument.
+
+```kotlin
+data class Forecast(
+    val temperature: Int,
+    val precipitation: Int,
+    val wind: Int,
+)
+
+data class WeatherForecastState(
+    val forecasts: Async<List<Forecast>> = Uninitialized,
+) : MavericksState
+
+interface WeatherApi {
+    suspend fun getForecasts(): List<Forecast>
+}
+
+class WeatherForecastRepository(
+    scope: CoroutineScope,
+    private val api: WeatherApi,
+) : MavericksRepository<WeatherForecastState>(
+    initialState = WeatherForecastState(),
+    coroutineScope = scope,
+    performCorrectnessValidations = BuildConfig.DEBUG,
+) {
+    init {
+        suspend { api.getForecasts() }.execute { copy(forecasts = it) }
+    }
+
+    fun refresh() {
+        suspend { api.getForecasts() }.execute { copy(forecasts = it) }
+    }
+}
+```
+
+#### `MavericksRepositoryConfig` 
+
+In order to construct an instance of `MavericksRepository` you have to provide some configuration parameters, you can do that by:
+
+1. providing instance of `MavericksRepositoryConfig`
+```kotlin
+class WeatherForecastRepository(
+    scope: CoroutineScope,
+    private val api: WeatherApi,
+) : MavericksRepository<WeatherForecastState>(
+    MavericksRepositoryConfig(...)
+```
+
+2. or via constructor arguments
+```kotlin
+class WeatherForecastRepository(
+    scope: CoroutineScope,
+    private val api: WeatherApi,
+) : MavericksRepository<WeatherForecastState>(
+    initialState = WeatherForecastState(),
+    coroutineScope = scope,
+    performCorrectnessValidations = BuildConfig.DEBUG,
+)
+```
+
+**Note:** `performCorrectnessValidations` should be enabled in debug build only as it applies runtime checks to ensure the repository is used correctly.
+To avoid extra overhead this flag should be disabled in production build.
+
+Checkout out  [integrate Mavericks into your app](/debug-checks) or docs for [MavericksRepositoryConfig](https://github.com/airbnb/mavericks/blob/main/mvrx-core/src/main/kotlin/com/airbnb/mvrx/MavericksRepositoryConfig.kt) for more info.

gradle.properties

@@ -1,4 +1,4 @@
-VERSION_NAME=2.7.0
+VERSION_NAME=3.0.0
 GROUP=com.airbnb.android
 POM_DESCRIPTION=Mavericks is an Android application framework that makes product development fast and fun.
 POM_URL=https://github.com/airbnb/mavericks

launcher/src/main/java/com/airbnb/mvrx/launcher/MavericksLauncherMockActivity.kt

@@ -9,8 +9,8 @@ import android.os.Parcelable
 import android.util.Log
 import androidx.core.os.postDelayed
 import androidx.fragment.app.Fragment
+import com.airbnb.mvrx.MavericksBlockExecutions
 import com.airbnb.mvrx.MavericksView
-import com.airbnb.mvrx.MavericksViewModelConfig
 import com.airbnb.mvrx.launcher.utils.toastLong
 import com.airbnb.mvrx.mocking.MockBehavior
 import com.airbnb.mvrx.mocking.MockedView
@@ -190,15 +190,15 @@ class MavericksLauncherMockActivity : MavericksBaseLauncherActivity() {
                 mock.forInitialization || mock.isForProcessRecreation -> MockBehavior(
                     initialStateMocking = MockBehavior.InitialStateMocking.Partial,
                     stateStoreBehavior = MockBehavior.StateStoreBehavior.Normal,
-                    blockExecutions = MavericksViewModelConfig.BlockExecutions.No
+                    blockExecutions = MavericksBlockExecutions.No
                 )
                 // The Fragment is fully mocked out and we prevent initialization code from overriding the mock.
                 // However, our ViewModelEnabler will later toggle executions to be allowed, once initialization is over,
                 // so that the fragment is functional from the state we set it up in.
                 else -> MockBehavior(
                     initialStateMocking = MockBehavior.InitialStateMocking.Full,
                     stateStoreBehavior = MockBehavior.StateStoreBehavior.Scriptable,
-                    blockExecutions = MavericksViewModelConfig.BlockExecutions.Completely
+                    blockExecutions = MavericksBlockExecutions.Completely
                 )
             }
         }

launcher/src/main/java/com/airbnb/mvrx/launcher/ViewModelEnabler.kt

@@ -4,9 +4,9 @@ import android.os.Handler
 import androidx.lifecycle.Lifecycle
 import androidx.lifecycle.LifecycleObserver
 import androidx.lifecycle.OnLifecycleEvent
+import com.airbnb.mvrx.MavericksBlockExecutions
 import com.airbnb.mvrx.MavericksView
 import com.airbnb.mvrx.MavericksViewModel
-import com.airbnb.mvrx.MavericksViewModelConfig
 import com.airbnb.mvrx.mocking.MockBehavior
 import com.airbnb.mvrx.mocking.MockableMavericksViewModelConfig
 import com.airbnb.mvrx.mocking.MockedView
@@ -46,7 +46,7 @@ class ViewModelEnabler(
                     .forEach { viewModel ->
                         MockableMavericksViewModelConfig.access(viewModel).pushBehaviorOverride(
                             MockBehavior(
-                                blockExecutions = MavericksViewModelConfig.BlockExecutions.No,
+                                blockExecutions = MavericksBlockExecutions.No,
                                 stateStoreBehavior = MockBehavior.StateStoreBehavior.Normal
                             )
                         )

mvrx-core/build.gradle

@@ -0,0 +1,29 @@
+import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
+
+plugins {
+    id 'java-library'
+    id 'org.jetbrains.kotlin.jvm'
+}
+
+tasks.withType(KotlinCompile).all {
+    kotlinOptions {
+        freeCompilerArgs += [
+                '-Xopt-in=kotlin.RequiresOptIn',
+                '-Xopt-in=kotlinx.coroutines.ExperimentalCoroutinesApi',
+                '-Xopt-in=com.airbnb.mvrx.InternalMavericksApi',
+                '-Xopt-in=com.airbnb.mvrx.ExperimentalMavericksApi',
+        ]
+    }
+}
+
+java {
+    sourceCompatibility = JavaVersion.VERSION_1_8
+    targetCompatibility = JavaVersion.VERSION_1_8
+}
+
+dependencies {
+    api Libraries.kotlinCoroutines
+
+    testImplementation TestLibraries.junit
+    testImplementation TestLibraries.kotlinCoroutinesTest
+}

mvrx-core/gradle.properties

@@ -0,0 +1,4 @@
+POM_NAME=Mavericks
+POM_ARTIFACT_ID=mavericks-core
+POM_PACKAGING=jar
+GROUP=com.airbnb.android

mvrx/src/main/kotlin/com/airbnb/mvrx/Async.kt → mvrx-core/src/main/java/com/airbnb/mvrx/Async.kt

@@ -52,7 +52,7 @@ data class Success<out T>(private val value: T) : Async<T>(complete = true, shou
      * you could map a network request to just the data you need in the value, but your base layers could
      * keep metadata about the request, like timing, for logging.
      *
-     * @see MavericksViewModel.execute
+     * @see MavericksRepository.execute
      * @see Async.setMetadata
      * @see Async.getMetadata
      */

mvrx/src/main/kotlin/com/airbnb/mvrx/CoroutinesStateStore.kt → mvrx-core/src/main/java/com/airbnb/mvrx/CoroutinesStateStore.kt

@@ -124,6 +124,6 @@ class CoroutinesStateStore<S : MavericksState>(
          * The internally allocated buffer is replay + extraBufferCapacity but always allocates 2^n space.
          * We use replay=1 so buffer = 64-1.
          */
-        internal const val SubscriberBufferSize = 63
+        @InternalMavericksApi const val SubscriberBufferSize = 63
     }
 }

mvrx-core/src/main/java/com/airbnb/mvrx/ExperimentalMavericksApi.kt

@@ -0,0 +1,9 @@
+package com.airbnb.mvrx
+
+/**
+ * Marks declarations that are still experimental in Mavericks API.
+ * Marked declarations are subject to change their semantics or behaviours, that not backward compatible.
+ */
+@Retention(value = AnnotationRetention.BINARY)
+@RequiresOptIn(level = RequiresOptIn.Level.WARNING)
+annotation class ExperimentalMavericksApi

mvrx-core/src/main/java/com/airbnb/mvrx/MavericksBlockExecutions.kt

@@ -0,0 +1,19 @@
+package com.airbnb.mvrx
+
+/**
+ * Defines whether a [MavericksRepository.execute] invocation should not be run.
+ */
+enum class MavericksBlockExecutions {
+    /** Run the execute block normally. */
+    No,
+
+    /** Block the execute call from having an impact. */
+    Completely,
+
+    /**
+     * Block the execute call from having an impact from values returned by the object
+     * being executed, but perform one state callback to set the Async property to loading
+     * as if the call is actually happening.
+     */
+    WithLoading
+}

mvrx/src/main/kotlin/com/airbnb/mvrx/MavericksMutabilityHelper.kt → mvrx-core/src/main/java/com/airbnb/mvrx/MavericksMutabilityHelper.kt

@@ -1,10 +1,5 @@
 package com.airbnb.mvrx
 
-import android.os.Build
-import android.util.SparseArray
-import androidx.collection.ArrayMap
-import androidx.collection.LongSparseArray
-import androidx.collection.SparseArrayCompat
 import java.lang.reflect.Field
 import java.lang.reflect.Modifier
 import java.lang.reflect.ParameterizedType
@@ -30,6 +25,16 @@ fun assertMavericksDataClassImmutability(
 ) {
     require(kClass.java.isData) { "Mavericks state must be a data class! - ${kClass.simpleName}" }
 
+    val disallowedFieldCollectionTypes = listOfNotNull(
+        ArrayList::class.java,
+        HashMap::class.java,
+        runCatching { Class.forName("android.util.SparseArray") }.getOrNull(),
+        runCatching { Class.forName("androidx.collection.LongSparseArray") }.getOrNull(),
+        runCatching { Class.forName("androidx.collection.SparseArrayCompat") }.getOrNull(),
+        runCatching { Class.forName("androidx.collection.ArrayMap") }.getOrNull(),
+        runCatching { Class.forName("android.util.ArrayMap") }.getOrNull(),
+    )
+
     fun Field.isSubtype(vararg classes: KClass<*>): Boolean {
         return classes.any { klass ->
             return when (val returnType = this.type) {
@@ -43,16 +48,12 @@ fun assertMavericksDataClassImmutability(
         // During tests, jacoco can add a transient field called jacocoData.
         .filterNot { Modifier.isTransient(it.modifiers) }
         .forEach { prop ->
+            val disallowedFieldCollectionType = disallowedFieldCollectionTypes.firstOrNull { clazz -> prop.isSubtype(clazz.kotlin) }
             when {
                 !Modifier.isFinal(prop.modifiers) -> "State property ${prop.name} must be a val, not a var."
-                prop.isSubtype(ArrayList::class) -> "You cannot use ArrayList for ${prop.name}.\n$IMMUTABLE_LIST_MESSAGE"
-                prop.isSubtype(SparseArray::class) -> "You cannot use SparseArray for ${prop.name}.\n$IMMUTABLE_LIST_MESSAGE"
-                prop.isSubtype(LongSparseArray::class) -> "You cannot use LongSparseArray for ${prop.name}.\n$IMMUTABLE_LIST_MESSAGE"
-                prop.isSubtype(SparseArrayCompat::class) -> "You cannot use SparseArrayCompat for ${prop.name}.\n$IMMUTABLE_LIST_MESSAGE"
-                prop.isSubtype(ArrayMap::class) -> "You cannot use ArrayMap for ${prop.name}.\n$IMMUTABLE_MAP_MESSAGE"
-                Build.VERSION.SDK_INT >= Build.VERSION_CODES.KITKAT &&
-                    prop.isSubtype(android.util.ArrayMap::class) -> "You cannot use ArrayMap for ${prop.name}.\n$IMMUTABLE_MAP_MESSAGE"
-                prop.isSubtype(HashMap::class) -> "You cannot use HashMap for ${prop.name}.\n$IMMUTABLE_MAP_MESSAGE"
+                disallowedFieldCollectionType != null -> {
+                    "You cannot use ${disallowedFieldCollectionType.simpleName} for ${prop.name}.\n$IMMUTABLE_LIST_MESSAGE"
+                }
                 !allowFunctions && prop.isSubtype(Function::class, KCallable::class) -> {
                     "You cannot use functions inside Mavericks state. Only pure data should be represented: ${prop.name}"
                 }