JarCastingCirce encoder/decoder implementation for ADT to JSON with a configurable type field.
This library provides an efficient, type safe and macro based ADT to JSON encoder/decoder for circe with configurable JSON type field mappings.
When you have ADTs (as trait and case classes) defined like this
sealed trait TestEvent
case class MyEvent1(anyYourField : String /*, ...*/) extends TestEvent
case class MyEvent2(anyOtherField : Long /*, ...*/) extends TestEvent
// ...
and you would like to encode them to JSON like this:
{
"type" : "my-event-1",
"anyYourField" : "my-data",
"..." : "..."
}
The main objectives here are:
- Avoid JSON type field in Scala case class definitions.
- Configurable JSON type field values and their mapping to case classes. They don't have to be Scala class names.
- Avoid writing circe Encoder/Decoder manually.
- Check at the compile time JSON type field mappings and Scala case classes.
Scala support
- Scala v2.12 / v2.13
- Scala.js v0.6 / v1
Getting Started
Add the following to your build.sbt:
libraryDependencies += "org.latestbit" %% "circe-tagged-adt-codec" % "0.9.1"
or if you need Scala.js support:
libraryDependencies += "org.latestbit" %%% "circe-tagged-adt-codec" % "0.9.1"
Usage
import io.circe._
import io.circe.parser._
import io.circe.syntax._
// This example uses auto coding for case classes.
// You decide here if you need auto/semi/custom coders for your case classes.
import io.circe.generic.auto._
// One import for this ADT/JSON codec
import org.latestbit.circe.adt.codec._
sealed trait TestEvent
//@JsonAdt annotation is required only if you'd like to specify JSON type field value yourself.
// Otherwise it would be the class name
@JsonAdt("my-event-1")
case class MyEvent1(anyYourField : String /*, ...*/) extends TestEvent
@JsonAdt("my-event-2")
case class MyEvent2(anyOtherField : Long /*, ...*/) extends TestEvent
// Encoding
implicit val encoder : Encoder[TestEvent] = JsonTaggedAdtCodec.createEncoder[TestEvent]("type")
val testEvent : TestEvent = TestEvent1("test")
val testJsonString : String = testEvent.asJson.dropNullValues.noSpaces
// Decoding
implicit val decoder : Decoder[TestEvent] = JsonTaggedAdtCodec.createDecoder[TestEvent]("type")
decode[TestEvent] (testJsonString) match {
case Right(model : TestEvent) => // ...
}
Configure and customise base ADT Encoder/Decoder implementation
In case you need a slightly different style of coding of your ADT to JSON, there is an API to change it.
Let's assume that you'd like to produce a bit different JSON like this:
{
"type" : "my-event-1",
"body" : {
"anyYourField" : "my-data",
"..." : "..."
}
}
Then you should specify it with your own implementation:
implicit val encoder: Encoder[TestEvent] =
JsonTaggedAdtCodec.
createEncoderDefinition[TestEvent] { case (converter, obj) =>
// converting our case classes accordingly to obj instance type
// and receiving JSON type field value from annotation
val (jsonObj, typeFieldValue) = converter.toJsonObject(obj)
// Our custom JSON structure
JsonObject(
"type" -> Json.fromString(typeFieldValue),
"body" -> Json.fromJsonObject(jsonObj)
)
}
implicit val decoder: Decoder[TestEvent] =
JsonTaggedAdtCodec.
createDecoderDefinition[TestEvent] { case (converter, cursor) =>
// Reading JSON type field value
cursor.get[Option[String]]("type").flatMap {
case Some(typeFieldValue) =>
// Decode a case class from body accordingly to typeFieldValue
converter.fromJsonObject(
jsonTypeFieldValue = typeFieldValue,
cursor = cursor.downField("body")
)
case _ =>
Decoder.failedWithMessage(s"'type' isn't specified in json.")(cursor)
}
}
Complex ADT definitions and trait inheritance
All the following examples are support for this codec:
sealed trait MyTrait
case class MyCaseClass() extends MyTrait
// case objects
case object MyCaseObject extends MyTrait
// trait inheritance with passing through tags -
// so, direct children of MyTrait and
// direct children of MyChildTrait now
// share the same tags namespace
@JsonAdtPassThrough
sealed trait MyChildTrait extends MyTrait
case class MyChildCaseClass() extends MyChildTrait
case class MyOtherChildCaseClass() extends MyChildTrait
// Now this is has its own decoder/encoder
// and the children of MyIsolatedChildTrait have their own tags
sealed trait MyIsolatedChildTrait extends MyTrait
case class MyIsolatedCaseClass() extends MyIsolatedChildTrait
case class MyIsolatedOtherChildCaseClass() extends MyIsolatedChildTrait
// The same like previous, except here we now define our own tag on a child trait
// (instead of default behaviour where a tag would be a trait name)
@JsonAdt("isolated-trait-2")
sealed trait MySecondIsolatedChildTrait extends MyTrait
Pure enum constants / case objects ADT definitions support
Sometimes you just need tags themselves for declarations like this without any additional type tags:
sealed trait MyEnum
@JsonAdt("tag-1")
case object Enum1 extends MyEnum
@JsonAdt("tag-2")
case object Enum2 extends MyEnum
//...
to produce JSON strings for enum constants in json (instead of objects). To help with this scenario, ADT codec provides the specialized encoder and decoder implementations:
implicit val encoder : Encoder[MyEnum] = JsonTaggedAdtCodec.createPureEnumEncoder[MyEnum]()
implicit val decoder : Decoder[MyEnum] = JsonTaggedAdtCodec.createPureEnumDecoder[MyEnum]()
Licence
Apache Software License (ASL)
Author
Abdulla Abdurakhmanov