Pushka is a serialization library implemented without any runtime reflection. It created to reach well human readability of output JSON and good performance. Pushka works well both on Scala (2.10, 2.11, 2.12) and Scala.js.
-
The most of serialization libraries write case classes "as is". For example, if we have
Optionvalue it will be written with some kind of wrapper. In the case of sealed traits, most libraries write metadata: trait name and case class name. This makes JSON unreadable by human and makes it useless for creating public API. We want to achieve high human readability of output JSON: no wrappers if possible, no metadata ever. -
Codebase simplicity. In our work, we encountered that some libraries based on implicit macroses (including shapeless based) fails on our data. In this project, we want to make the code as simple as possible to find bugs more faster.
-
High performance. Minimum runtime overhead. See Boopickle benchmarks for comparison with other similar libraries.
Add Pushka dependency to your project.
// For Scala.js
libraryDependencies += "com.github.fomkin" %%% "pushka-json" % "0.8.0"
// For Scala.jvm
libraryDependencies += "com.github.fomkin" %% "pushka-json" % "0.8.0"Pushka uses macro annotations which implemented in macro paradise plugin. Unfortunately, it can't be added transitively by Pushka dependency, so you need to plug it manually.
addCompilerPlugin("org.scalamacros" % "paradise" % "2.1.0" cross CrossVersion.full)Let's define types we want to write to JSON.
import pushka.annotation._
@pushka case class User(
email: String,
name: Option[String],
role: Role
)
@pushka sealed trait Role
object Role {
case object Moderator extends Role
case object Accountant extends Role
case class Group(xs: Seq[Role]) extends Role
}Ok. Now let's create data and write it into JSON
import pushka.json._
val data = User(
email = "[email protected]",
name = None,
role = Role.Accountant
)
println(write(data)){
"email": "[email protected]",
"role": "accountant"
}Ok. Change user's role.
data.copy(role = Role.Group(Role.Accountant, Role.Moderator)){
"email": "[email protected]",
"role": {
"group": ["accountant", "moderator"]
}
}Add user name.
data.copy(name = Some("Jonh Doe")){
"email": "[email protected]",
"name": "John Doe",
"role": {
"group": ["accountant", "moderator"]
}
}Now, in the opposite direction. Let's read JSON.
val json = """
{
"email": "[email protected]",
"name": "John Doe",
"role": {
"group": ["accountant", "moderator"]
}
}
"""
assert {
read[User](json) == User(
email = "[email protected]",
name = Some("Jonh Doe"),
role = Role.Group(Role.Accountant, Role.Moderator)
)
} What if we add the new field to class and try to read JSON written to KV storage with an old version of the class? An exception will be thrown. To avoid this behavior add the new field with a default value.
@pushka case class User(
email: String,
name: Option[String],
role: Role,
photoUrl: String = "http://example.com/images/users/dafault.jpg"
)Pushka allows to define the key that a field is serialized with via a @key annotation.
@pushka
case class Log(@key("@ts") timestamp: String, message: String)Case classes with one field are written without object wrapper by default. To avoid this behavior use @forceObject annotation.
@pushka case class Id(value: String)
write(Id("9f3ce5")) // "9f3ce5"
@pushka @forceObject case class Id(value: String)
write(Id("9f3ce5")) // { "value": "9f3ce5" }Obviously Map[K, V] should be written as {} and this is true when K is String, Int, Double or UUID. But several K types can't be written as JSON object key. Consider case class Point(x: Int, y: Int). This type will be written to JSON object. In this case Map[Point, T] will be written as a sequence of tuples.
@pushka case class Point(x: Int, y: Int)
val m: Map[Point, String] = Map(
Point(0,1) -> "John",
Point(1,0) -> "Jane"
)
write(m)[
[ { "x": 1, "y": 0 }, "John" ],
[ { "x": 0, "y": 1 }, "Jane" ]
]If you want to write such maps as {} you should prove that K type can be written as string.
@pushka case class Point(x: Int, y: Int)
object Point {
implicit val pointOk = new puska.ObjectKey[Point] {
def stringify(value: Point): String = s"${value.x}:${value.y}"
def parse(s: String): Point = {
val Array(x, y) = s.split(":")
Point(x.toInt, y.toInt)
}
}
}
val m: Map[Point, String] = Map(
Point(0,1) -> "John",
Point(1,0) -> "Jane"
)
write(m){
"0:1": "John",
"1:0": "Jane"
}Sometimes we want to write objects in a special way. Just define your own reader/writer for your type.
import pushka.RW
import pushka.Ast
case class Name(first: String, last: String)
object Name {
val Pattern = "(.*) (.*)".r
implicit val rw = new pushka.RW[Name] {
def write(value: Name): Ast = {
Ast.Str(s"${value.first} ${value.last}")
}
def read(ast: Ast): Name = ast match {
case Ast.Str(Pattern(first, last)) => Name(first, last)
case _ => throw new Exception("It's wrong!")
}
}
}
// ...
write(User("John", "Doe"))"John Doe"Code released under Apache 2.0 license. See LICENSE.