[PROPOSAL] Either API deprecation, and preparation for 2.x.x

[nomisRev]

This PR proposes a smaller API surface for Either without compromising any of its functionality, or feature set.
The goal of these changes is to offer APIs that are more powerful, and more idiomatic to use in Kotlin. Following the signatures and naming of some other well-know APIs from Kotlin Std, or KotlinX Coroutines

The PR reduces the API surface from 70 functions, to 16. Which means the learning curve would be drastically reduced, and learning to work with Either will be significantly simpler.

The list below describes the changes found in this PR for simpler reviewing. All community feedback is welcome, if you're (heavily) using one of these APIs then please comment your use-cases below. Some other APIs are still up for discussion, and they're marked with an "// TODO open-question" comment in the PR. Those APIs are currently not up for deprecation, but might be considered for deprecation in the future.

Either (API Size 70 -> 16)

(Bi)Functor / Applicative / Monad (API Size 15 -> 5)

Keep

map: transform right value
onRight: peek right value
flatMap: transform right value with Either + flatten
flatten: flatten nested eithers.
widen: conveniently change the generic parameters to a super class type.
​

Remove

replicate -> replace with map { List(n) { it } }
exists -> fold({ false }, predicate) // map(predicate).getOrElse { false }
all -> fold({ true }, predicate) // map(predicate).getOrElse { true }
void -> Use map { }
findOrNull => Kotlin nullable syntax: orNull()?.takeIf(predicate)
filterOrElse => Use DSL + ensure, flatMap + if-else
filterOrOther => Use DSL + ensure, flatMap + if-else
ensure => Use DSL + ensure, flatMap + if-else
contains => fold({ false }) { it == elem }
bimap -> map . recover or bind + recover, or recover inside DSL, ...
widenLeft -> widen covers both left, and right generic parameter.
​​tap -> onRight, to be more in line with Kotlin Std

Replaced

zip -> Replaced with Validated behavior, original zip will be inline either + bind

Applicative/MonadError (API Size 9 -> 4)

New

recover: DSL powered version of handleErrorWith signature
catch: DSL powered version of handleErrorWith specific for working with Throwable
​

Keep

mapLeft: map error
onLeft: peek left value
getOrElse: extract & transform error value to success type
​

Remove

combineK -> recover { other.bind() }
handleErrorWith -> recover { transform(it).bind() }
handleError -> recover { transform(it) }
redeem -> map(transformValue).recover { transformError(it) }
redeemWith -> fold(transformError, transformValue)
getOrHandle -> duplicate: use getOrElse
tapLeft -> onLeft, to be more in line with Kotlin Std
​

Foldable / (Bi)Traverse (API Size 27 -> 2)

Keep

fold -> Alternative to when
merge -> E == A, extract value.
​

Remove

foldLeft -> replace with fold
foldMap -> replace with fold
bifoldLeft -> replace with fold
bifoldMap -> replace with fold
​

• All of the traverse methods can be replaced by a simple fold, or even simpler by orNull, getOrElse in a bunch of cases.
  ​
  sequence
  sequenceOption
  sequence
  sequenceNullable
  sequence
  sequenceValidated
  sequence
  bisequence
  bisequenceOption
  bisequenceNullable
  bisequenceValidated
  traverse
  traverse
  traverseOption
  traverseNullable
  traverse
  traverseValidated
  bitraverse
  bitraverseOption
  bitraverseNullable
  bitraverseValidated
  ​

Utilities (19 -> 5)

Keep

swap -> Flip type arguments
getOrNull: extract value, or return null
getOrNone: extract value, or return None

isRight() -> Add smart-contracts, alternative to when
isLeft() -> Add smart-contracts, altenative to when
compareTo -> Add Comparable operators for Either type
​

Remove

orNone() -> use getOrNone
​orNull -> use getOrNull

rightIfNotNull -> this?.right() ?: default().left()
rightIfNull -> this?.let { default().left() } ?: null.right()
leftIfNull -> DSL+ensureNotNull or flatMap { b -> b?.right() ?: default().left() }
​
isNotEmpty -> duplicate: use isRight()
isEmpty -> duplicate: use isLeft()
isLeft -> duplicate: use isLeft()
isRight -> duplicate: use isRight()
​
combineAll -> fold(Monoid.either(MA, MB))
combine -> Will be covered by accumulating zip behavior in 2.x.x
​
toValidatedNel: Validated removed in Arrow 2.x.x
toValidated: Validated removed in Arrow 2.x.x

[sksamuel]

tap might be named onRight which would align with the kotlin sdk names for things like onEach, onComplete, onSuccess, onFailure. Similarly tapLeft could be onLeft.

orNull could be getOrNull to align with Result.

[raulraja]

LGTM @nomisRev !, great work!

[nomisRev]

Those are great suggestions @sksamuel, onXXX also better indicates that it's a side-effect whilst tapXXX doesn't perse. Aligning more with Kotlin Std is always a win in my book, since it also helps reducing surprise factor and learning curve.

[JavierSegoviaCordoba]

