zio · jdegoes · Apr 7, 2021 · Apr 2, 2021 · Apr 2, 2021 · Apr 2, 2021
diff --git a/docs/datatypes/core/io.md b/docs/datatypes/core/io.md
@@ -5,7 +5,28 @@ title: "IO"
 
 `IO[E, A]` is a type alias for `ZIO[Any, E, A]`, which represents an effect that has no requirements, and may fail with an `E`, or succeed with an `A`.
 
-## Unproductive IO
+> **Note:**
+>
+> In Scala, the _type alias_ is a way to give a name to another type, to avoid having to repeat the original type again and again. It doesn't affect the type-checking process. It just helps us to have an expressive API design.
 
-`ZIO` values of type `IO[E, Nothing]` (where the value type is `Nothing`) are considered _unproductive_,
-because the `Nothing` type is _uninhabitable_, i.e. there can be no actual values of type `Nothing`. Values of this type may fail with an `E`, but will never produce a value.
+Let's see how the `IO` type alias is defined:
+
+```scala mdoc:invisible
+import zio.ZIO
+```
+
+```scala mdoc:silent
+type IO[+E, +A] = ZIO[Any, E, A]
+```
+
+So the `IO` just equal to `ZIO` which doesn't need any requirement.
+
+`ZIO` values of type `IO[E, Nothing]` (where the value type is `Nothing`) are considered _unproductive_, because the `Nothing` type is _uninhabitable_, i.e. there can be no actual values of type `Nothing`. Values of this type may fail with an `E`, but will never produce a value.
+
+> **Note:** _Principle of The Least Power_
+>
+> The `ZIO` data type is the most powerful effect in the ZIO library. It helps us to model various types of workflows. On other hand, the type aliases are a way of subtyping and specializing the `ZIO` type, specific for a less powerful workflow. 
+>
+> Lot of the time, we don't need such a piece of powerful machinery. So as a rule of thumb, whenever we require a less powerful effect, it's better to use the proper specialized type alias.
+>
+> So there is no need to convert type aliases to the `ZIO` data type, whenever the `ZIO` data type is required, we can use the most precise type alias to fit our workflow requirement.
diff --git a/docs/datatypes/core/rio.md b/docs/datatypes/core/rio.md
@@ -4,3 +4,27 @@ title: "RIO"
 ---
 
 `RIO[R, A]` is a type alias for `ZIO[R, Throwable, A]`, which represents an effect that requires an `R`, and may fail with a `Throwable` value, or succeed with an `A`.
+
+> **_Note:_**
+>
+> In Scala, the _type alias_ is a way to give a name to another type, to avoid having to repeat the original type again and again. It doesn't affect the type-checking process. It just helps us to have an expressive API design.
+
+Let's see how `RIO` is defined:
+```scala mdoc:invisible
+import zio.ZIO
+```
+
+```scala mdoc:silent
+type RIO[-R, +A]  = ZIO[R, Throwable, A]
+```
+
+So the `RIO` just equal to `ZIO` which its error channel is `Throwable`.
+
+
+> **Note:** _Principle of The Least Power_
+>
+> The `ZIO` data type is the most powerful effect in the ZIO library. It helps us to model various types of workflows. On other hand, the type aliases are a way of subtyping and specializing the `ZIO` type, specific for a less powerful workflow. 
+>
+> Lot of the time, we don't need such a piece of powerful machinery. So as a rule of thumb, whenever we require a less powerful effect, it's better to use the proper specialized type alias.
+>
+> So there is no need to convert type aliases to the `ZIO` data type, whenever the `ZIO` data type is required, we can use the most precise type alias to fit our workflow requirement.
diff --git a/docs/datatypes/core/task.md b/docs/datatypes/core/task.md
@@ -5,6 +5,30 @@ title: "Task"
 
 `Task[A]` is a type alias for `ZIO[Any, Throwable, A]`, which represents an effect that has no requirements, and may fail with a `Throwable` value, or succeed with an `A`.
 
