From 71c106244d7c48d79f851dc6b40856ff3ba1e4e0 Mon Sep 17 00:00:00 2001
From: Pierre Ricadat <ghostdogpr@users.noreply.github.com>
Date: Sun, 27 Oct 2019 09:02:44 +0900
Subject: [PATCH] Docs for cats interop (#58)

---
 .../interop/cats/ExampleCatsInterop.scala     |  8 ++--
 vuepress/docs/.vuepress/config.js             |  1 +
 vuepress/docs/docs/README.md                  |  6 +++
 vuepress/docs/docs/interop.md                 | 42 +++++++++++++++++++
 4 files changed, 53 insertions(+), 4 deletions(-)
 create mode 100644 vuepress/docs/docs/interop.md

diff --git a/examples/src/main/scala/caliban/interop/cats/ExampleCatsInterop.scala b/examples/src/main/scala/caliban/interop/cats/ExampleCatsInterop.scala
index 1544af2f6..f90ce447a 100644
--- a/examples/src/main/scala/caliban/interop/cats/ExampleCatsInterop.scala
+++ b/examples/src/main/scala/caliban/interop/cats/ExampleCatsInterop.scala
@@ -2,7 +2,7 @@ package caliban.interop.cats
 
 import caliban.GraphQL.graphQL
 import caliban.RootResolver
-import cats.effect.{ExitCode, IO, IOApp}
+import cats.effect.{ ExitCode, IO, IOApp }
 import zio.DefaultRuntime
 
 object ExampleCatsInterop extends IOApp {
@@ -15,10 +15,10 @@ object ExampleCatsInterop extends IOApp {
 
   case class Queries(numbers: List[Number], randomNumber: IO[Number])
 
-  val numbers = List(1, 2, 3, 4).map(Number)
+  val numbers      = List(1, 2, 3, 4).map(Number)
   val randomNumber = IO(scala.util.Random.nextInt()).map(Number)
 
-  val queries = Queries(numbers, randomNumber)
+  val queries     = Queries(numbers, randomNumber)
   val interpreter = graphQL(RootResolver(queries))
 
   val query = """
@@ -35,6 +35,6 @@ object ExampleCatsInterop extends IOApp {
   override def run(args: List[String]): IO[ExitCode] =
     for {
       result <- interpreter.executeAsync[IO](query)
-      _ <- IO(println(result))
+      _      <- IO(println(result))
     } yield ExitCode.Success
 }
diff --git a/vuepress/docs/.vuepress/config.js b/vuepress/docs/.vuepress/config.js
index dcd29bfe0..e7d7861b6 100644
--- a/vuepress/docs/.vuepress/config.js
+++ b/vuepress/docs/.vuepress/config.js
@@ -33,6 +33,7 @@ module.exports = {
                 'schema',
                 'validation',
                 'introspection',
+                'interop',
                 'examples'
               ]
             }
diff --git a/vuepress/docs/docs/README.md b/vuepress/docs/docs/README.md
index c74bd295e..bf182a3cc 100644
--- a/vuepress/docs/docs/README.md
+++ b/vuepress/docs/docs/README.md
@@ -15,6 +15,12 @@ To use `caliban`, add the following line in your `build.sbt` file:
 libraryDependencies += "com.github.ghostdogpr" %% "caliban" % "0.1.0"
 ```
 
+The following modules are optional:
+``` 
+libraryDependencies += "com.github.ghostdogpr" %% "caliban-http4s" % "0.1.0" // routes for http4s
+libraryDependencies += "com.github.ghostdogpr" %% "caliban-cats"   % "TODO"  // interop with cats effect
+```
+
 Note that Caliban is also available for ScalaJS.
 
 ## A simple example
diff --git a/vuepress/docs/docs/interop.md b/vuepress/docs/docs/interop.md
new file mode 100644
index 000000000..cc8dba3c5
--- /dev/null
+++ b/vuepress/docs/docs/interop.md
@@ -0,0 +1,42 @@
+# Interop (Cats)
+
+If you prefer using [Monix](https://github.com/monix/monix) or [Cats IO](https://github.com/typelevel/cats-effect) rather than ZIO, you can use the `caliban-cats` module.
+
+You first need to import `caliban.interop.cats.implicits._` and have an implicit `zio.Runtime` in scope. Then a few helpers are available:
+- the GraphQL object is enriched with `executeAsync` and `checkAsync`, variants of `execute` and `check` that return an `F[_]: Async` instead of a `ZIO`.
+- the `Http4sAdapter` also has cats-effect variants named `makeRestServiceF` and `makeWebSocketServiceF`.
+
+In addition to that, a `Schema` for any `F[_]: Effect` is provided. That means you can include fields returning Monix Task for Cats IO in your queries, mutations or subscriptions.
+
+The following example shows how to create an interpreter and run a query while only using Cats IO.
+```scala
+import caliban.GraphQL.graphQL
+import caliban.RootResolver
+import caliban.interop.cats.implicits._
+import cats.effect.{ ExitCode, IO, IOApp }
+import zio.DefaultRuntime
+
+object ExampleCatsInterop extends IOApp {
+
+  implicit val runtime = new DefaultRuntime {}
+
+  case class Queries(numbers: List[Int], randomNumber: IO[Int])
+
+  val queries     = Queries(List(1, 2, 3, 4), IO(scala.util.Random.nextInt()))
+  val interpreter = graphQL(RootResolver(queries))
+
+  val query = """
+  {
+    numbers
+    randomNumber
+  }"""
+
+  override def run(args: List[String]): IO[ExitCode] =
+    for {
+      result <- interpreter.executeAsync[IO](query)
+      _      <- IO(println(result))
+    } yield ExitCode.Success
+}
+```
+
+You can find this example within the [examples](https://github.com/ghostdogpr/caliban/blob/master/examples/src/main/scala/caliban/interop/cats/ExampleCatsInterop.scala) project.
\ No newline at end of file