Merge pull request #2 from fluencelabs/bj-category-with-split

Bijection is a Category with split

README.md

@@ -1,3 +1,138 @@
+[![Build Status](https://travis-ci.org/fluencelabs/codec.svg?branch=master)](https://travis-ci.org/fluencelabs/codec) [![Gitter](https://badges.gitter.im/fluencelabs/codec.svg)](https://gitter.im/fluencelabs/codec?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
+
 # Codec
 
-Like bijections, but pure and suitable for `cats`.
+`Codec` is an opinionated library for `cats`-friendly pure (reversible) conversions between types, with possible errors represented with `Either`.
+
+It's cross-built for Scala and Scala.js, and can also be used for other free-of-effect conversions to reach functional composability.
+
+## Motivation
+
+### Use partial functions, track the errors
+
+Often it's useful to do some validation alongside conversion, like in `String => Int`. 
+
+However, this function throws when malformed input is given. Hence `String => Either[Throwable, Int]`, being a total function, should fit better.
+
+In this case, error is reflected in type system. It keeps things pure. We go further, forcing the error to be of type `CodecError`, so that later it's easy to track where it comes from, especially in asynchronous environment.
+
+This uni-direction type is called `fluence.codec.PureCodec.Func` for a fixed `CodecError` error type. Any other error type could be used by extending `fluence.codec.MonadicalEitherArrow[Error]`.
+
+Bidirection type `A <=> B` is composed from two `Func`s and is called `Bijection`.
+
+### Lawful composition
+
+A type `Func[A, B]`, being something like `A => Either[E, B]`, is not very composable on it's own, so we implemented `cats.arrow.ArrowChoice[Func]` for it. You may use `cats.syntax.compose._` or anything like that to receive `andThen` and other lawful functions.
+
+`Bijection[A, B]` is more complex type, so it has only `Compose[Bijection]` typeclass. Finally you can do something like this:
+
+```scala
+import cats.syntax.compose._
+import fluence.codec.PureCodec
+
+val intToBytes: PureCodec[Int, Array[Byte]] = PureCodec[Int, String] andThen PureCodec[String, Array[Byte]]
+```
+
+Errors are handled in monad-like "fail-fast" fashion.
+
+### Benefit from different Monads
+
+In general, functional types conversion could be lazy or eager, be performed in current thread or another. This choice should not affect the logic of conversion, as it's pure.
+
+`PureCodec` may use any  monad to preform execution upon, retaining its nature. The most simple case is strict eager evaluation:
+
+```scala
+import cats.Id
+
+val resEagerSync: Either[CodecError, Array[Byte]] = intToBytes.runF[Id](33)
+
+```
+
+You may use any monad, like `Task`, `Coeval`, `Eval`, `IO`...
+
+### Minimal dependencies
+
+`codec-core` depends only on `cats`. Each particular codec set is moved into separate module.
+
+### Cross compile
+
+In case of complex algorithms, it's worthy to share codebase between platforms. We cross-compile all the codecs possible both to Scala and Scala.js.
+
+## Installation
+
+```scala
+// Bintray repo is used so far. Migration to Maven Central is planned
+resolvers += Resolver.bintrayRepo("fluencelabs", "releases")
+
+val codecV = "0.0.1"
+
+libraryDependencies ++= Seq(
+  "one.fluence" %%% "codec-core" % codecV, // basic types
+  "one.fluence" %%% "codec-bits" % codecV, // scodec-bits conversions for ByteVector 
+  "one.fluence" %%% "codec-circe" % codecV, // json handling with circe
+  "one.fluence" %%% "codec-protobuf" % codecV, // ByteString conversions for both scala and scala.js
+  "one.fluence" %% "codec-kryo" % codecV // typesafe kryo codecs, only for scala
+)
+```
+
+## Example
+
+```scala
+  import cats.syntax.compose._
+  import fluence.codec.PureCodec
+  import fluence.codec.circe.CirceCodecs._
+  import io.circe.{Decoder, Encoder, Json}
+  import scodec.bits.ByteVector
+  import fluence.codec.bits.BitsCodecs._
+
+  // Simple class
+  case class User(id: Int, name: String)
+
+  // Encode and decode with circe
+  implicit val encoder: Encoder[User] =
+    user ⇒ Json.obj("id" → Encoder.encodeInt(user.id), "name" → Encoder.encodeString(user.name))
+
+  implicit val decoder: Decoder[User] = cursor ⇒
+    for {
+      id ← cursor.downField("id").as[Int]
+      name ← cursor.downField("name").as[String]
+    } yield User(id, name)
+
+  // Get codec for encoder/decoder
+  implicit val userJson: PureCodec[User, Json] = circeJsonCodec(encoder, decoder)
+
+  // A trivial string to bytes codec; never use it in production!
+  implicit val stringCodec: PureCodec[String, Array[Byte]] =
+    PureCodec.liftB(_.getBytes, bs ⇒ new String(bs))
+
+  // Convert user to byte vector and vice versa
+  implicit val userJsonVec: PureCodec[User, ByteVector] =
+    PureCodec[User, Json] andThen
+      PureCodec[Json, String] andThen
+      PureCodec[String, Array[Byte]] andThen
+      PureCodec[Array[Byte], ByteVector]
+
+  // Try it with an instance
+  val user = User(234, "Hey Bob")
+
+  // unsafe() is to be used in tests only; it throws!
+  println(userJsonVec.direct.unsafe(user).toBase64)
+  
+  // eyJpZCI6MjM0LCJuYW1lIjoiSGV5IEJvYiJ9
+```
+
+For more real-world examples, see [Fluence](https://github.com/fluencelabs/fluence).
+
+## Roadmap
+
+- `connect[A, B, C]` to compose several Funcs or Bijections
+- `sbt-tut` for docs
+- Implement more codecs
+- Enhance `Func` api with shortcuts to `EitherT` methods
+- Consider improving performance: `EitherT` [is not so fast](https://twitter.com/alexelcu/status/988031831357485056) (at least yet)
+
+## License
+
+Fluence is free software; you can redistribute it and/or modify it under the terms of the GNU Affero General Public License v3 (AGPLv3) as published by the Free Software Foundation.
+
+Fluence includes some [external modules](https://github.com/fluencelabs/codec/blob/master/build.sbt) that carry their own licensing.

build.sbt

@@ -14,7 +14,7 @@ val scalaV = scalaVersion := "2.12.5"
 
 val commons = Seq(
   scalaV,
-  version                   := "0.0.1",
+  version                   := "0.0.2",
   fork in Test              := true,
   parallelExecution in Test := false,
   organization              := "one.fluence",
@@ -22,10 +22,10 @@ val commons = Seq(
   organizationHomepage      := Some(new URL("https://fluence.one")),
   startYear                 := Some(2017),
   licenses += ("AGPL-V3", new URL("http://www.gnu.org/licenses/agpl-3.0.en.html")),
-  headerLicense := Some(License.AGPLv3("2017", organizationName.value)),
+  headerLicense       := Some(License.AGPLv3("2017", organizationName.value)),
   bintrayOrganization := Some("fluencelabs"),
-  publishMavenStyle := true,
-  bintrayRepository := "releases"
+  publishMavenStyle   := true,
+  bintrayRepository   := "releases"
 )
 
 commons
@@ -61,12 +61,12 @@ lazy val `codec-core` = crossProject(JVMPlatform, JSPlatform)
     commons,
     kindProjector,
     libraryDependencies ++= Seq(
-      "org.typelevel" %%% "cats-core"   % Cats1V,
-      "org.typelevel" %%% "cats-laws" % Cats1V % Test,
-      "org.typelevel" %%% "cats-testkit" % Cats1V % Test,
+      "org.typelevel"              %%% "cats-core"                 % Cats1V,
+      "org.typelevel"              %%% "cats-laws"                 % Cats1V % Test,
+      "org.typelevel"              %%% "cats-testkit"              % Cats1V % Test,
       "com.github.alexarchambault" %%% "scalacheck-shapeless_1.13" % "1.1.8" % Test,
-      "org.scalacheck"  %%% "scalacheck" % ScalacheckV % Test,
-      "org.scalatest" %%% "scalatest"    % ScalatestV % Test
+      "org.scalacheck"             %%% "scalacheck"                % ScalacheckV % Test,
+      "org.scalatest"              %%% "scalatest"                 % ScalatestV % Test
     )
   )
   .jsSettings(
@@ -84,9 +84,9 @@ lazy val `codec-bits` = crossProject(JVMPlatform, JSPlatform)
   .settings(
     commons,
     libraryDependencies ++= Seq(
-      "org.scodec"    %%% "scodec-bits" % ScodecBitsV,
-      "org.scalacheck"  %%% "scalacheck" % ScalacheckV % Test,
-      "org.scalatest" %%% "scalatest"    % ScalatestV % Test
+      "org.scodec"     %%% "scodec-bits" % ScodecBitsV,
+      "org.scalacheck" %%% "scalacheck"  % ScalacheckV % Test,
+      "org.scalatest"  %%% "scalatest"   % ScalatestV % Test
     )
   )
   .jsSettings(
@@ -125,8 +125,8 @@ lazy val `codec-kryo` = project
     commons,
     libraryDependencies ++= Seq(
       chill,
-      "com.chuusai"   %% "shapeless"     % ShapelessV,
-      "org.scalatest" %% "scalatest"    % ScalatestV % Test
+      "com.chuusai"   %% "shapeless" % ShapelessV,
+      "org.scalatest" %% "scalatest" % ScalatestV % Test
     )
   )
   .dependsOn(`codec-core-jvm`)
@@ -148,4 +148,3 @@ lazy val `codec-protobuf` = crossProject(JVMPlatform, JSPlatform)
 
 lazy val `codec-protobuf-jvm` = `codec-protobuf`.jvm
 lazy val `codec-protobuf-js` = `codec-protobuf`.js
-

circe/src/main/scala/fluence/codec/circe/CirceCodecs.scala

@@ -22,7 +22,7 @@ import io.circe._
 
 object CirceCodecs {
 
-  implicit def circeJsonCodec[T](encoder: Encoder[T], decoder: Decoder[T]): PureCodec[T, Json] =
+  implicit def circeJsonCodec[T](implicit encoder: Encoder[T], decoder: Decoder[T]): PureCodec[T, Json] =
     PureCodec.liftEitherB[T, Json](
       t ⇒ Right(encoder.apply(t)),
       json ⇒ decoder.decodeJson(json).left.map(f ⇒ CodecError("Cannot decode json value", causedBy = Some(f)))

core/src/main/scala/fluence/codec/MonadicalEitherArrow.scala

@@ -18,7 +18,8 @@
 package fluence.codec
 
 import cats.{Monad, MonadError, Traverse}
-import cats.arrow.{ArrowChoice, Compose}
+import cats.arrow.{ArrowChoice, Category}
+import cats.syntax.arrow._
 import cats.data.{EitherT, Kleisli}
 import cats.syntax.flatMap._
 import cats.syntax.compose._
@@ -32,6 +33,7 @@ import scala.util.Try
  * @tparam E Error type
  */
 abstract class MonadicalEitherArrow[E <: Throwable] {
+  mea ⇒
 
   /**
    * Alias for error type
@@ -114,6 +116,13 @@ abstract class MonadicalEitherArrow[E <: Throwable] {
     )
     def toCodec[F[_]](implicit F: MonadError[F, Throwable]): Codec[F, A, B] =
       Codec(direct.runF[F], inverse.runF[F])
+
+    /**
+     * Splits the input and puts it to either bijection, then merges output.
+     * It could have been achieved with `Strong` typeclass in case it doesn't extend `Profunctor`; but it does.
+     */
+    def split[A1, B1](bj: Bijection[A1, B1]): Bijection[(A, A1), (B, B1)] =
+      mea.split(this, bj)
   }
 
   /**
@@ -250,10 +259,20 @@ abstract class MonadicalEitherArrow[E <: Throwable] {
   implicit def swap[A, B](implicit bijection: Bijection[A, B]): Bijection[B, A] = bijection.swap
 
   /**
-   * Bijection should obey ComposeLaws
+   * Bijection should obey CategoryLaws
    */
-  implicit object catsMonadicalBijectionCompose extends Compose[Bijection] {
+  implicit object catsMonadicalBijectionCategory extends Category[Bijection] {
     override def compose[A, B, C](f: Bijection[B, C], g: Bijection[A, B]): Bijection[A, C] =
       Bijection(f.direct compose g.direct, g.inverse compose f.inverse)
+
+    override def id[A]: Bijection[A, A] = identityBijection
   }
+
+  /**
+   * Splits the input and puts it to either bijection, then merges output.
+   * It could be achieved with `Strong` typeclass in case it doesn't extend `Profunctor`; but it does.
+   */
+  def split[A1, B1, A2, B2](f1: Bijection[A1, B1], f2: Bijection[A2, B2]): Bijection[(A1, A2), (B1, B2)] =
+    Bijection(f1.direct *** f2.direct, f1.inverse *** f2.inverse)
+
 }

core/src/test/scala/fluence/codec/PureCodecBijectionLawsSpec.scala

@@ -17,7 +17,7 @@
 
 package fluence.codec
 
-import cats.laws.discipline.ComposeTests
+import cats.laws.discipline.CategoryTests
 import cats.tests.CatsSuite
 import cats.Eq
 import org.scalacheck.ScalacheckShapeless._
@@ -32,7 +32,7 @@ class PureCodecBijectionLawsSpec extends CatsSuite {
     Eq.instance((x, y) ⇒ directEq.eqv(x.direct, y.direct) && inverseEq.eqv(x.inverse, y.inverse))
 
   checkAll(
-    "PureCodec.Bijection.ComposeLaws",
-    ComposeTests[PureCodec].compose[Int, String, Double, BigDecimal]
+    "PureCodec.Bijection.CategoryLaws",
+    CategoryTests[PureCodec].category[Int, String, Double, BigDecimal]
   )
 }

project/build.properties

@@ -1 +1 @@
-sbt.version = 1.1.2
+sbt.version = 1.1.4