+Let's see how the `Task` type alias is defined:
+
+```scala mdoc:invisible
+import zio.ZIO
+```
+
+```scala mdoc:silent
+type Task[+A] = ZIO[Any, Throwable, A]
+```
+
+So the `Task` just equal to `ZIO` which doesn't require any dependency. Its error channel is `Throwable`, so it may fail with `Throwable` and may succeed with an `A` value.
+
+> **Note:**
+>
+> In Scala, the _type alias_ is a way to give a name to another type, to avoid having to repeat the original type again and again. It doesn't affect the type-checking process. It just helps us to have an expressive API design.
+
 Some time, we know that our effect may fail, but we don't care the type of that exception, this is where we can use `Task`. The type signature of this type-alias is similar to the `Future[T]` and Cats `IO`.
 
 If we want to be less precise and want to eliminate the need to think about requirements and error types, we can use `Task`. This type-alias is a good start point for anyone who wants to refactor the current code base which is written in Cats `IO` or Monix `Task`. 
+
+> **Note:** _Principle of The Least Power_
+>
+> The `ZIO` data type is the most powerful effect in the ZIO library. It helps us to model various types of workflows. On other hand, the type aliases are a way of subtyping and specializing the `ZIO` type, specific for a less powerful workflow. 
+>
+> Lot of the time, we don't need such a piece of powerful machinery. So as a rule of thumb, whenever we require a less powerful effect, it's better to use the proper specialized type alias.
+>
+> So there is no need to convert type aliases to the `ZIO` data type, whenever the `ZIO` data type is required, we can use the most precise type alias to fit our workflow requirement.
diff --git a/docs/datatypes/core/uio.md b/docs/datatypes/core/uio.md
@@ -5,6 +5,22 @@ title: "UIO"
 
 `UIO[A]` is a type alias for `ZIO[Any, Nothing, A]`, which represents an **Unexceptional** effect that doesn't require any specific environment, and cannot fail, but can succeed with an `A`.
 
+> **_Note:_**
+>
+> In Scala, the _type alias_ is a way to give a name to another type, to avoid having to repeat the original type again and again. It doesn't affect the type-checking process. It just helps us to have an expressive API design.
+
+Let's see how the `UIO` type alias is defined:
+
+```scala mdoc:invisible
+import zio.ZIO
+```
+
+```scala mdoc:silent
+type UIO[+A] = ZIO[Any, Nothing, A]
+```
+
+So the `UIO` just equal to `ZIO` which doesn't need any requirement and cannot fail because in the Scala the `Nothing` type has no inhabitant, we can't create an instance of type `Nothing`.
+
 `ZIO` values of type `UIO[A]` (where the error type is `Nothing`) are considered _infallible_,
 because the `Nothing` type is _uninhabitable_, i.e. there can be no actual values of type `Nothing`. Values of this type may produce an `A`, but will never fail with an `E`.
 
@@ -26,3 +42,11 @@ def fib(n: Int): UIO[Int] =
     } yield v1 + v2
   }
 ```
+
+> **Note:** _Principle of The Least Power_
+>
+> The `ZIO` data type is the most powerful effect in the ZIO library. It helps us to model various types of workflows. On other hand, the type aliases are a way of subtyping and specializing the `ZIO` type, specific for a less powerful workflow. 
+>
+> Lot of the time, we don't need such a piece of powerful machinery. So as a rule of thumb, whenever we require a less powerful effect, it's better to use the proper specialized type alias.
+>
+> So there is no need to convert type aliases to the `ZIO` data type, whenever the `ZIO` data type is required, we can use the most precise type alias to fit our workflow requirement.
diff --git a/docs/datatypes/core/urio.md b/docs/datatypes/core/urio.md
@@ -5,8 +5,25 @@ title: "URIO"
 
 `URIO[R, A]` is a type alias for `ZIO[R, Nothing, A]`, which represents an effect that requires an `R`, and cannot fail, but can succeed with an `A`.
 
-In following example, the type of `putStrLn` is `URIO[Console, Unit]` which means, it requires `Console` service as an environment, and it succeeds with `Unit` value:
+> **_Note:_**
+>
+> In Scala, the _type alias_ is a way to give a name to another type, to avoid having to repeat the original type again and again. It doesn't affect the type-checking process. It just helps us to have an expressive API design.
+
+Let's see how the `URIO` type alias is defined:
+
 ```scala mdoc:invisible
