Release 0.2.2

Author: adamw

README.md

@@ -23,13 +23,13 @@ the project!
 To test Ox, use the following dependency, using either [sbt](https://www.scala-sbt.org):
 
 ```scala
-"com.softwaremill.ox" %% "core" % "0.2.1"
+"com.softwaremill.ox" %% "core" % "0.2.2"
 ```
 
 Or [scala-cli](https://scala-cli.virtuslab.org):
 
 ```scala
-//> using dep "com.softwaremill.ox::core:0.2.1"
+//> using dep "com.softwaremill.ox::core:0.2.2"
 ```
 
 Documentation is available at [https://ox.softwaremill.com](https://ox.softwaremill.com), ScalaDocs can be browsed at [https://javadoc.io](https://www.javadoc.io/doc/com.softwaremill.ox).

generated-doc/out/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
 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
+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
@@ -120,3 +135,57 @@ import ox.catching
 
 val result: Either[Throwable, String] = catching(throw new RuntimeException("boom"))
 ```
+
+### Nested `either` blocks
+
+Either blocks cannot be nested in the same scope to prevent surprising failures after refactors. The `.ok()` combinator
+is typed using inference. Therefore, nesting of `either:` blocks can quickly lead to a scenario where due to a change 
+in the return type of a method, another `either:` block will be selected by the `.ok()` combinator. This could lead to a
+change in execution semantics without a compile error. Consider:
+
+```scala 
+import ox.either, either.*
+
+def returnsEither: Either[String, Int] = ???
+
+val outerResult: Either[Exception, Unit] = either:
+  val innerResult: Either[String, Int] = either:
+    val i = returnsEither.ok() // this would jump to innerResult on Left
+    // ...
+    i
+  ()
+```
+
+Now, after a small refactor of `returnsEither` return type the `returnsEither.ok()` expression would still compile but 
+instead of short-circuiting the inner `either:` block, it would immediately jump to the outer `either:` block on errors.
+
+```scala
+import ox.either, either.*
+
+def returnsEither: Either[Exception, Int] = ???
+
+val outerResult: Either[Exception, Unit] = either:
+  val innerResult: Either[String, Int] = either:
+    val i = returnsEither.ok() // this would jump to outerResult on Left now!
+    // ...
+    i
+  ()
+```
+
+Proper way to solve this is to extract the inner `either:` block to a separate function:
+
+```scala
+import ox.either, either.*
+
+def returnsEither: Either[String, Int] = ???
+
+def inner(): Either[String, Int] = either:
+  val i = returnsEither.ok() // this can only jump to either on the opening of this function
+  i
+
+val outerResult: Either[Exception, Unit] = either:
+  val innerResult = inner()
+  ()
+```
+
+After this change refactoring `returnsEither` to return `Either[Exception, Int]` would yield a compile error on `returnsEither.ok()`.

generated-doc/out/basics/start-here.md

@@ -4,10 +4,10 @@
 
 ```scala
 // sbt dependency
-"com.softwaremill.ox" %% "core" % "0.2.1"
+"com.softwaremill.ox" %% "core" % "0.2.2"
 
 // scala-cli dependency
-//> using dep "com.softwaremill.ox::core:0.2.1"
+//> using dep "com.softwaremill.ox::core:0.2.2"
 ```
 
 ## Scope of the Ox project

generated-doc/out/io.md

@@ -68,13 +68,13 @@ To use the plugin, add the following settings to your sbt configuration:
 
 ```scala
 autoCompilerPlugins := true
-addCompilerPlugin("com.softwaremill.ox" %% "plugin" % "0.2.1")
+addCompilerPlugin("com.softwaremill.ox" %% "plugin" % "0.2.2")
 ```
 
 For scala-cli:
 
 ```scala
-//> using plugin com.softwaremill.ox:::plugin:0.2.1
+//> using plugin com.softwaremill.ox:::plugin:0.2.2
 ```
 
 With the plugin enabled, the following code won't compile:

generated-doc/out/kafka.md

@@ -3,7 +3,7 @@
 Dependency:
 
 ```scala
-"com.softwaremill.ox" %% "kafka" % "0.2.1"
+"com.softwaremill.ox" %% "kafka" % "0.2.2"
 ```
 
 `Source`s which read from a Kafka topic, mapping stages and drains which publish to Kafka topics are available through