https://github.com/a-sit-plus/kmmresult
Wrapper of kotlin.Result with KMM goodness
https://github.com/a-sit-plus/kmmresult
ios js jvm kmm kotlin kotlin-multiplatform multiplatform swift wasm
Last synced: 5 months ago
JSON representation
Wrapper of kotlin.Result with KMM goodness
- Host: GitHub
- URL: https://github.com/a-sit-plus/kmmresult
- Owner: a-sit-plus
- License: apache-2.0
- Created: 2022-11-17T07:38:29.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-10-16T14:17:11.000Z (7 months ago)
- Last Synced: 2024-10-18T23:38:30.657Z (6 months ago)
- Topics: ios, js, jvm, kmm, kotlin, kotlin-multiplatform, multiplatform, swift, wasm
- Language: Kotlin
- Homepage: https://a-sit-plus.github.io/KmmResult/
- Size: 697 KB
- Stars: 8
- Watchers: 2
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# Swift-Friendly Kotlin Multiplatform Result Class
[](http://www.apache.org/licenses/LICENSE-2.0)
[](https://a-sit-plus.github.io)
[](http://kotlinlang.org)
[](http://kotlinlang.org)
[](https://mvnrepository.com/artifact/at.asitplus/kmmresult/)
Wrapper for `kotlin.Result` with KMM goodness, s.t. it becomes possible to expose a result class to
public APIs interfacing with platform-specific code. For Kotlin/Native (read: iOS), this requires a `Result` equivalent, which
is *not* a value class (a sealed `Either` type also does not interop well with Swift).
`KmmResult` comes to the rescue! → [Full documentation](https://a-sit-plus.github.io/KmmResult/).
## Using in your Projects
This library is available at maven central.
### Gradle
```kotlin
dependencies {
api("at.asitplus:kmmresult:$version") //This library was designed to play well with multiplatform APIs
} //and is therefore intended to be exposed through your public API
```
## Quick Start
Creation of `Success` and `Failure` objects is provided through a companion:
```kotlin
var intResult = KmmResult.success(3)
intResult = KmmResult.failure (NotImplementedError("Not Implemented"))
```
Convenience functions:
- `map()` transforms success types while passing through errors
- `mapFailure` transforms error types while passing through success cases
- the more generic `fold()` is available for conveniently operating on both success and failure branches
- `KmmResult` sports `unwrap()` to conveniently map it to the `kotlin.Result` equivalent
- `Result.wrap()` extension function goes the opposite way
- `mapCatching()` does what you'd expect
- `wrapping()` allows for wrapping the failure branch's exception unless it is of the specified type
Refer to the [full documentation](https://a-sit-plus.github.io/kmmresult/) for more info.
### Java
Works from the JVM as expected:
```java
KmmResult demonstrate() {
if (new Random().nextBoolean())
return KmmResult.failure(new NotImplementedError("Not Implemented"));
else
return KmmResult.success(true);
}
```
### Swift
Use the initializers:
```swift
func funWithKotlin() -> KmmResult {
if 2 != 3 {
return KmmResult(failure: KotlinThrowable(message: "error!"))
} else {
return KmmResult(value: "works!")
}
}
```
## Non-Fatal-Only `catching`
KmmResult comes with `catching`. This is a non-fatal-only-catching version of stdlib's `runCatching`, directly returning a `KmmResult`.
It re-throws any fatal exceptions, such as `OutOfMemoryError`. The underlying logic is borrowed from [Arrow's](https://arrow-kt.io)'s
[`nonFatalOrThrow`](https://apidocs.arrow-kt.io/arrow-core/arrow.core/non-fatal-or-throw.html).
The only downside of `catching` is that it incurs instantiation overhead, because it creates a `KmmResult` instance.
Internally, though, only the behaviour is important, not Swift interop. Hence, you don't care for a `KmmResult` and you
certainly don't care for the cost of instantiating an object. Here, the `Result.nonFatalOrThrow()` extension shipped with KmmResult
comes to the rescue. It does exactly what the name suggest: It re-throws any fatal exception and leaves the `Result` object
untouched otherwise. As a convenience shorthand, there's `catchingUnwrapped` which directly returns an stdlib `Result`.
Happy folding!
## Contributing
External contributions are greatly appreciated!
Just be sure to observe the contribution guidelines (see [CONTRIBUTING.md](CONTRIBUTING.md)).
---
The Apache License does not apply to the logos, (including the A-SIT logo) and the project/module name(s), as these are the sole property of
A-SIT/A-SIT Plus GmbH and may not be used in derivative works without explicit permission!