+import zio.ZIO
+```
+
+```scala mdoc:silent
+type URIO[-R, +A] = ZIO[R, Nothing, A]
+```
+
+So the `URIO` just equal to `ZIO` which requires `R` and cannot fail because in the Scala the `Nothing` type has no inhabitant, we can't create an instance of type `Nothing`. It succeeds with `A`.
+
+In following example, the type of `putStrLn` is `URIO[Console, Unit]` which means, it requires `Console` service as an environment, and it succeeds with `Unit` value:
+
+```scala mdoc:invisible:reset
 import zio._
 import zio.console._
 ```
@@ -15,3 +32,11 @@ import zio.console._
 def putStrLn(line: => String): URIO[Console, Unit] =
   ZIO.accessM(_.get putStrLn line)
 ```
+
+> **Note:** _Principle of The Least Power_
+>
+> The `ZIO` data type is the most powerful effect in the ZIO library. It helps us to model various types of workflows. On other hand, the type aliases are a way of subtyping and specializing the `ZIO` type, specific for a less powerful workflow. 
+>
+> Lot of the time, we don't need such a piece of powerful machinery. So as a rule of thumb, whenever we require a less powerful effect, it's better to use the proper specialized type alias.
+>
+> So there is no need to convert type aliases to the `ZIO` data type, whenever the `ZIO` data type is required, we can use the most precise type alias to fit our workflow requirement.
diff --git a/docs/datatypes/misc/index.md b/docs/datatypes/misc/index.md
@@ -6,3 +6,4 @@ title: "Summary"
 - **[Chunk](chunk.md)** — ZIO `Chunk`: Fast, Pure Alternative to Arrays
 - **[Schedule](schedule.md)** — A `Schedule` is a model of a recurring schedule, which can be used for repeating successful `IO` values, or retrying failed `IO` values.
 - **[Has](has.md)** - A `Has` is used to express an effect's dependency on a service of type `A`.
+- **[Supervisor](supervisor.md)** — Supervising the launching and termination of fibers.
diff --git a/docs/datatypes/misc/supervisor.md b/docs/datatypes/misc/supervisor.md
@@ -0,0 +1,100 @@
+---
+id: supervisor
+title: "Supervisor"
+---
+
+A `Supervisor[A]` is allowed to supervise the launching and termination of fibers, producing some visible value of type `A` from the supervision.
+
+## Creation
+
+### track
+The `track` creates a new supervisor that tracks children in a set. It takes a boolean `weak` parameter as input, which indicates whether track children in a `Weakset` or not.
+
+
+```scala mdoc:invisible
+import zio.Supervisor
+```
+
+```scala mdoc
+val supervisor = Supervisor.track(true)
+```
+
+We can periodically, report the status of the fibers of our program with the help of the Supervisor.
+
+### fibersIn
+The `fibersIn` creates a new supervisor with an initial sorted set of fibers.
+
+In the following example we are creating a new supervisor from an initial set of fibers:
+
+```scala mdoc:invisible
+import zio.{Ref, Fiber}
+import scala.collection.immutable.SortedSet
+def fibers: Seq[Fiber.Runtime[Any, Any]] = ???
+```
+
+```scala mdoc
+def fiberListSupervisor = for { 
+  ref <- Ref.make(SortedSet.from(fibers))
+  s <- Supervisor.fibersIn(ref)
+} yield (s)
+```
+
+## Supervising
+
+Whenever we need to supervise a ZIO effect, we can call `ZIO#supervised` function, `supervised` takes a supervisor and return another effect. The behavior of children fibers is reported to the provided supervisor:
+
+```scala mdoc:invisible
+import zio._
+import zio.console._
+import zio.clock._
+import zio.duration._
+def fib(n: Int): ZIO[Any, Nothing, Int] = ???
+```
+
+```scala mdoc:silent
+val supervised = supervisor.flatMap(s => fib(20).supervised(s))
+```
+
+Now we can access all information of children fibers through the supervisor.
+
+## Example
+In the following example we are going to periodically monitor the number of fibers throughout our application life cycle:
+
+```scala mdoc:silent
+object SupervisorExample extends zio.App {
+  import zio.duration._
+
+  val program = for {
+    supervisor <- Supervisor.track(true)
+    fiber <- fib(20).supervised(supervisor).fork
+    policy = Schedule
+      .spaced(500.milliseconds)
+      .whileInputM[Any, Unit](_ => fiber.status.map(x => !x.isDone))
+    logger <- monitorFibers(supervisor)
+      .repeat(policy).fork
+    _ <- logger.join
+    result <- fiber.join
+    _ <- putStrLn(s"fibonacci result: $result")
+  } yield ()
+
+  def monitorFibers(supervisor: Supervisor[Chunk[Fiber.Runtime[Any, Any]]]) = for {
+    length <- supervisor.value.map(_.length)
+    _ <- putStrLn(s"number of fibers: $length")
+  } yield ()
+
+  def fib(n: Int): ZIO[Clock, Nothing, Int] =
+    if (n <= 1) {
+      ZIO.succeed(1)
+    } else {
+      for {
+        _ <- sleep(500.milliseconds)
+        fiber1 <- fib(n - 2).fork
+        fiber2 <- fib(n - 1).fork
+        v2 <- fiber2.join
+        v1 <- fiber1.join
+      } yield v1 + v2
+    }
+
+  override def run(args: List[String]) = program.exitCode
+}
+```
diff --git a/docs/howto/system.md → docs/howto/access-system-information.md b/docs/howto/system.md → docs/howto/access-system-information.md
@@ -1,6 +1,6 @@
 ---
