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

[gutiory]

Ior API deprecation

This PR proposes a smaller API surface for Ior without compromising 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-known APIs from Kotlin Std, or KotlinX Coroutines

Ior (API Size 65 -> 28)

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

Keep

• flatMap: transform right value. with Ior
• flatten: flatten nested Iors.
• map: transform right value, when Right or Both
• widen: change generic parameter to a super class type.

Remove

• exists -> fold({ false }, predicate) // map(predicate).getOrElse { false }
• leftWiden: widen already covers Left , Right , and Both
• lift(f): replace with { it.map(f) }
• lift(fa, fb): replace with { it.map(fb).mapLeft(fa) }
• bimap: replace with map(fb).mapLeft(fa)
• findOrNull: use getOrNull()?.takeIf(predicate)
• void: use map { }
• zip -> Replaced with Validated behavior, original zip will be inline ior + bind

Applicative/MonadError (API Size 4 -> 4)

Keep

• getOrElse: get Right value if Right or Both . Get default if Left
• mapLeft: transform left value, when Left or Both
• replicate: Hard to find a simple sugestion to replace the use

Foldable / (Bi)Traverse (API Size 25 -> 1)

Keep

• fold

Remove

All traverse, bitraverse, sequence, bisequence, crosswalk are set to be replace with fold

• all
• bicrosswalk
• bicrosswalkMap
• bicrosswalkNull
• bitraverse
• bitraverseEither
• bitraverseNullable
• bitraverseOption
• bitraverseValidated
• bifoldLeft: replace with fold
• bifoldMap: replace with fold
• crosswalk
• crosswalkMap
• crosswalkNull
• foldLeft: replace with fold
• foldMap: replace with fold
• traverse( iterable )
• traverseEither
• traverse( Either )
• traverseNullable
• traverse( Option )
• traverseOption( Option )
• traverse(Validated)
• traverseValidated(Validated)

Utilities (14 -> 9)

Keep

• bothIor: construct a Both from a Pair
• getOrNull: get Right if Ior is Right or Both.
• leftOrNull: get Left if Ior is Left or Both.
• leftIor: construct a Left from a value
• padNull: return the Ior as a Pair o nullables.
• rightIor: construct a Right from a value
• swap: flip type arguments
• toEither: return Right if the Ior is Right or Both. Left otherwise.
• unwrap: return the isomorphic Either of the Ior

Remove

• combine -> Will be covered by accumulating zip behavior in 2.x.x
• isEmpty: use isLeft
• isNotEmpty: use isRight
• orNull: use getOrNull
• toValidated: Validated removed in Arrow 2.x.x

[github-actions]

Kover Report

File	Coverage [59.78%]
arrow-libs/core/arrow-core/src/commonMain/kotlin/arrow/core/Ior.kt	59.78%

Total Project Coverage	44.10%

[nomisRev]

Great work @gutiory 🙌 Thank you so much for looking into this! I added a bunch of suggestions 😅 Feel free to apply them, or use them as a guide to update the PR. Whatever works best for you.

• ReplaceWith is missing imports, added Ior. in most cases to avoid conflicts with Either.Left & Either.Right.
• A bunch of identity calls slipped in due to refactoring tools of IDEA.
• Some styling nits (Spaces before { mostly).
• Small improvements to foldLeft and bifold, empty + a == a for Monoid so the ReplaceWith can be simplified.

[nomisRev]

Suggested change

	ReplaceWith("fold({ f(c, it) }, { g(c, it) }, { a, b -> g(f(c, a), b) })")
	ReplaceWith("this.fold<C>({ f(c, it) }, { g(c, it) }, { a, b -> g(f(c, a), b) })")

[gutiory]

question: Why is it needed here the this.fold<C> part?. I've tried a couple of replacement and the result is the same than using the current solution.

_{This comment follows the conventionalcomments.org standard}

[nomisRev]

This replacement was not working for me as is :/
Just adding this is sufficient, it's strange it works for foldMap, without this.

So the <C> can be ignored, IIRC adding it adds a type-check during replacement that checks if the resulting replacement is correct in cases where it otherwise is incorrect but it's not entirely clear to me when it's needed and when not. Similar in this case for this.

[gutiory]

See 74ef6ec (#2928)

[nomisRev]

Sorry to keep you waiting for so long @gutiory. Thanks for all the great work so far 🙌
Couple of things we still need to address, that I missed in the first review:

1. We missed a couple of deprecations:

• isRight, isLeft, & isBoth properties
• toValidated
• bitraverseValidated, bisequenceValidated
• replicate

2. we should align getOrElse function with the other signatures. This can be done without deprecation, in a source -and binary compatible way. Either.getOrElse { }, Either.getOrElse { _ -> }.

3. We need to introduce getLeftOrNull similarly to getOrNull and deprecate the current leftOrNull method. Similarly I would love to have a better name for padNull but getBothOrNull seems wrong since it returns Pair<A?, B?> 🤔

I've tested a couple of the ReplaceWith, and left comments. Also resolved some of the previous comments that were still open.

[nomisRev]

This replacement was not working for me as is :/
Just adding this is sufficient, it's strange it works for foldMap, without this.

So the <C> can be ignored, IIRC adding it adds a type-check during replacement that checks if the resulting replacement is correct in cases where it otherwise is incorrect but it's not entirely clear to me when it's needed and when not. Similar in this case for this.

[nomisRev]

The PR looks really great! Thank you for all the hard work, and a lot of patience @gutiory. 🙏 👏 👏 👏
Let's merge this this 🙌

[nomisRev]

Thank you, to completely track decision making on this. Result from Kotlin Std has exceptionOrNull alongside getOrNull instead of getExceptionOrNull so we're following the same API naming pattern.

[franciscodr]

Great job, @gutiory!