About orNull, Gradle uses it on properties and I always forget it because I look for getOrNull. Big +1 for that.

[myuwono]

either.orNone() is a really useful function for option interop. Hopefully we can keep it. 🙏

[nomisRev]

@myuwono, thanks for your feedback 🙏

We've already kept this in mind, but I wanted to list it here explicitly anyways. And I'd like to pick your brain because I know you've worked a lot with Arrow's Option (in combination with Project Reactor).

I am wondering if you're experiencing a lack of Option APIs in other places? This is my concern about Option APIs actually, because I don't think that having getOrNull() increases the learning curve but it might increase the need for having Option specific APIs everywhere. Or do you think that the current balance we've already struck in 1.x.x is sufficient for all your use-case?

Secondary concern that people might use Option over nullable without actually having a need for it. Option should only be used with Project Reactor, RxJava or in generic code that is not constrained to A & Any.

PS: I assume you'd be okay with a orNone -> getOrNone rename as suggested for the nullable one above.

[nomisRev]

@JavierSegoviaCordoba @sksamuel thanks for the great feedback & help shaping Arrow 2.x.x together 🙏

I added onRight and onLeft and deprecated tap & tapLeft accordingly. Much more descriptive, and idiomatic Kotlin names. I made the same change for orNull -> getOrNull 👍

[Zordid]

While I appreciate a cleaner API in general, I really doubt the learning curve for my colleagues will be better if they see code like this:

flatMap { b -> b?.right() ?: default().left() }

instead of the much more understandable leftIfNull...

Even I have to twist my brain around all of the noise characters here instead of just reading what is meant. So, I got REALLY annoyed when I saw these deprecations in 1.1.5

Do you really think that it's wise to now let many people write their own extensions to bring back the ease of reading into their code?

[nomisRev]

Hey @Zordid,

Thank you for your feedback. flatMap { b -> b?.right() ?: default().left() } is not what we had in mind when deprecating this API but sadly ReplaceWith is quite limited in what it can do 😞

We consider the following code to be Arrow & Kotlin idiomatic. It leverages both the Arrow DSL, and Kotlin smart casting to offer an elegant and Kotlin idiomatic API.

either {
  val b: B? = bind()
  ensureNotNull(b) { default() }
  // b is smart-casted to non-null
}

This snippet is however not possible to be used with Kotlin's ReplaceWith and we think it offers a much more consistent and idiomatic API over leftIfNull.

Out of our own experience working on many projects with Kotlin & Arrow we felt these APIs are really confusing, and hard to learn for people not familiar with FP. Additionally, we've not used these methods in many years since the APIs were added that were shown above.

After asking for feedback on Slack, Github and Twitter we felt that most users were in agreement on this. If there are a couple APIs you extensively use, adding an extension method is always a good option. Otherwise feel free to open a Github issue for a specific API you think should remain towards 2.0.0 and we can discuss in more detail there to consider keeping it for 2.0.0.

[uliSchuster]

Without the ifNotNull extension functions, what would be a idiomatic way to write the following:

either {
    val sender = (cElem.findElementString(Tag.Sender)?.right() ?: MissingDataElementError(Tag.Sender).left()).bind()
    val receiver = (cElem.findElementString(Tag.Receiver)?.right() ?: MissingDataElementError(Tag.Receiver).left()).bind()
    Transmitter(sender, receiver)
}

Wrapping the entire expression in parenthesis just to call bind() on it immediately doesn't feel right

[serras]

@uliSchuster The easiest way would be

either {
  val sender = cElem.findElementString(Tag.Sender) ?: raise(MissingDataElementError(Tag.Sender))
  val receiver = cElem.findElementString(Tag.Receiver) ?: raise(MissingDataElementError(Tag.Receiver))
  Transmitter(sender, receiver)
}

[uliSchuster]

How about the corresponding functions for Validated and ValidatedNel; e.g., invalidNelIfNull()? Will they be deprecated as well? To keep the API consistent, this would seem consequential. But what would be an idiomatic Kotlin replacement?

[nomisRev]

The idiomatic way is actually using the ensureNotNull API in the DSL with Kotlin's smart-casting also available.

either {
    val sender = ensureNotNull(cElem.findElementString(Tag.Sender)) { MissingDataElementError(Tag.Sender) }
    val receiver = ensureNotNull(cElem.findElementString(Tag.Receiver)) { MissingDataElementError(Tag.Receiver }
    Transmitter(sender, receiver)
}

[nomisRev]

How about the corresponding functions for Validated and ValidatedNel; e.g., invalidNelIfNull()? Will they be deprecated as well? To keep the API consistent, this would seem consequential. But what would be an idiomatic Kotlin replacement?

Validated will get deprecated, and flattened into Either towards 2.x.x. Any feedback is greatly appreciated 🙏

Some relevant PRs:

• Feature/remove validated #2795
• Backport zipOrAccumulate for Either #2916
• Add flattenOrAccumulate #2892
• Introduce parMap and deprecate parTraverseXXX #2863
• zipOrAccumulate for Raise #2919