Update README
This commit is contained in:
Michael Bull
parent
981fbe2812
commit
fb3ef3dc66
182
README.md
182
README.md
@ -35,19 +35,32 @@ dependencies {
|
||||
|
||||
## Introduction
|
||||
|
||||
The [`Result`][result] monad has two subtypes, [`Ok<V>`][result-ok]
|
||||
representing success and containing a `value`, and [`Err<E>`][result-err],
|
||||
representing failure and containing an `error`.
|
||||
In functional programming, the result [`Result`][result] type is a monadic type
|
||||
holding a returned [value][result-value] or an [error][result-error].
|
||||
|
||||
Mappings are available on the [wiki][wiki] to assist those with experience
|
||||
using the `Result` type in other languages:
|
||||
To indicate an operation that succeeded, return an [`Ok(value)`][result-Ok]
|
||||
with the successful `value`. If it failed, return an [`Err(error)`][result-Err]
|
||||
with the `error` that caused the failure.
|
||||
|
||||
- [Elm](https://github.com/michaelbull/kotlin-result/wiki/Elm)
|
||||
- [Haskell](https://github.com/michaelbull/kotlin-result/wiki/Haskell)
|
||||
- [Rust](https://github.com/michaelbull/kotlin-result/wiki/Rust)
|
||||
- [Scala](https://github.com/michaelbull/kotlin-result/wiki/Scala)
|
||||
This helps to define a clear happy/unhappy path of execution that is commonly
|
||||
referred to as [Railway Oriented Programming][rop], whereby the happy and
|
||||
unhappy paths are represented as separate railways.
|
||||
|
||||
## Read More
|
||||
### Overhead
|
||||
|
||||
The `Result` type is modelled as an
|
||||
[inline value class][kotlin-inline-classes]. This achieves zero object
|
||||
allocations on the happy path.
|
||||
|
||||
A full breakdown, with example output Java code, is available in the
|
||||
[Overhead][wiki-Overhead] design doc.
|
||||
|
||||
### Multiplatform Support
|
||||
|
||||
`kotlin-result` targets all three tiers outlined by the
|
||||
[Kotlin/Native target support][kotlin-native-target-support]
|
||||
|
||||
### Read More
|
||||
|
||||
Below is a collection of videos & articles authored on the subject of this
|
||||
library. Feel free to open a pull request on [GitHub][github] if you would like
|
||||
@ -60,11 +73,18 @@ to include yours.
|
||||
- [[JP] KotlinでResult型使うならkotlin-resultを使おう](https://note.com/yasukotelin/n/n6d9e352c344c)
|
||||
- [[JP] kotlinのコードにReturn Resultを組み込む](https://nnao45.hatenadiary.com/entry/2019/11/30/224820)
|
||||
|
||||
Mappings are available on the [wiki][wiki] to assist those with experience
|
||||
using the `Result` type in other languages:
|
||||
|
||||
- [Elm](https://github.com/michaelbull/kotlin-result/wiki/Elm)
|
||||
- [Haskell](https://github.com/michaelbull/kotlin-result/wiki/Haskell)
|
||||
- [Rust](https://github.com/michaelbull/kotlin-result/wiki/Rust)
|
||||
- [Scala](https://github.com/michaelbull/kotlin-result/wiki/Scala)
|
||||
|
||||
## Getting Started
|
||||
|
||||
The idiomatic approach to modelling operations that may fail in Railway
|
||||
Oriented Programming is to avoid throwing an exception and instead make the
|
||||
return type of your function a `Result`.
|
||||
Below is a simple example of how you may use the `Result` type to model a
|
||||
function that may fail.
|
||||
|
||||
```kotlin
|
||||
fun checkPrivileges(user: User, command: Command): Result<Command, CommandError> {
|
||||
@ -76,10 +96,9 @@ fun checkPrivileges(user: User, command: Command): Result<Command, CommandError>
|
||||
}
|
||||
```
|
||||
|
||||
To incorporate the `Result` type into an existing codebase that throws
|
||||
exceptions, you can wrap functions that may `throw` with
|
||||
[`runCatching`][result-runCatching]. This will execute the block of code and
|
||||
`catch` any `Throwable`, returning a `Result<T, Throwable>`.
|
||||
When interacting with code outside your control that may throw exceptions, wrap
|
||||
the call with [`runCatching`][result-runCatching] to capture its execution as a
|
||||
`Result<T, Throwable>`:
|
||||
|
||||
```kotlin
|
||||
val result: Result<Customer, Throwable> = runCatching {
|
||||
@ -100,8 +119,7 @@ val result: Result<Customer, String> = customers
|
||||
|
||||
Both success and failure results can be transformed within a stage of the
|
||||
railway track. The example below demonstrates how to transform an internal
|
||||
program error (`UnlockError`) into an exposed client error
|
||||
(`IncorrectPassword`).
|
||||
program error `UnlockError` into the exposed client error `IncorrectPassword`.
|
||||
|
||||
```kotlin
|
||||
val result: Result<Treasure, UnlockResponse> =
|
||||
@ -130,21 +148,22 @@ tokenize(command.toLowerCase())
|
||||
|
||||
### Binding (Monad Comprehension)
|
||||
|
||||
The `binding` keyword allows multiple calls that each return a `Result` to be
|
||||
chained imperatively. When inside a `binding` block, the `.bind()` function is
|
||||
accessible on any `Result`. Each call to `bind` will attempt to unwrap the
|
||||
`Result` and store its value, returning early if any `Result` is an `Err`.
|
||||
The [`binding`][result-binding] function allows multiple calls that each return
|
||||
a `Result` to be chained imperatively. When inside a `binding` block, the
|
||||
`bind()` function is accessible on any `Result`. Each call to `bind` will
|
||||
attempt to unwrap the `Result` and store its value, returning early if any
|
||||
`Result` is an error.
|
||||
|
||||
In the example below, should `functionX()` return an `Err`, then execution will
|
||||
skip both `functionY()` and `functionZ()`, instead storing the `Err` from
|
||||
In the example below, should `functionX()` return an error, then execution will
|
||||
skip both `functionY()` and `functionZ()`, instead storing the error from
|
||||
`functionX` in the variable named `sum`.
|
||||
|
||||
```kotlin
|
||||
fun functionX(): Result<Int, DomainError> { ... }
|
||||
fun functionY(): Result<Int, DomainError> { ... }
|
||||
fun functionZ(): Result<Int, DomainError> { ... }
|
||||
fun functionX(): Result<Int, SumError> { ... }
|
||||
fun functionY(): Result<Int, SumError> { ... }
|
||||
fun functionZ(): Result<Int, SumError> { ... }
|
||||
|
||||
val sum: Result<Int, DomainError> = binding {
|
||||
val sum: Result<Int, SumError> = binding {
|
||||
val x = functionX().bind()
|
||||
val y = functionY().bind()
|
||||
val z = functionZ().bind()
|
||||
@ -154,18 +173,18 @@ val sum: Result<Int, DomainError> = binding {
|
||||
println("The sum is $sum") // prints "The sum is Ok(100)"
|
||||
```
|
||||
|
||||
The `binding` keyword primarily draws inspiration from
|
||||
The `binding` function primarily draws inspiration from
|
||||
[Bow's `binding` function][bow-bindings], however below is a list of other
|
||||
resources on the topic of monad comprehensions.
|
||||
|
||||
- [Monad comprehensions - Arrow (Kotlin)][arrow-monad-comprehension]
|
||||
- [Monad comprehensions - Bow (Swift)][bow-monad-comprehension]
|
||||
- [For comprehensions - Scala][scala-for-comprehension]
|
||||
- [Monad comprehensions - Arrow (Kotlin)](https://arrow-kt.io/docs/0.10/patterns/monad_comprehensions/)
|
||||
- [Monad comprehensions - Bow (Swift)](https://bow-swift.io/docs/patterns/monad-comprehensions)
|
||||
- [For comprehensions - Scala](https://docs.scala-lang.org/tour/for-comprehensions.html)
|
||||
|
||||
#### Coroutine Support
|
||||
#### Coroutine Binding Support
|
||||
|
||||
Use of suspending functions within a `binding` block requires an additional
|
||||
dependency:
|
||||
Use of suspending functions within a `coroutineBinding` block requires an
|
||||
additional dependency:
|
||||
|
||||
```kotlin
|
||||
dependencies {
|
||||
@ -174,9 +193,12 @@ dependencies {
|
||||
}
|
||||
```
|
||||
|
||||
The coroutine implementation of `binding` has been designed so that the first
|
||||
call to `bind()` that fails will cancel all child coroutines within the current
|
||||
coroutine scope.
|
||||
The [`coroutineBinding`][result-coroutineBinding] function runs inside a
|
||||
[`coroutineScope`][kotlin-coroutineScope], facilitating _concurrent
|
||||
decomposition of work_.
|
||||
|
||||
When any call to `bind()` inside the block fails, the scope fails, cancelling
|
||||
all other children.
|
||||
|
||||
The example below demonstrates a computationally expensive function that takes
|
||||
five milliseconds to compute being eagerly cancelled as soon as a smaller
|
||||
@ -187,7 +209,7 @@ suspend fun failsIn5ms(): Result<Int, DomainErrorA> { ... }
|
||||
suspend fun failsIn1ms(): Result<Int, DomainErrorB> { ... }
|
||||
|
||||
runBlocking {
|
||||
val result: Result<Int, BindingError> = binding {
|
||||
val result: Result<Int, BindingError> = coroutineBinding { // this creates a new CoroutineScope
|
||||
val x = async { failsIn5ms().bind() }
|
||||
val y = async { failsIn1ms().bind() }
|
||||
x.await() + y.await()
|
||||
@ -207,20 +229,15 @@ Result monad is present, including:
|
||||
- [Rust](https://doc.rust-lang.org/std/result/)
|
||||
- [Scala](http://www.scala-lang.org/api/2.12.4/scala/util/Either.html)
|
||||
|
||||
It also iterates on other Result libraries written in Kotlin, namely:
|
||||
|
||||
- [danneu/kotlin-result](https://github.com/danneu/kotlin-result)
|
||||
- [kittinunf/Result](https://github.com/kittinunf/Result)
|
||||
- [npryce/result4k](https://github.com/npryce/result4k)
|
||||
|
||||
Improvements on the existing solutions include:
|
||||
Improvements on existing solutions such the stdlib include:
|
||||
|
||||
- Reduced runtime overhead with zero object allocations on the happy path
|
||||
- Feature parity with Result types from other languages including Elm, Haskell,
|
||||
& Rust
|
||||
- Lax constraints on `value`/`error` nullability
|
||||
- Lax constraints on the `error` type's inheritance (does not inherit from
|
||||
`Exception`)
|
||||
- Top level `Ok` and `Err` classes avoids qualifying usages with
|
||||
- Top level `Ok` and `Err` functions avoids qualifying usages with
|
||||
`Result.Ok`/`Result.Err` respectively
|
||||
- Higher-order functions marked with the `inline` keyword for reduced runtime
|
||||
overhead
|
||||
@ -239,52 +256,10 @@ in a real world scenario.
|
||||
It hosts a [ktor][ktor] server on port 9000 with a `/customers` endpoint. The
|
||||
endpoint responds to both `GET` and `POST` requests with a provided `id`, e.g.
|
||||
`/customers/100`. Upserting a customer id of 42 is hardcoded to throw an
|
||||
[`SQLException`][customer-42] to demonstrate how the `Result` type can [map
|
||||
internal program errors][update-customer-error] to more appropriate
|
||||
[`SQLException`][customer-42] to demonstrate how the `Result` type can
|
||||
[map internal program errors][update-customer-error] to more appropriate
|
||||
user-facing errors.
|
||||
|
||||
### Payloads
|
||||
|
||||
#### Fetch customer information
|
||||
|
||||
```
|
||||
$ curl -i -X GET 'http://localhost:9000/customers/1'
|
||||
```
|
||||
|
||||
```
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json; charset=UTF-8
|
||||
Content-Length: 84
|
||||
|
||||
{
|
||||
"firstName": "Michael",
|
||||
"lastName": "Bull",
|
||||
"email": "michael@example.com"
|
||||
}
|
||||
```
|
||||
|
||||
#### Add new customer
|
||||
|
||||
```
|
||||
$ curl -i -X POST \
|
||||
-H "Content-Type:application/json" \
|
||||
-d \
|
||||
'{
|
||||
"firstName": "Your",
|
||||
"lastName": "Name",
|
||||
"email": "email@example.com"
|
||||
}' \
|
||||
'http://localhost:9000/customers/200'
|
||||
```
|
||||
|
||||
```
|
||||
HTTP/1.1 201 Created
|
||||
Content-Type: text/plain; charset=UTF-8
|
||||
Content-Length: 16
|
||||
|
||||
Customer created
|
||||
```
|
||||
|
||||
## Contributing
|
||||
|
||||
Bug reports and pull requests are welcome on [GitHub][github].
|
||||
@ -295,22 +270,27 @@ This project is available under the terms of the ISC license. See the
|
||||
[`LICENSE`](LICENSE) file for the copyright information and licensing terms.
|
||||
|
||||
[result]: https://github.com/michaelbull/kotlin-result/blob/master/kotlin-result/src/commonMain/kotlin/com/github/michaelbull/result/Result.kt#L10
|
||||
[result-ok]: https://github.com/michaelbull/kotlin-result/blob/master/kotlin-result/src/commonMain/kotlin/com/github/michaelbull/result/Result.kt#L35
|
||||
[result-err]: https://github.com/michaelbull/kotlin-result/blob/master/kotlin-result/src/commonMain/kotlin/com/github/michaelbull/result/Result.kt#L58
|
||||
[result-runCatching]: https://github.com/michaelbull/kotlin-result/blob/master/kotlin-result/src/commonMain/kotlin/com/github/michaelbull/result/Factory.kt#L11
|
||||
[result-value]: https://github.com/michaelbull/kotlin-result/blob/master/kotlin-result/src/commonMain/kotlin/com/github/michaelbull/result/Result.kt#L55
|
||||
[result-error]: https://github.com/michaelbull/kotlin-result/blob/master/kotlin-result/src/commonMain/kotlin/com/github/michaelbull/result/Result.kt#L59
|
||||
[result-Ok]: https://github.com/michaelbull/kotlin-result/blob/master/kotlin-result/src/commonMain/kotlin/com/github/michaelbull/result/Result.kt#L9
|
||||
[result-Err]: https://github.com/michaelbull/kotlin-result/blob/master/kotlin-result/src/commonMain/kotlin/com/github/michaelbull/result/Result.kt#L17
|
||||
[kotlin-inline-classes]: https://kotlinlang.org/docs/inline-classes.html
|
||||
[wiki-Overhead]: https://github.com/michaelbull/kotlin-result/wiki/Overhead
|
||||
[rop]: https://fsharpforfunandprofit.com/rop/
|
||||
[kotlin-native-target-support]: https://kotlinlang.org/docs/native-target-support.html
|
||||
[github]: https://github.com/michaelbull/kotlin-result
|
||||
[wiki]: https://github.com/michaelbull/kotlin-result/wiki
|
||||
[result-runCatching]: https://github.com/michaelbull/kotlin-result/blob/master/kotlin-result/src/commonMain/kotlin/com/github/michaelbull/result/Factory.kt#L11
|
||||
[result-binding]: https://github.com/michaelbull/kotlin-result/blob/master/kotlin-result/src/commonMain/kotlin/com/github/michaelbull/result/Binding.kt#L28
|
||||
[bow-bindings]: https://bow-swift.io/docs/patterns/monad-comprehensions/#bindings
|
||||
[result-coroutineBinding]: https://github.com/michaelbull/kotlin-result/blob/master/kotlin-result-coroutines/src/commonMain/kotlin/com/github/michaelbull/result/coroutines/CoroutineBinding.kt#L42
|
||||
[kotlin-coroutineScope]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/coroutine-scope.html
|
||||
[unit-tests]: https://github.com/michaelbull/kotlin-result/tree/master/kotlin-result/src/commonTest/kotlin/com/github/michaelbull/result
|
||||
[example]: https://github.com/michaelbull/kotlin-result/tree/master/example/src/main/kotlin/com/github/michaelbull/result/example
|
||||
[swalschin-example]: https://github.com/swlaschin/Railway-Oriented-Programming-Example
|
||||
[ktor]: http://ktor.io/
|
||||
[customer-42]: https://github.com/michaelbull/kotlin-result/blob/master/example/src/main/kotlin/com/github/michaelbull/result/example/repository/InMemoryCustomerRepository.kt#L38
|
||||
[update-customer-error]: https://github.com/michaelbull/kotlin-result/blob/master/example/src/main/kotlin/com/github/michaelbull/result/example/service/CustomerService.kt#L50
|
||||
[github]: https://github.com/michaelbull/kotlin-result
|
||||
[bow-bindings]: https://bow-swift.io/docs/patterns/monad-comprehensions/#bindings
|
||||
[bow-monad-comprehension]: https://bow-swift.io/docs/patterns/monad-comprehensions
|
||||
[scala-for-comprehension]: https://docs.scala-lang.org/tour/for-comprehensions.html
|
||||
[arrow-monad-comprehension]: https://arrow-kt.io/docs/0.10/patterns/monad_comprehensions/
|
||||
[either-syntax]: https://arrow-kt.io/docs/0.10/apidocs/arrow-core-data/arrow.core/-either/#syntax
|
||||
|
||||
[badge-android]: http://img.shields.io/badge/-android-6EDB8D.svg?style=flat
|
||||
[badge-android-native]: http://img.shields.io/badge/support-[AndroidNative]-6EDB8D.svg?style=flat
|
||||
|
||||
Loading…
Reference in New Issue
Block a user