You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -14,29 +14,42 @@ The wrapper intends to help us avoid the imperative _try/catch_ syntax, while pr
14
14
* Type-safe differentiation between resolving a value vs. runnning effects.
15
15
* Easy and rich API similar to Java's `Optional`.
16
16
* Full interoperability with `java.util.Optional`.
17
+
* Includes an entirely safe `Either<L, R>` type where only one side can be present at a time
17
18
* Method reference friendly - The API provides methods with overloads that makes it easier to use [method reference](https://docs.oracle.com/javase/tutorial/java/javaOO/methodreferences.html) syntax.
18
19
19
20
## Requirements
20
21
21
-
> The only requirement to use this library is Java 8 or higher.
22
+
As of v3 this library uses new Java features, so `Java 18+` is required. This library moves along with Java and the requirement might increase as new Java versions aare released.
23
+
24
+
> If you need a JDK 8+ compatible version you can use v2 instead. I'll try to maintain v2 as long as possible to provide a backawards compatible version. However, it's my strong belive that Java developers need start moving their codebase to newer Java versions rather than staying on their Java 8-ish confort zone, and open-source libraries has a great impact on this by puting the requirement bars so low, allowing Java updates to be neglated.
25
+
26
+
## Breaking Changes (from v2 to v3)
27
+
28
+
-**⚠️ IMPORTANT:** Due to changes on GitHub policies (and by consequence on Maven), it's no longer allowed to use `com.github` as a valid group ID prefix. To honor that and maintain consistency, **as of v3**, the artifact ID is now `io.github.joselion.maybe`. If you want to use a version **before v3**, you can still find it using the ID `com.github.joselion.maybe`.
29
+
- A `ResolveHandler` can no longer be empty. It either has the resolved value or an error.
30
+
- The method `ResolveHandler#filter` was removed to avoid the posibility of an inconsitent empty handler.
31
+
- The `WrapperException` type was removed. Errors now propagate downstream with the API.
32
+
- The method `EffectHandler#toMaybe` was removed as it didn't make sense for effects.
33
+
- All `*Checked.java` functions were renamed to `Throwing*.java`
34
+
- For example, `FunctionChecked<T, R, E>` was renamed to `ThrowingFunction<T, R, E>`
Maybe is available in [Maven Central](https://mvnrepository.com/artifact/com.github.joselion/maybe). You can checkout the latest version with the badge above.
40
+
Maybe is available in [Maven Central](https://mvnrepository.com/artifact/io.github.joselion/maybe). You can checkout the latest version with the badge above.
28
41
29
42
**Gradle**
30
43
31
44
```gradle
32
-
implementation('com.github.joselion:maybe:x.y.z')
45
+
implementation('io.github.joselion:maybe:x.y.z')
33
46
```
34
47
35
48
**Maven**
36
49
37
50
```xml
38
51
<dependency>
39
-
<groupId>com.github.joselion</groupId>
52
+
<groupId>io.github.joselion</groupId>
40
53
<artifactId>maybe</artifactId>
41
54
<version>x.y.z</version>
42
55
</dependency>
@@ -103,6 +116,46 @@ Maybe.just(path)
103
116
.orElse(err ->...);
104
117
```
105
118
119
+
## The `Either<L, R>` type
120
+
121
+
An awesome extra of `Maybe`, is that it provides a useful [Either<L, R>][either-ref] type which guarantees that the only one of the sides (left `L` or right `R`) is present per instance. That is possible thanks to:
122
+
123
+
1.`Either<L, R>` is a [sealed interface](https://docs.oracle.com/en/java/javase/15/language/sealed-classes-and-interfaces.html). It cannot be implemented by any class nor anonimously instantiated in any way.
124
+
2. There only exist 2 implementations of `Either<L, R>`: `Either.Left` and `Either.Right`. In those implementations, only one field is used to store the instance value.
125
+
3. It's not possible to create an `Either<L, R>` instance of a `null` value.
126
+
127
+
The `Either<L, R>` makes a lot of sense when resolving values from throwing operations. At the end of the day, you can end up with either the resolved value (`Rigth`) or the thrown exception (`Left`). You can convert from a `ResolveHandler<T, E>` to an `Either<E, T>` usong the `ResolveHandler#toEither` terminal operator.
128
+
129
+
To use `Either` on its own, use the factory methods to create an instance and the API to handle/unwrap the value:
.onLeft(fizz -> log.info("Multiple of 7: {}", fizz))
145
+
.onRight(value -> log.info("Value: {}", value))
146
+
.unwrap(
147
+
fizz ->0,
148
+
Function.identity()
149
+
)
150
+
)
151
+
.reduce(0, Integer::sum);
152
+
153
+
log.info("The sum of non-fizz values is: {}", sum);
154
+
}
155
+
```
156
+
157
+
Take a look at the [documentation][either-ref] to see all the methods available in the `Either<L, R>` API.
158
+
106
159
## Optional interoperability
107
160
108
161
The API provides full interoperability with Java's `Optional`. You can use `Maybe.fromOptional(..)` to create an instance from an optional value, or you can use the terminal operator `.toOptional()` to unwrap the value to an optional too. However, there's a change you might want to create a `Maybe<T>` withing the Optional API or another library like [Project Reactor](https://projectreactor.io/), like from `.map(..)` method. To make this esier the API provides overloads to that create partial applications, and when fully applied return the specific handler.
@@ -161,10 +214,10 @@ public Properties parsePropertiesFile(final String filePath) {
161
214
162
215
## API Reference
163
216
164
-
You can find more details of the API in the [latest Javadocs](https://javadoc.io/doc/com.github.joselion/maybe).If you need to check the Javadocs of an older version you can also use the full URL as shown below. Just replace `<x.y.z>` with the version you want to see:
217
+
You can find more details of the API in the [latest Javadocs](https://javadoc.io/doc/io.github.joselion/maybe).If you need to check the Javadocs of an older version you can also use the full URL as shown below. Just replace `<x.y.z>` with the version you want to see:
`Maybe<T>` is a monadic wrapper similar `java.util.Optional`, but with a different intention. By leveraging `Optional<T>` benefits, it provides a functional API that safely allows us to perform operations that may or may not throw checked and unchecked exceptions.
8
+
`Maybe<T>` is a monadic wrapper similar to `java.util.Optional`, but with a different intention. By leveraging `Optional<T>` benefits, it provides a functional API that safely allows us to perform operations that may throw checked and unchecked exceptions.
9
9
10
10
The wrapper intends to help us avoid the imperative _try/catch_ syntax, while promoting safe exception handling and functional programming principles.
11
11
@@ -14,29 +14,42 @@ The wrapper intends to help us avoid the imperative _try/catch_ syntax, while pr
14
14
* Type-safe differentiation between resolving a value vs. runnning effects.
15
15
* Easy and rich API similar to Java's `Optional`.
16
16
* Full interoperability with `java.util.Optional`.
17
+
* Includes an entirely safe `Either<L, R>` type where only one side can be present at a time
17
18
* Method reference friendly - The API provides methods with overloads that makes it easier to use [method reference](https://docs.oracle.com/javase/tutorial/java/javaOO/methodreferences.html) syntax.
18
19
19
20
## Requirements
20
21
21
-
> The only requirement to use this library is Java 8 or higher.
22
+
As of v3 this library uses new Java features, so `Java 18+` is required. This library moves along with Java and the requirement might increase as new Java versions aare released.
23
+
24
+
> If you need a JDK 8+ compatible version you can use v2 instead. I'll try to maintain v2 as long as possible to provide a backawards compatible version. However, it's my strong belive that Java developers need start moving their codebase to newer Java versions rather than staying on their Java 8-ish confort zone, and open-source libraries has a great impact on this by puting the requirement bars so low, allowing Java updates to be neglated.
25
+
26
+
## Breaking Changes (from v2 to v3)
27
+
28
+
-**⚠️ IMPORTANT:** Due to changes on GitHub policies (and by consequence on Maven), it's no longer allowed to use `com.github` as a valid group ID prefix. To honor that and maintain consistency, as of v3, the artifact ID is now `io.github.joselion.maybe`. If you want to use a version before v3, you can still find it using the ID `com.github.joselion.maybe`.
29
+
- A `ResolveHandler` can no longer be empty. It either has the resolved value or an error.
30
+
- The method `ResolveHandler#filter` was removed to avoid the posibility of an inconsitent empty handler.
31
+
- The `WrapperException` type was removed. Errors now propagate downstream with the API.
32
+
- The method `EffectHandler#toMaybe` was removed as it didn't make sense for effects.
33
+
- All `*Checked.java` functions were renamed to `Throwing*.java`
34
+
- For example, `FunctionChecked<T, R, E>` was renamed to `ThrowingFunction<T, R, E>`
Maybe is available in [Maven Central](https://mvnrepository.com/artifact/com.github.joselion/maybe). You can checkout the latest version with the badge above.
40
+
Maybe is available in [Maven Central](https://mvnrepository.com/artifact/io.github.joselion/maybe). You can checkout the latest version with the badge above.
28
41
29
42
**Gradle**
30
43
31
44
```gradle
32
-
implementation('com.github.joselion:maybe:x.y.z')
45
+
implementation('io.github.joselion:maybe:x.y.z')
33
46
```
34
47
35
48
**Maven**
36
49
37
50
```xml
38
51
<dependency>
39
-
<groupId>com.github.joselion</groupId>
52
+
<groupId>io.github.joselion</groupId>
40
53
<artifactId>maybe</artifactId>
41
54
<version>x.y.z</version>
42
55
</dependency>
@@ -103,6 +116,46 @@ Maybe.just(path)
103
116
.orElse(err ->...);
104
117
```
105
118
119
+
## The `Either<L, R>` type
120
+
121
+
An awesome extra of `Maybe`, is that it provides a useful [Either<L, R>][either-ref] type which guarantees that the only one of the sides (left `L` or right `R`) is present per instance. That is possible thanks to:
122
+
123
+
1.`Either<L, R>` is a [sealed interface](https://docs.oracle.com/en/java/javase/15/language/sealed-classes-and-interfaces.html). It cannot be implemented by any class nor anonimously instantiated in any way.
124
+
2. There only exist 2 implementations of `Either<L, R>`: `Either.Left` and `Either.Right`. In those implementations, only one field is used to store the instance value.
125
+
3. It's not possible to create an `Either<L, R>` instance of a `null` value.
126
+
127
+
The `Either<L, R>` makes a lot of sense when resolving values from throwing operations. At the end of the day, you can end up with either the resolved value (`Rigth`) or the thrown exception (`Left`). You can convert from a `ResolveHandler<T, E>` to an `Either<E, T>` usong the `ResolveHandler#toEither` terminal operator.
128
+
129
+
To use `Either` on its own, use the factory methods to create an instance and the API to handle/unwrap the value:
.onLeft(fizz -> log.info("Multiple of 7: {}", fizz))
145
+
.onRight(value -> log.info("Value: {}", value))
146
+
.unwrap(
147
+
fizz ->0,
148
+
Function.identity()
149
+
)
150
+
)
151
+
.reduce(0, Integer::sum);
152
+
153
+
log.info("The sum of non-fizz values is: {}", sum);
154
+
}
155
+
```
156
+
157
+
Take a look at the [documentation][either-ref] to see all the methods available in the `Either<L, R>` API.
158
+
106
159
## Optional interoperability
107
160
108
161
The API provides full interoperability with Java's `Optional`. You can use `Maybe.fromOptional(..)` to create an instance from an optional value, or you can use the terminal operator `.toOptional()` to unwrap the value to an optional too. However, there's a change you might want to create a `Maybe<T>` withing the Optional API or another library like [Project Reactor](https://projectreactor.io/), like from `.map(..)` method. To make this esier the API provides overloads to that create partial applications, and when fully applied return the specific handler.
@@ -161,10 +214,10 @@ public Properties parsePropertiesFile(final String filePath) {
161
214
162
215
## API Reference
163
216
164
-
You can find more details of the API in the [latest Javadocs](https://javadoc.io/doc/com.github.joselion/maybe).If you need to check the Javadocs of an older version you can also use the full URL as shown below. Just replace `<x.y.z>` with the version you want to see:
217
+
You can find more details of the API in the [latest Javadocs](https://javadoc.io/doc/io.github.joselion/maybe).If you need to check the Javadocs of an older version you can also use the full URL as shown below. Just replace `<x.y.z>` with the version you want to see:
0 commit comments