scalalandio / chimney   0.7.5

Apache License 2.0 Website GitHub

Scala library for boilerplate-free, type-safe data transformations

Scala versions: 3.x 2.13 2.12 2.11
Scala.js versions: 1.x 0.6
Scala Native versions: 0.4 0.3

Chimney Chimney logo

chimney Scala version support

CI build License Join the discussions at

Documentation Status Scaladoc 2.11 Scaladoc 2.12 Scaladoc 2.13 Scaladoc 3

Battle tested Scala library for boilerplate-free data transformations.

In the daily life of a strongly-typed language's programmer sometimes it happens we need to transform an object of one type to another object which contains a number of the same or similar fields in their definitions.

case class MakeCoffee(id: Int, kind: String, addict: String)
case class CoffeeMade(id: Int, kind: String, forAddict: String, at: ZonedDateTime)

Usual approach is to just rewrite fields one by one

val command = MakeCoffee(id = Random.nextInt,
                         kind = "Espresso",
                         addict = "Piotr")
val event = CoffeeMade(id =,
                       kind = command.kind,
                       forAddict = command.addict,
                       at =

While the example stays lean, in real-life code we usually end up with tons of such boilerplate, especially when:

  • we keep separate models of different layers in the system
  • we apply practices like DDD (Domain-Driven-Design) where suggested approach is to separate models of different bounded contexts
  • we use code-generation tools like Protocol Buffers that generate primitive types like Int or String, while you'd prefer to use value objects in your domain-level code to improve type-safety and readability
  • we maintain typed, versioned schemas and want to migrate between multiple schema versions

Chimney provides a compact DSL with which you can define transformation rules and transform your objects with as little boilerplate as possible.

import io.scalaland.chimney.dsl._

val event = command.into[CoffeeMade]
  .withFieldComputed(, _ =>
  .withFieldRenamed(_.addict, _.forAddict)
  // CoffeeMade(24, "Espresso", "Piotr", "2020-02-03T20:26:59.659647+07:00[Europe/Warsaw]")

For computations that may potentially fail, Chimney provides partial transformers.

import io.scalaland.chimney.dsl._
import io.scalaland.chimney.partial._

case class UserForm(name: String, ageInput: String, email: Option[String])
case class User(name: String, age: Int, email: String)

UserForm("John", "21", Some("[email protected]"))
  .withFieldComputedPartial(_.age, form => Result.fromCatching(form.ageInput.toInt))
  .asOption  // Some(User("name", 21, "[email protected]"))

val result = UserForm("Ted", "eighteen", None)
  .withFieldComputedPartial(_.age, form => Result.fromCatching(form.ageInput.toInt))
result.asOption // None
// Iterable("age" -> "For input string: \"eighteen\"", "email" -> "empty value")

The library uses Scala macros underneath, to give you:

  • type-safety at compile-time
  • efficient generated code, almost equivalent to hand-written version
  • excellent compilation error messages
  • minimal overhead on compilation time

Getting started

To include Chimney to your SBT project, add the following line to your build.sbt:

// if you use Scala on JVM-only
libraryDependencies += "io.scalaland" %% "chimney" % chimneyVersion
// if you cross-compile to Scala.js and/or Scala Native
libraryDependencies += "io.scalaland" %%% "chimney" % chimneyVersion

where the latest versions available on Maven for each platform are

Chimney JVM versions
Chimney Scala.js 1.x versions
Chimney Scala.js 0.6 versions
Chimney Scala Native 0.4 versions
Chimney Scala Native 0.3 versions

Library is currently supported for Scala 2.12.x, 2.13.x and 3.x on JVM, SJS 1.x, SN 0.4. Other versions should be considered EOL.

Due to some compiler bugs, it's recommended to use at least Scala 2.12.1.

Trying out with Scala CLI/Ammonite

If you are using Scala CLI you can try out Chimney by adding it with using clause:

//> using scala "2.13.11"
//> using dep "io.scalaland::chimney:0.8.0-RC1"
import io.scalaland.chimney.dsl._

case class Foo(x: String, y: Int, z: Boolean = true)
case class Bar(x: String, y: Int)

object Main extends App {
  println(Foo("abc", 10).transformInto[Bar])
  println(Bar("abc", 10).into[Foo].enableDefaultValues.transform)

or run the Ammonite REPL:

scala-cli --power repl --ammonite --scala "2.13.11" --dependency "io.scalaland::chimney:0.8.0-RC1"
Welcome to the Ammonite Repl 2.5.9 (Scala 2.13.11 Java 17.0.3)
@ case class Foo(x: String, y: Int, z: Boolean = true)
defined class Foo

@ case class Bar(x: String, y: Int)
defined class Bar

@ import io.scalaland.chimney.dsl._
import io.scalaland.chimney.dsl._

@ Foo("abc", 10).transformInto[Bar]
res3: Bar = Bar(x = "abc", y = 10)

@ Bar("abc", 10).into[Foo].enableDefaultValues.transform
res4: Foo = Foo(x = "abc", y = 10, z = true)

If you don't have Scala CLI installed you can use this quick script that downloads coursier and uses it to fetch Ammonite REPL with the latest version of Chimney. It drops you immediately into a REPL session.

curl -s | bash


Chimney documentation is available at

Building documentation locally

For building documentation locally you can use Docker:

docker run --rm -v "$PWD/docs:/docs" sphinxdoc/sphinx:5.3.0 bash -c "pip install sphinx-rtd-theme && make html"

It will build the docs in the ./docs/build/html/ directory.


Thanks to JProfiler (Java profiler) for helping us develop the library and allowing us to use it during development.

Thanks to SwissBorg for sponsoring the development time for this project.