https://github.com/favware/java-result
A Java implementation of a Result monad inspired by Rust's Result struct.
https://github.com/favware/java-result
java result
Last synced: 11 months ago
JSON representation
A Java implementation of a Result monad inspired by Rust's Result struct.
- Host: GitHub
- URL: https://github.com/favware/java-result
- Owner: favware
- License: mit
- Created: 2023-03-10T12:09:57.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-11-17T00:29:02.000Z (over 1 year ago)
- Last Synced: 2024-11-17T01:22:04.007Z (over 1 year ago)
- Topics: java, result
- Language: Java
- Homepage: https://favware.github.io/java-result/
- Size: 3.14 MB
- Stars: 1
- Watchers: 1
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: .github/CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE.md
- Code of conduct: .github/CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# Result
**A Java implementation of a Result monad inspired by Rust's Result struct**
[](https://github.com/favware/java-result/blob/main/LICENSE)
[](https://join.favware.tech)
***Important:*** This package is a mirror of https://github.com/jasongoodwin/better-java-monads, however that package is
not maintained any more. This way we can maintain the code ourselves. Furthermore, the dependency as pulled in from
maven-central was also unable to properly show javadoc comments for unknown reason. Big chunks of the following text are
taken straight from the original source code.
---
## About
This library adds a `Result` monad to Java. While `Optional` exists to express nulls in types, there is no way to
express a success/failure of a callable lambda expression. `Result` fills this gap.
The `Result` type is very similar to the `Result` in Scala's standard lib. Some inspiration is also taken from
the `Result` monad in the Rust language, and subsequently from `@sapphire/result`, the TypeScript implementation of the
former.
Lastly, this version of the `Result` monad also addresses all open issues in the original project, as well as including
the
code of all open pull requests.
## Installation
### Maven
```xml
tech.favware
result
1.2.0
```
### Gradle
**With Gradle Groovy**
```groovy
dependencies {
implementation 'tech.favware:result:1.2.0'
}
```
**With Kotlin DSL**
```kotlin
dependencies {
implementation("tech.favware:result:1.2.0")
}
```
## Usage
The `Result` monad was attributed to Twitter and placed into the Scala standard library.
While both Scala and Haskell have a monad Either which has a left and a right type,
a `Result` is specifically of a type `T` on success or an exception on failure.
The `Result` api is meant to be similar to the `Optional` type so has the same functions.
- `get()` returns the held value or throws the thrown exception
- `getUnchecked()` returns the held value or throws the thrown exception wrapped in a `RuntimeException` instance
- `map(x)` maps the success value `x` to a new value and type or otherwise passes the Failure forward.
- `flatMap((x) -> f(x))` maps the success value `x` to a new `Result` of f(x).
- `recover((t) -> x)` will return the success value of the `Result` in the success case or the value `x` in the failure
case.
Exposes the exception.
- `recoverWith((t) -> f(x))` will return the success value of the `Result` in the success case or a new `Result`
of `f(x)` in
the
failure case. Exposes the exception.
- `filter((x) -> isTrue(x))` - If `Success`, returns the same `Success` if the predicate succeeds, otherwise, returns a
`Failure` with type `NoSuchElementException`.
- `onSuccess((x) -> f(x))` execute some code on success - takes a `Consumer` (e.g. requires no return value).
- `onFailure((x) -> f(x))` execute some code on failure - takes a `Consumer` (e.g. requires no return value).
- `raise(x)` -> will throw an exception of type `x` when it happens.
- `orElse(x)` will return the success value of the `Result` in success case or the value `x` in failure case.
- `orElseResult(f)` will return the success value of the `Result` in success case or a new `Result(f)` in the failure
case.
- `orElseThrow(() -> throw new T)` gets result or on failure will throw checked exception of type `T`
- `toOptional()` will return `Optional` of success value of `Result` (if not `null`), otherwise it will return an
empty `Optional`
- `mapErr(e)` maps the failure value `e` to a new error type or otherwise passes the success forward.
- `match((x, y)` Takes the result of the `Result` and applies the first function to the success value or the second
function to the failure value. Transforms the return type to the return type of the applied function.
## Contributors
Please make sure to read the [Contributing Guide][contributing] before making a pull request.
Thank you to all the people who already contributed to Sapphire!
[contributing]: ./.github/CONTRIBUTING.md