Add the possibility to ok() a forked-either computation (#155)

Author: adamw

core/src/main/scala/ox/either.scala

@@ -70,6 +70,15 @@ object either:
         case _ => error("`.ok()` can only be used within an `either` call.\nIs it present?")
       }
 
+  extension [E, A](inline f: Fork[Either[E, A]])
+    /** Join the fork and unwrap the value of its `Either` result, short-circuiting the computation to the enclosing [[either]], in case
+      * this is a left-value.
+      *
+      * If the fork fails with an exception, the enclosing scope ends (when it's [[supervised]]), or the exception is re-thrown by this
+      * method (when the enclosing scope is [[unsupervised]]).
+      */
+    transparent inline def ok(): A = f.join().ok()
+
   extension [E](e: E)
     transparent inline def fail(): Nothing =
       summonFrom {

core/src/main/scala/ox/fork.scala

@@ -193,10 +193,15 @@ private[ox] inline def unwrapExecutionException[T](f: => T): T =
   */
 trait Fork[T]:
   /** Blocks until the fork completes with a result. Throws an exception, if the fork completed with an exception, and is unsupervised.
+    *
+    * @see
+    *   If `T` is an `Either`, and there's an enclosing [[either]] block, the result can be unwrapped using [[either.ok]].
     */
   def join(): T
 
-  /** Blocks until the fork completes with a result. */
+  /** Blocks until the fork completes with a result. Only makes sens in unsupervised scoped: otherwise a thrown exception causes the scope
+    * to end, and is re-thrown by the [[supervised]] block.
+    */
   def joinEither(): Either[Throwable, T] =
     try Right(join())
     catch

core/src/test/scala/ox/EitherTest.scala

@@ -59,6 +59,17 @@ class EitherTest extends AnyFlatSpec with Matchers:
     r3 shouldBe Left(())
   }
 
+  it should "work correctly when invoked on fork" in {
+    supervised:
+      val f =
+        fork:
+          either:
+            ok1.ok()
+
+      either:
+        f.ok() shouldBe "x"
+  }
+
   it should "report a proper compilation error when used outside of either:" in {
     val e = intercept[TestFailedException](assertCompiles("ok1.ok()"))
 

core/src/test/scala/ox/ForkTest.scala

@@ -7,7 +7,7 @@ import ox.util.Trail
 
 import scala.concurrent.duration.*
 
-class ForkTest extends AnyFlatSpec with Matchers {
+class ForkTest extends AnyFlatSpec with Matchers:
   "fork" should "run two forks concurrently" in {
     val trail = Trail()
     unsupervised {
@@ -73,4 +73,4 @@ class ForkTest extends AnyFlatSpec with Matchers {
 
     trail.get shouldBe Vector("main mid", "f1 complete", "result = 5", "f2 interrupted")
   }
-}
+

doc/basics/error-handling.md

@@ -87,7 +87,7 @@ val result: Either[Int | Long, String] = either:
   v1.ok() ++ v2.ok()
 ```
 
-Finally, options can be unwrapped as well; the error type is then `Unit`:
+Options can be unwrapped as well; the error type is then `Unit`:
 
 ```scala mdoc:compile-only
 import ox.either
@@ -100,6 +100,21 @@ val result: Either[Unit, String] = either:
   v1.ok() * v2.ok()
 ```
 
+Finally, a forked computation, resulting in an `Either`, can be joined & unwrapped using a single `ok()` invocation:
+
+```scala mdoc:compile-only
+import ox.{either, fork, Fork, supervised}
+import ox.either.ok
+
+val v1: Either[Int, String] = ???
+
+supervised:
+  val forkedResult: Fork[Either[Int, String]] = fork(either(v1.ok()))
+
+  val result: Either[Int, String] = either:
+    forkedResult.ok()
+```
+
 Failures can be reported using `.fail()`. For example (although a pattern match would be better in such a simple case):
 
 ```scala mdoc:compile-only
@@ -173,4 +188,4 @@ val outerResult: Either[Exception, Unit] = either:
   ()
 ```
 
-After this change refactoring `returnsEither` to return `Either[Exception, Int]` would yield a compile error on `returnsEither.ok()`.
+After this change refactoring `returnsEither` to return `Either[Exception, Int]` would yield a compile error on `returnsEither.ok()`.