Adds validNel and invalidNel extension functions (#123)

Backports validNel and invalidNel extension functions which were
originally available in Validated, but recently removed in Arrow 2.x.

Adds `shouldBeValid` and `shouldBeInvalid` matchers.

Author: hugomd

lib/api/lib.api

@@ -234,8 +234,10 @@ public final class app/cash/quiver/extensions/SuspendedFunctionKt {
 public final class app/cash/quiver/extensions/ValidatedKt {
 	public static final fun attemptValidated (Larrow/core/Either;)Larrow/core/Either;
 	public static final fun concatMap (Larrow/core/Either;Lkotlin/jvm/functions/Function1;)Larrow/core/Either;
+	public static final fun invalidNel (Ljava/lang/Object;)Larrow/core/Either;
 	public static final fun takeLeft (Larrow/core/Either;Larrow/core/Either;)Larrow/core/Either;
 	public static final fun takeRight (Larrow/core/Either;Larrow/core/Either;)Larrow/core/Either;
+	public static final fun validNel (Ljava/lang/Object;)Larrow/core/Either;
 	public static final fun validate (Ljava/lang/Object;Lkotlin/jvm/functions/Function1;Lkotlin/jvm/functions/Function1;)Larrow/core/Either;
 	public static final fun validateEither (Ljava/lang/Object;Lkotlin/jvm/functions/Function1;Lkotlin/jvm/functions/Function1;)Larrow/core/Either;
 	public static final fun validateMap (Ljava/lang/Object;Lkotlin/jvm/functions/Function1;Lkotlin/jvm/functions/Function2;)Larrow/core/Either;

lib/src/main/kotlin/app/cash/quiver/extensions/Validated.kt

@@ -87,3 +87,17 @@ inline fun <ERR, A, B> A.validateMap(
  */
 inline fun <ERR, A, B> ValidatedNel<ERR, A>.concatMap(f: (A) -> ValidatedNel<ERR, B>): ValidatedNel<ERR, B> =
   this.flatMap { f(it) }
+
+/**
+ * An extension method for constructing a valid ValidatedNel.
+ */
+fun <A> A.validNel(): ValidatedNel<Nothing, A> =
+  this.right()
+
+
+/**
+ * An extension method for constructing an invalid ValidatedNel.
+ */
+fun <E> E.invalidNel(): ValidatedNel<E, Nothing> =
+  nonEmptyListOf(this).left()
+

lib/src/test/kotlin/app/cash/quiver/extensions/ValidatedTest.kt

@@ -0,0 +1,16 @@
+package app.cash.quiver.extensions
+
+import app.cash.quiver.matchers.shouldBeInvalid
+import app.cash.quiver.matchers.shouldBeValid
+import io.kotest.core.spec.style.StringSpec
+import io.kotest.matchers.shouldBe
+
+class ValidatedTest : StringSpec({
+  "validNel creates an Either.Right<A>" {
+    "hello world".validNel().shouldBeValid() shouldBe "hello world"
+  }
+
+  "invalidNel creates an Either.Left<NonEmptyList<E>>" {
+    "uh oh!".invalidNel().shouldBeInvalid() shouldBe setOf("uh oh!")
+  }
+})

testing-lib/api/testing-lib.api

@@ -9,6 +9,7 @@ public final class app/cash/quiver/matchers/MatchersKt {
 	public static final fun shouldBeAbsent (Lapp/cash/quiver/Outcome;Lkotlin/jvm/functions/Function1;)V
 	public static synthetic fun shouldBeAbsent$default (Lapp/cash/quiver/Outcome;Lkotlin/jvm/functions/Function1;ILjava/lang/Object;)V
 	public static final fun shouldBeFailure (Lapp/cash/quiver/Outcome;)Ljava/lang/Object;
+	public static final fun shouldBeInvalid (Larrow/core/Either;)Ljava/util/Set;
 	public static final fun shouldBePresent (Lapp/cash/quiver/Outcome;Lkotlin/jvm/functions/Function1;)Ljava/lang/Object;
 	public static synthetic fun shouldBePresent$default (Lapp/cash/quiver/Outcome;Lkotlin/jvm/functions/Function1;ILjava/lang/Object;)Ljava/lang/Object;
 }

testing-lib/src/main/kotlin/app/cash/quiver/matchers/Matchers.kt

@@ -4,6 +4,9 @@ import app.cash.quiver.Absent
 import app.cash.quiver.Failure
 import app.cash.quiver.Outcome
 import app.cash.quiver.Present
+import app.cash.quiver.extensions.ValidatedNel
+import arrow.core.Either
+import arrow.core.NonEmptyList
 import kotlin.contracts.ExperimentalContracts
 import kotlin.contracts.contract
 
@@ -42,3 +45,26 @@ fun <A, B> Outcome<A, B>.shouldBeFailure(): A {
     is Present -> throw AssertionError("Expected Outcome.Failure but got Present($value)")
   }
 }
+
+@OptIn(ExperimentalContracts::class)
+inline fun <E, reified A> ValidatedNel<E, A>.shouldBeValid(): A {
+  contract {
+    returns() implies (this@shouldBeValid is A)
+  }
+
+  return when(this) {
+    is Either.Left -> throw AssertionError("Expected Right (Valid), but found $this")
+    is Either.Right -> value
+  }
+}
+@OptIn(ExperimentalContracts::class)
+fun <E, A> ValidatedNel<E, A>.shouldBeInvalid(): Set<E> {
+  contract {
+    returns() implies (this@shouldBeInvalid is Set<*>)
+  }
+
+  return when(this) {
+    is Either.Left -> value.toSet()
+    is Either.Right -> throw AssertionError("Expected Left (Invalid), but found $this")
+  }
+}