make package ready

Author: ValdemarGr

README.md

@@ -1 +1,80 @@
-# hxl
+# Hxl
+Hxl is a pure applicative batching library for Scala.
+
+Hxl is based on the ideas presented in [Haxl](https://simonmar.github.io/bib/papers/haxl-icfp14.pdf), but diverges in in a few ways.
+Notably, hxl does not use side effects, but is instead based on free applicatives.
+
+Hxl is very small (only a couple hundred lines of code) and only depends on cats.
+
+Hxl is written in tagless final, which allows for molding the library to your needs.
+
+## Installation
+Hxl is available on Maven Central for Scala 2.13 and 3.2.
+```scala
+libraryDependencies += "com.github.casehubdk" %% "hxl" % "0.1.0"
+```
+
+## Usage
+There are two primitive structures in hxl: `DataSource[F, K, V]` and `DSKey[K, V]`.
+A `DataSource[F, K, V]` abstracts over a function `NonEmptyList[K] => F[Map[K, V]]`.
+A `DataSource` is uniquely (as in Scala universal equals) identified by its `DSKey`.
+```scala
+import cats._
+import cats.implicits._
+
+final case class MyDSKey(id: String)
+case object MyDSKey extends DSKey[MyDSKey, String]
+
+val database = Map(
+  "foo" -> "bar",
+  "baz" -> "qux"
+)
+
+def dataSource[F[_]: Applicative] = DataSource.from[F, MyDSKey, String](MyDSKey) { keys =>
+  keys.toList.flatMap(key => database.get(key.id).toList.tupleLeft(key)).toMap.pure[F]
+}
+
+val fa: Hxl[Id, Option[String]] = Hxl(MyDSKey("foo"), dataSource[Id])
+val fb: Hxl[Id, Option[String]] = Hxl(MyDSKey("baz"), dataSource[Id])
+(fa, fb).mapN(_.mkString + " " + _.mkString) // "bar qux"
+```
+
+Hxl is an applicative, but sometimes you need a monad.
+Hxl is like `Validated` from `cats`, in that it can escape it's applicative nature via a method `andThen`.
+However, if you need Hxl to become a monad (like `Either` to `Validated`), you can use request a monadic view of your effect:
+```scala
+val fa: Hxl[F, String] = ???
+
+val m: HxlM[F, String] = fa.monadic.flatMap{ x =>
+  ???
+}
+
+val back: Hxl[F, String] = m.hxl
+```
+
+## Advanced usage
+Since Hxl is written in tagless final, you can add various behaviors to your data sources.
+For instance, you can add (pure) caching.
+```scala
+import cats.data._
+import cats.implicits._
+
+final case class MyDSKey(id: String)
+case object MyDSKey extends DSKey[MyDSKey, String]
+
+val database = Map(
+  "foo" -> "bar",
+  "baz" -> "qux"
+)
+
+type Cache = Map[String, String]
+type Effect[A] = State[Cache, A]
+
+def dataSource: DataSource[Effect, MyDSKey, String] = DataSource.from(MyDSKey) { keys =>
+  State[Cache, Map[MyDSKey, String]] { cache =>
+    val (misses, hits) = keys.toList.partitionEither(k => cache.get(k.id).tupleLeft(k).toRight(k))
+    val fetched = misses.flatMap(key => database.get(key.id).toList.map(key -> _)).toMap
+    (cache ++ fetched.map{ case (k, v) => k.id -> v }, hits.toMap ++ fetched)
+  }
+}
+```

hxl/src/main/scala/hxl/Hxl.scala

@@ -18,7 +18,6 @@ package hxl
 
 import cats._
 import cats.implicits._
-import cats.arrow.FunctionK
 
 /*
  * Hxl is a value that that represents a computation that may be batched.
@@ -71,7 +70,7 @@ object Hxl {
   }
 
   def runSequential[F[_]: Monad, A](node: Hxl[F, A]): F[A] = {
-    implicit val ev = Parallel.identity[F]
+    implicit val ev: Parallel[F] = Parallel.identity[F]
     runPar[F, A](node)
   }
 
@@ -93,10 +92,12 @@ object Hxl {
     new Parallel[G] {
       type F[A] = Hxl[P.F, A]
 
-      override def sequential: F ~> G =
-        FunctionK.liftFunction(fa => fa.mapK(P.sequential)(P.monad))
-      override def parallel: G ~> F =
-        FunctionK.liftFunction(fa => fa.mapK(P.parallel)(P.applicative))
+      override def sequential: F ~> G = new (F ~> G) {
+        def apply[A](fa: F[A]): G[A] = fa.mapK(P.sequential)(P.monad)
+      }
+      override def parallel: G ~> F = new (G ~> F) {
+        def apply[A](fa: G[A]): F[A] = fa.mapK(P.parallel)(P.applicative)
+      }
 
       override def applicative: Applicative[F] = applicativeForHxl[P.F](P.applicative)
 

hxl/src/main/scala/hxl/Requests.scala

@@ -66,9 +66,9 @@ object Requests {
 
   def read[F[_], A](req: Requests[F, A], state: DSMap): Eval[A] = Eval.defer {
     req match {
-      case Pure(a)          => Eval.now(a)
-      case ap: Ap[F, a, b]  => (read(ap.left, state), read(ap.right, state)).mapN(_(_))
-      case l: Lift[F, k, a] => Eval.now(state.get(l.source.key, l.key))
+      case Pure(a)                     => Eval.now(a)
+      case ap: Ap[F, a, b]             => (read(ap.left, state), read(ap.right, state)).mapN(_(_))
+      case l: Lift[F, k, a] @unchecked => Eval.now(state.get(l.source.key, l.key))
     }
   }
 
@@ -84,8 +84,8 @@ object Requests {
     val m2: F[List[(DSKey[_, _], KeyedData[_, _])]] = m.toList.parTraverse { case (ds: Key[k, v], keys) =>
       type K = k
       val nest: F[Map[ds.ds.K2, v]] = keys.toList.toNel match {
-        case None                                 => F.pure(Map.empty[ds.ds.K2, v])
         case Some(k2: NonEmptyList[K] @unchecked) => ds.ds.batch(k2)
+        case _                                    => F.pure(Map.empty[ds.ds.K2, v])
       }
 
       nest.map { m =>