New Object Interface (#1)

Author: AllanHasegawa

.editorconfig

@@ -0,0 +1,9 @@
+[*.{kt,kts}]
+# possible values: number (e.g. 2), "unset" (makes ktlint ignore indentation completely)
+indent_size=4
+# true (recommended) / false
+insert_final_newline=true
+# possible values: number (e.g. 120) (package name, imports & comments are ignored), "off"
+# it's automatically set to 100 on `ktlint --android ...` (per Android Kotlin Style Guide)
+max_line_length=off
+disabled_rules=import-ordering

README.md

@@ -1,6 +1,7 @@
 # Kelm
 
-Kelm eases the pain when dealing with complex app state and asynchronous tasks.
+Kelm simplifies management of complex app states and asynchronous tasks.
+
 Kelm is a Kotlin library based on the [Elm Architecture](https://guide.elm-lang.org/architecture) and [RxJava](http://reactivex.io/).
 
 ## Introduction
@@ -17,31 +18,39 @@ The **Model** can only be updated in the **Update** function. **Messages** are t
 
 **Messages** can be UI events, responses from APIs, or the result of computations.
 
-A good strategy when designing the initial version of a **Model** and **Messages** is to write down every event the UI can generate, and everything it can render.
-
 ### A simple example
 
 Below is a simple Kelm app. Try to read and guess what it does:
 
 ```kotlin
-data class Model(val count: Int)
+object CounterElement : Kelm.Sandbox<Model, Msg>() {
+    sealed class Msg {
+        object MinusClick : Msg()
+        object PlusClick : Msg()
+        object ResetClick : Msg()
+    }
 
-sealed class Msg {
-    object Increment : Msg()
-    object Decrement : Msg()
+    data class Model(val count: Int) {
+        val resetBtEnabled = count > 0
+        val minusBtEnabled = resetBtEnabled
+    }
+
+    fun initModel() = Model(count = 0)
+
+    override fun updateSimple(model: Model, msg: Msg): Model? =
+        when (msg) {
+            is Msg.MinusClick -> model.copy(count = model.count - 1)
+            is Msg.PlusClick -> model.copy(count = model.count + 1)
+            is Msg.ResetClick -> model.copy(count = 0)
+        }
 }
 
 val msgSubj = PublishSubject.create<Msg>()
 
-Kelm.build<Model, Msg, Nothing>(
-    msgObserver = msgSubj,
-    initModel = Model(0)
-) { model, msg -> 
-    when (msg) {
-        is Increment -> Model(model.count + 1)
-        is Decrement -> Model(model.count - 1)
-    }
-}.subscribe { model ->
+CounterElement.start(
+    initModel = CounterElement.initModel(),
+    msgInput = msgSubj
+).subscribe { model ->
     println("The total count is ${model.count}")
 }
 
@@ -51,13 +60,17 @@ msgSubj.onNext(Msg.Decrement)
 ``` 
 
 The above example shows how the main flow of a Kelm app works.
-We first declare our **Model** and our **Messages**, we then build the main **Update** function.
+We first declare a `Kelm.Sandbox` object†, the contract for our **Model** and our **Messages**,
+and how they interact with the **update** function. 
+
+† Your **Sandbox** implementation should be an **object** with no properties.
 
 The **Update** is a *pure function* that takes the current **Model** and a **Message** and returns a new **Model**.
 
-The return of the `Kelm::build` is of type `Observable<Model>`. The **View** (a Android View, for example) can subscribe to this `Observable` and render it when it changes.
+The return of the `Element::start` is of type `Observable<Model>`.
+The **View** (an Android View, for example) can subscribe to this `Observable` and render it when it changes.
 
-See the [Counter Sample](sample-andorid/src/main/java/kelm/sample/CounterSampleActivity.kt) for a working implementation.
+See the [Counter Sample](sample-android/src/main/java/kelm/sample/CounterSampleActivity.kt).
 
 #### Rules for the **Update** function:
 
@@ -68,65 +81,37 @@ See the [Counter Sample](sample-andorid/src/main/java/kelm/sample/CounterSampleA
 
 ### Commands
 
-**Commands** are asynchronous tasks that finish with *one* **Message**.
+**Commands** are asynchronous tasks that finish with *at most one* **Message**.
 This **Message** indicates the result of a task, be it a successful result
 or an error.
 
-Here's an example using commands to fetch data from an API:
+* All side-effects and expensive computations must be done with **Commands**.
 
-```kotlin
-fun fetchFromApi(): Single<Response> = ...
+To work with **Commands** implement an ``Kelm::Element`` instead of a ``Kelm::Sandbox``.
 
-sealed class Model {
-    object Loading : Model()
-    data class LoadedContent(val response: Response) : Model()
-}
+Then create a `cmdToMaybe` function that takes a **Command** and transforms it into a `Maybe<Msg>`.
+This `Maybe<Msg>` is the action of a **Command** and *it should never emit any error in its error channel*.
 
-sealed class Msg {
-    object FetchClick : Msg()
-    data class ContentFetched(val response: Response) : Msg()
-}
+The **Update** function has some special implicit functions like the `runCmd` function. `runCmd` adds the **Command** to be executed.
 
-sealed class Cmd : kelm.Cmd() {
-    object FetchFromApi : Cmd()
-}
+See the [Fox Service Sample](sample-android/src/main/java/kelm/sample/FoxServiceSampleActivity.kt).
 
-val msgSubj = PublishSubject.create<Msg>()
+### Subscriptions
 
-Kelm.build<Model, Msg, Cmd>(
-    msgObserver = msgSubj,
-    initModel = Model.Loading,
-    cmdToSingle = { cmd ->
-        when (cmd) {
-            is Cmd.FetchFromApi ->
-                  fetchFromApi().map { Msg.ContentFetched(it) }
-        }
-    },
-    update = { model, msg ->
-        when (msg) {
-            is FetchClick -> Model.Loading.also {
-                runCmd(Cmd.FetchFromApi)
-            }
-            is ContentFetched -> Model.LoadedContent(msg.response)
-        }
-    }
-)
+```
+TODO
 ```
 
-To work with **Commands** we first declare their type.
-Then we create a `cmdToSingle` function that takes a **Command** and transforms it into a `Single<Msg>`.
-This `Single<Msg>` is the action of a **Command** and *it should never emit any error in its error channel*.
-
-The **Update** function has some special implicit functions like the `runCmd` function. `runCmd` adds the **Command** to be executed.
-
-See the [Fox Service Sample](sample-andorid/src/main/java/kelm/sample/FoxServiceSampleActivity.kt) for a working implementation.
+See the [Clock Sample](sample-android/src/main/java/kelm/sample/ClockSampleActivity.kt).
 
-### Subscriptions
+### Dealing with complex projects
 
 ```
 TODO
 ```
 
+See the [Advanced Sample](sample-android/src/main/java/kelm/sample/signUp).
+
 ### FAQ
 
 ```

build.gradle

@@ -1,7 +1,6 @@
 // Top-level build file where you can add configuration options common to all sub-projects/modules.
 
 buildscript {
-    ext.kotlin_version = '1.3.50'
     repositories {
         google()
         jcenter()
@@ -10,18 +9,18 @@ buildscript {
         }
     }
     dependencies {
-        classpath 'com.android.tools.build:gradle:3.5.0'
-        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
-        classpath 'org.jlleitschuh.gradle:ktlint-gradle:8.0.0'
-        // NOTE: Do not place your application dependencies here; they belong
-        // in the individual module build.gradle files
+        classpath 'com.android.tools.build:gradle:3.5.1'
+        classpath Dep.plugins.kotlin
+        classpath Dep.plugins.ktlint
+        classpath Dep.plugins.gradleVersions
     }
 }
 
 apply plugin: "org.jlleitschuh.gradle.ktlint"
+apply plugin: "com.github.ben-manes.versions"
 
 subprojects {
-    apply plugin: "org.jlleitschuh.gradle.ktlint" // Version should be inherited from parent
+    apply plugin: "org.jlleitschuh.gradle.ktlint"
 
     ktlint {
     }
@@ -36,4 +35,4 @@ allprojects {
 
 task clean(type: Delete) {
     delete rootProject.buildDir
-}
+}

buildSrc/build.gradle.kts

@@ -0,0 +1,7 @@
+plugins {
+    `kotlin-dsl`
+}
+
+repositories {
+    jcenter()
+}

buildSrc/settings.gradle.kts

@@ -0,0 +1,41 @@
+private object Versions {
+    const val kotlin = "1.3.50"
+    const val spek = "2.0.8"
+}
+
+object Dep {
+    val plugins = Plugins
+    val kotlin = Kotlin
+    val android = Android
+
+    object Plugins {
+        const val kotlin = "org.jetbrains.kotlin:kotlin-gradle-plugin:${Versions.kotlin}"
+        const val ktlint = "org.jlleitschuh.gradle:ktlint-gradle:9.0.0"
+        const val gradleVersions = "com.github.ben-manes:gradle-versions-plugin:0.27.0"
+    }
+
+    object Kotlin {
+        private val v = Versions
+
+        const val std = "org.jetbrains.kotlin:kotlin-stdlib:${v.kotlin}"
+        const val kotlinTest = "org.jetbrains.kotlin:kotlin-test:${v.kotlin}"
+        const val reflect = "org.jetbrains.kotlin:kotlin-reflect:${v.kotlin}"
+        const val kotlinAssertions = "io.kotlintest:kotlintest-assertions:3.4.2"
+        const val junit = "junit:junit:4.12"
+        const val rxJava = "io.reactivex.rxjava2:rxjava:2.2.13"
+        const val spekJvm = "org.spekframework.spek2:spek-dsl-jvm:${v.spek}"
+        const val spekRuntime = "org.spekframework.spek2:spek-runner-junit5:${v.spek}"
+    }
+
+    object Android {
+        private val v = Versions
+
+        const val appCompat = "androidx.appcompat:appcompat:1.1.0"
+        const val coreKtx = "androidx.core:core-ktx:1.2.0-beta01"
+        const val lifecycleExt = "androidx.lifecycle:lifecycle-extensions:2.2.0-rc01"
+        const val rxAndroid = "io.reactivex.rxjava2:rxandroid:2.1.1"
+        const val constraintLayout = "androidx.constraintlayout:constraintlayout:2.0.0-beta3"
+        const val picasso = "com.squareup.picasso:picasso:2.71828"
+        const val loadingButton = "br.com.simplepass:loading-button-android:2.1.5"
+    }
+}

buildSrc/src/main/kotlin/dependencies.kt

@@ -7,19 +7,15 @@ repositories {
 }
 
 dependencies {
-    def spek_version = "2.0.5"
-    implementation fileTree(dir: 'libs', include: ['*.jar'])
-    implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
-    implementation "io.reactivex.rxjava2:rxjava:2.2.8"
+    implementation Dep.kotlin.std
+    implementation Dep.kotlin.rxJava
 
-    testImplementation 'junit:junit:4.12'
-    testImplementation "org.jetbrains.kotlin:kotlin-test:$kotlin_version"
-    testImplementation "io.kotlintest:kotlintest-assertions:3.4.0"
-
-    //spek2
-    testImplementation "org.spekframework.spek2:spek-dsl-jvm:$spek_version"
-    testRuntimeOnly "org.spekframework.spek2:spek-runner-junit5:$spek_version"
-    testImplementation "org.jetbrains.kotlin:kotlin-reflect:$kotlin_version"
+    testImplementation Dep.kotlin.junit
+    testImplementation Dep.kotlin.kotlinTest
+    testImplementation Dep.kotlin.kotlinAssertions
+    testImplementation Dep.kotlin.spekJvm
+    testRuntimeOnly Dep.kotlin.spekRuntime
+    testImplementation Dep.kotlin.reflect
 }
 
 test {
@@ -30,6 +26,8 @@ test {
     testLogging {
         events("passed", "skipped", "failed")
     }
+
+    systemProperty 'SPEK_TIMEOUT', 0
 }
 
 group = 'com.github.AllanHasegawa.kelm'

docs/kelm_adv_sample_elements.png

@@ -0,0 +1,16 @@
+package kelm
+
+class CmdFactoryNotImplementedException :
+    RuntimeException("Cmd factory not implemented")
+
+class SubFactoryNotImplementedException :
+    RuntimeException("Subscription factory not implemented")
+
+sealed class ExternalException(message: String, cause: Throwable) :
+    RuntimeException(message, cause)
+
+data class SubscriptionException(val subscription: Any, override val cause: Throwable) :
+    ExternalException("The subscription [$subscription] threw an error", cause)
+
+data class CmdException(val cmd: Any, override val cause: Throwable) :
+    ExternalException("The command [$cmd] threw an error", cause)