circe-derivation

This library provides macro-supported derivation of circe's type class instances. It differs from circe-generic in that this derivation is not based on Shapeless's generic representation of case classes and ADTs, and it is not intended to be as fully featured as io.circe.generic. Notably fully automatic derivation is a non-goal. The only targeted remaining feature for parity is constructor renaming.

In return for losing automatic derivation you get a library that has no dependencies apart from circe-core, should compile much more quickly in most cases, and supports some classes that circe-generic doesn't (e.g. Scrooge-generated representations of Thrift structs).

Who is this for?

There are already a lot of ways to define encoders and decoders in circe (or to avoid defining them using fully-automatic derivation). In general users who want to use generic derivation should stick to circe-generic, which is well-tested, robust, and provides a clear path from automatic generic derivation (which can be useful for initial exploration or in relatively simple applications) to semi-automatic derivation (which has some syntactic overhead but tends to compile much more quickly and to be easier to reason about).

Users who want the generic derivation experience but need particular functionality that isn't provided in circe-generic may be interested in circe-generic-extras, which supports transforming member names, using default values, etc. (at the expense of even slower compile times).

This library is for people who don't care about the full generic derivation experience but just want fast builds and instances that stay in sync with their definitions, and who don't mind a bit of boilerplate (a couple of lines per case class).

Note that the io.circe.derivation API is almost identical to io.circe.generic.semiauto, and in many situations it can be used as a drop-in replacement. If you're currently using circe-generic's deriveEncoder and deriveDecoder for case classes, but are still suffering from slow compilation, adding a circe-derivation dependency and switching the imports is probably worth a try.

Contributors and participation

This project supports the Scala code of conduct and we want all of its channels (Gitter, GitHub, etc.) to be welcoming environments for everyone.

Please see the circe contributors' guide for details on how to submit a pull request.

License

circe-derivation is licensed under the Apache License, Version 2.0 (the "License"); you may not use this software except in compliance with the License.

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.