ProductPromotion
Logo

Kotlin

made by https://0x3d.site

GitHub - kittinunf/Result: The modelling for success/failure of operations in Kotlin and KMM (Kotlin Multiplatform Mobile)
The modelling for success/failure of operations in Kotlin and KMM (Kotlin Multiplatform Mobile) - kittinunf/Result
Visit Site

GitHub - kittinunf/Result: The modelling for success/failure of operations in Kotlin and KMM (Kotlin Multiplatform Mobile)

GitHub - kittinunf/Result: The modelling for success/failure of operations in Kotlin and KMM (Kotlin Multiplatform Mobile)

Result

Kotlin MavenCentral Run Gradle Codecov

This is a tiny framework for modelling success/failure of operations in Kotlin. In short, it is a model in type of Result<V: Any?, E : Throwable>.

Ideology

Result<V: Any?, E: Throwable> is to provide higher abstraction of operation that can be ended with result either success or failure. Result.Success represents value in case of success, and Result.Failure represents error in case of failure which is upper bounded with Throwable type.

Installation

Gradle

repositories {
    mavenCentral()
}

dependencies {
    // if you are working on JVM or Android only project
    implementation("com.github.kittinunf.result:result-jvm:«version»") //for JVM support
    
    // if you are working in KMM project
    implementation("com.github.kittinunf.result:result:«version»") //for Kotlin Multiplatform support
}

TL;DR

This model is highly inspired by "Railway Oriented Programming" concept.

Result allows one to express series of success/failure operations in Kotlin as;

Result.of<T, Throwable>(doOperation())
      .flatMap { normalizedData(it) }
      .map { createRequestFromData(it) }
      .flatMap { database.updateFromRequest(it) }

Work with Result is easy

//multi-declaration
val (value, error) = result

//get
val value: Int = result.get() // throw exception if error

//terminal operator
//success
result.success {
}

//failure
result.failure {
}

//fold is there, if you want to handle both success and failure
result.fold({ value ->
    //do something with value
}, { err ->
    //do something with err
})

Why

Result is suitable whenever there is a need to represent an operation that has the possibility of failure. Error handling can be cumbersome to work with. Result helps process the operations in a nice, functional way, while maintaining readability to your code.

Let's consider a need to read data from foo, and to perform some further validation

fun process(): String {
    try {
        val foo = File("/path/to/file/foo.txt").readText()
        val isSuccessful = processData(foo)
        if (!isSuccessful) {
            return "Data is corrupted and cannot be processed"
        }
    } catch (e: Throwable) {
        //do something if error
        Logger.log(ERROR, e.message())
    }
}

However, things start getting ugly when we have chain of operations being run sequentially, such as

fun process(): String {
    try {
        val foo = File("/path/to/file/foo.txt").readText()
        val isSuccessful = normalizedData(foo)
        if (!isSuccessful) {
            return "Data cannot be processable"
        }
        val request = createRequestFromData(foo)
        try {
            val result = database.updateFromRequest(request)
            if (!result) {
                return "Record in DB is not found"
            }
        } catch (dbEx: DBThrowable) {
            return "DB error, cannot update"
        }
    } catch (e: Throwable) {
        //do something if error
        Logger.log(ERROR, e.message())
    }
}

Ouch, it looks pretty bleak.

Let's see how Result can help us.

First, we break things down into a small set of model in Result.

  • Read a file
val operation = { File("/path/to/file/foo.txt").readText() }
Result.of { operation() }  // Result<String, FileThrowable>
  • Normalize a data
fun normalizedData(foo): Result<Boolean, NormalizedThrowable> {
    Result.of { foo.normalize() }
}
  • Create a request from data
fun createRequestFromData(foo): Request {
    return createRequest(foo)
}
  • Update DB with Request
fun database.updateFromRequest(request): Result<Boolean, DBThrowable> {
    val transaction = request.transaction
    return Result.of { 
        db.openTransaction {
            val success = db.execute(transaction)
            if (!success) {
                throw DBThrowable("Error")
            }
            return success
        }
    }
}

The whole operation can be chained by the following;

Result.of { doOperation() }
      .flatMap { normalizedData(it) }
      .map { createRequestFromData(it) }
      .flatMap { database.updateFromRequest(it) }

The creates a nice "happy path" of the whole chain, also handle error as appropriate. It looks better and cleaner, right?.

Never Fail Operation

In some case, one wants to model an always successful operation. Result<V: Any?, NoException> is a good idea for that. NoException is to indicate that there is no exception to throw. E.g.

// Add operation can never be failure
fun add(i: Int, j: Int) : Result<Int, NoException>

Nice thing about modelling in this way is to be able to compose it with others "fail-able" operations in Result.

High Order functions

Success

map and flatMap

map transforms Result with given transformation (V) -> U. As a result, we are able to transform V into a new V in the case where Result is Result.Success. When Result is Result.Failure, error is re-wrapped into a new Result.

flatMap is similar to map, however it requires transformation in type of (V) -> Result<U, ...> .

Failure

mapError and flatMapError

mapError ((E) -> E2) and flatMapError ((E) -> Result<E2, ...>) are counterpart of map and flatMap. However, they are operate on Result.Failure. It is quite handy when one needs to do some transformation on given Throwable into a custom type of Throwable that suits ones' need.

More features

Please check out more features in the ResultTest

Railway Oriented Programming

If interested, here are more articles that one might enjoy.

Credit to Scott Wlaschin

Credits

Result is brought to you by contributors.

License

Result is released under the MIT license.

More Resources
to explore the angular.

mail [email protected] to add your project or resources here 🔥.

Related Articles
to learn about angular.

FAQ's
to learn more about Angular JS.

mail [email protected] to add more queries here 🔍.

More Sites
to check out once you're finished browsing here.

0x3d
https://www.0x3d.site/
0x3d is designed for aggregating information.
NodeJS
https://nodejs.0x3d.site/
NodeJS Online Directory
Cross Platform
https://cross-platform.0x3d.site/
Cross Platform Online Directory
Open Source
https://open-source.0x3d.site/
Open Source Online Directory
Analytics
https://analytics.0x3d.site/
Analytics Online Directory
JavaScript
https://javascript.0x3d.site/
JavaScript Online Directory
GoLang
https://golang.0x3d.site/
GoLang Online Directory
Python
https://python.0x3d.site/
Python Online Directory
Swift
https://swift.0x3d.site/
Swift Online Directory
Rust
https://rust.0x3d.site/
Rust Online Directory
Scala
https://scala.0x3d.site/
Scala Online Directory
Ruby
https://ruby.0x3d.site/
Ruby Online Directory
Clojure
https://clojure.0x3d.site/
Clojure Online Directory
Elixir
https://elixir.0x3d.site/
Elixir Online Directory
Elm
https://elm.0x3d.site/
Elm Online Directory
Lua
https://lua.0x3d.site/
Lua Online Directory
C Programming
https://c-programming.0x3d.site/
C Programming Online Directory
C++ Programming
https://cpp-programming.0x3d.site/
C++ Programming Online Directory
R Programming
https://r-programming.0x3d.site/
R Programming Online Directory
Perl
https://perl.0x3d.site/
Perl Online Directory
Java
https://java.0x3d.site/
Java Online Directory
Kotlin
https://kotlin.0x3d.site/
Kotlin Online Directory
PHP
https://php.0x3d.site/
PHP Online Directory
React JS
https://react.0x3d.site/
React JS Online Directory
Angular
https://angular.0x3d.site/
Angular JS Online Directory