-id: howto_access_system_information
-title: "Access system information"
+id: access-system-information
+title: "How to Access System Information?"
 ---
 
 Sometimes, environment variables are relevant information to an application. ZIO provides a `system` package to interface with this functionality.

diff --git a/docs/howto/handle_errors.md → docs/howto/handle-errors.md b/docs/howto/handle_errors.md → docs/howto/handle-errors.md
@@ -1,6 +1,6 @@
 ---
-id: howto_handle_errors
-title:  "Handle errors"
+id: handle-errors
+title: "How to Handle Errors?"
 ---
 
 ## Declared Errors vs Unforeseen Defects

diff --git a/docs/howto/howto_macros.md → docs/howto/howto-macros.md b/docs/howto/howto_macros.md → docs/howto/howto-macros.md
@@ -1,6 +1,6 @@
 ---
-id: howto_macros
-title:  "Macros"
+id: use-zio-macros
+title: "How to use ZIO Macros?"
 ---
 
 ## Scrapping the boilerplate with macros

diff --git a/docs/howto/index.md b/docs/howto/index.md
@@ -1,14 +1,7 @@
 ---
-id: howto_index
+id: index
 title: "Summary"
 ---
 
-Here are a few guides for common patterns with ZIO:
+Here are a few howto guides for common patterns with ZIO.
 
-- **[Use modules and layers](use_modules_and_layers.md)**: how to structure larger ZIO programs with the help of **ZIO environment**.
-- **[Test assertions](test_assertions.md)**: how to use **ZIO Test** assert properties in your code.
-- **[Test effects](test_effects.md)**: how to use **ZIO Test** to test effectual programs seamlessly.
-- **[Mock services](mock_services.md)**: how to test interactions between services with **mocks**.
-- **[Handle errors](handle_errors.md)**: how to deal with **errors** in ZIO (declared errors vs unforeseen defects).
-- **[Access system information](system.md)**: how to access **environment variables** and other **system properties** with ZIO.
-- **[How to migrate from Monix to ZIO](migrating_from_monix.md)**
diff --git a/docs/interop/catseffect.md → docs/howto/interop/with-cats-effect.md b/docs/interop/catseffect.md → docs/howto/interop/with-cats-effect.md
@@ -1,9 +1,9 @@
 ---
-id: interop_catseffect
-title:  "Cats Effect"
+id: with-cats-effect
+title: "How to Interop with Cats Effect?"
 ---
 
