Getting started with desert

Desert is a binary serialization library for Scala, focusing on creating small binaries while still enabling binary compatible evolution of the data model.

It is suitable for use cases such as Akka remoting and persistence.

First add desert as a dependency:

libraryDependencies += "io.github.vigoo" %% "desert-core" % "0.2.0"

and optionally some extra bindings:

libraryDependencies += "io.github.vigoo" %% "desert-akka" % "0.2.0"
libraryDependencies += "io.github.vigoo" %% "desert-cats" % "0.2.0"
libraryDependencies += "io.github.vigoo" %% "desert-cats-effect" % "0.2.0"
libraryDependencies += "io.github.vigoo" %% "desert-zio" % "0.2.0"

The most simple use case is to serialize a known type to an array of bytes and read it back:

import io.github.vigoo.desert._
import io.github.vigoo.desert.codecs._
import io.github.vigoo.desert.syntax._

val x = "Hello world"

val dataOrFailure = serializeToArray(x)
// dataOrFailure: Either[DesertFailure, Array[Byte]] = Right(
//   value = Array(22, 72, 101, 108, 108, 111, 32, 119, 111, 114, 108, 100)
// )

val y = dataOrFailure.flatMap(data => deserializeFromArray[String](data))
// y: Either[DesertFailure, String] = Right(value = "Hello world")

Codecs

This works because there is an implicit BinaryCodec for String in scope, imported from the codecs package. Read the codecs page to learn about the available codecs and how to define custom ones.

Low level input/output

The above example shows the convenient functions to work on arrays directly, but they have a more generic version working on the low level BinaryInput and BinaryOutput interfaces. These are described on the input/output page.

Evolution

One of the primary features of the library is the support for evolving the data model. The possibilities are described on a separate page.

Type registry

For cases when the exact type to be deserialized is not known at compile type, the possibilities can be registered to a type registry.

Integrations

There are three additional modules providing integrations to different environments:

• Akka codecs and Akka Serializer implementation
• Cats Effect defining the serialization/deserialization as an effect
• ZIO defining the serialization/deserialization as an effect and some codecs