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