-The `interop-cats` module provides interoperability for the Cats Effect ecosystem.
+[`interop-cats`](https://github.com/zio/interop-cats) has instances for the [Cats](https://typelevel.org/cats/), [Cats MTL](https://github.com/typelevel/cats-mtl) and [Cats Effect](https://typelevel.org/cats-effect/) libraries, which allow you to use ZIO with any libraries that rely on these, like [Doobie](https://github.com/tpolecat/doobie), [Http4s](https://github.com/http4s/http4s), [FS2](https://github.com/functional-streams-for-scala/fs2) or [Circe](https://github.com/circe/circe)
 
 To use this module, add the following to your `build.sbt`:
 

diff --git a/docs/interop/future.md → docs/howto/interop/with-future.md b/docs/interop/future.md → docs/howto/interop/with-future.md
@@ -1,6 +1,6 @@
 ---
-id: interop_future
-title:  "Future"
+id: with-future
+title: "How to Interop with Future?"
 ---
 
 ## Scala Future

diff --git a/docs/howto/interop/with-guava.md b/docs/howto/interop/with-guava.md
@@ -0,0 +1,6 @@
+---
+id: with-guava
+title: "How to Interop with Guava?"
+---
+
+[`interop-guava`](https://github.com/zio/interop-guava) module provide capibility to convert [Guava's `com.google.common.util.concurrent.ListenableFuture`](https://github.com/google/guava/wiki/ListenableFutureExplained) into ZIO `Task`.
diff --git a/docs/interop/java.md → docs/howto/interop/with-java.md b/docs/interop/java.md → docs/howto/interop/with-java.md
@@ -1,10 +1,12 @@
 ---
-id: interop_java
-title:  "Java"
+id: with-java
+title: "How to Interop with Java?"
 ---
 
 ZIO has full interoperability with foreign Java code. Let me show you how it works and then *BOOM*, tomorrow you can show off your purely functional Java at work.
 
+ZIO has built-in conversion between ZIO data types (like `ZIO` and `Fiber`) and Java concurrent data types like [`CompletionStage`](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/CompletionStage.html), [`Future`](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/Future.html) and [`CompletionHandler`](https://docs.oracle.com/javase/8/docs/api/java/nio/channels/CompletionHandler.html).
+
 ## From Java CompletionStage and back
 
 `CompletionStage` is the interface that comes closest to emulate a functional asynchronous effects API like ZIO's, so we start with it. It's a breeze:

diff --git a/docs/interop/javascript.md → docs/howto/interop/with-javascript.md b/docs/interop/javascript.md → docs/howto/interop/with-javascript.md
@@ -1,6 +1,6 @@
 ---
-id: interop_javascript
-title:  "JavaScript"
+id: with-javascript
+title: "How to Interop with JavaScript?"
 ---
 
 Include ZIO in your Scala.js project by adding the following to your `build.sbt`:

diff --git a/docs/interop/monix.md → docs/howto/interop/with-monix.md b/docs/interop/monix.md → docs/howto/interop/with-monix.md
@@ -1,9 +1,9 @@
 ---
-id: interop_monix
-title:  "Monix"
+id: with-monix
+title: "How to Interop with Monix?"
 ---
 
-Checkout `interop-monix` module for inter-operation support.
+Checkout [`interop-monix`](https://github.com/zio/interop-monix) module for inter-operation support.
 
 ## `Task` conversions
 

diff --git a/docs/interop/reactivestreams.md → docs/howto/interop/with-reactive-streams.md b/docs/interop/reactivestreams.md → docs/howto/interop/with-reactive-streams.md
@@ -1,9 +1,9 @@
 ---
-id: interop_reactivestreams
-title:  "Reactive Streams"
+id: with-reactive-streams
+title: "How to Interop with Reactive Streams?"
 ---
 
-Checkout the `interop-reactive-streams` module for inter-operation support.
+Checkout the [`interop-reactive-streams`](https://github.com/zio/interop-reactive-streams) module for inter-operation support.
 
 ## Reactive Streams `Producer` and `Subscriber`