Quick Start

Chimney is supported for Scala 2.12, 2.13, 3.3+ on JVM, Scala.js and Scala Native with full feature parity between each version.

The newest stable versions on each platform are:

with newest Scaladoc API documentation available:

To start using the library add to your sbt config:

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

or try it in Scala CLI:

# Scala 2.12
scala-cli repl --scala "2.12.21" --dependency "io.scalaland::chimney::1.10.0"
# Scala 2.13
scala-cli repl --scala "2.13.18" --dependency "io.scalaland::chimney::1.10.0"
# Scala 3
scala-cli repl --scala "3.3.7" --dependency "io.scalaland::chimney::1.10.0"

then import in your codebase:

import io.scalaland.chimney.dsl._

and you are good to go!

case class User(id: UUID, name: String, surname: String)
case class ApiUser(name: String, surname: String)

val userID: UUID = ...
val user: User = ...

// Use .transformInto[Type], when don't need to customize anything...:
val apiUser: ApiUser  = user.transformInto[ApiUser]

// ...and .into[Type].customization.transform when you do:
val user2: User = apiUser.into[User].withFieldConst(_.id, userID).transform

// If yout want to reuse some Transformation (and you don't want to write it by hand)
// you can generate it with .derive:
implicit val transformer: Transformer[ApiUser, User] = Transformer.derive[ApiUser, User]

// ...or with .define.customization.buildTransformer:
implicit val transformerWithOverrides: Transformer[User, ApiUser] = Transformer.define[User, ApiUser]
  .withFieldConst(_.id, userID)
  .buildTransformer

// It works the same way with PartialTransformers and Patchers.

Chimney will take care of generating the boring transformation code, and if it finds something non-obvious, it will give you a nice error message what it needs:

apiUser.transformInto[User]
// Chimney can't derive transformation from ApiUser to User
//
// User
//   id: java.util.UUID - no accessor named id in source type ApiUser
//
// Consult https://chimney.readthedocs.io for usage examples.

But don't you worry! Usually Chimney only needs your help if there is no field in the source value with a matching name or whe the targeted type has a private constructor. Out of the box, it supports:

• conversions between case classes
  • actually, a conversion between any class and another class with a public constructor
  • with an opt-in support for Java Beans
• conversions between sealed traits, Scala 3 enums, Java enums
• conversions between collections
• conversions between Options
• conversions between Eithers
• wrapping/unwrapping AnyVals
• conversions where some transformation can fail in runtime (parsing, smart constructors)
• mergings multiple case classes or tuples into one
  • allowing combining of Options
  • allowing combining of Eithers
  • allowing combining of collections
• patching one case class with another
  • with special handling of Options
  • with special handling of Eithers
  • with special handling of collections
• previewing how Chimney attempts to generate the transformation

And much, much more!

Tip

If you are looking for videos or a tutorials take a look at More sources, videos and tutorials section!

Tip

If you are an advanced user, who wants to learn the difference between automatic derivation and semiautomatic derivation in Chimney, see Automatic, semiautomatic and inlined derivation.

Java collections integration

If you are interested in using java.util.Optional, java.util.Collections, java.util.Maps, java.util.streams and other Java's types, you need to add integration to your project:

// Java collections integrations is released only on JVM Scala!
libraryDependencies += "io.scalaland" %% "chimney-java-collections" % "1.10.0"

and then import:

import io.scalaland.chimney.javacollections._

Tip

See Java collections integration cookbook for more information.

Cats integration

If you are interested in Cats integrations for Partial Transformers, you need to add to your project:

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

import io.scalaland.chimney.cats._

Tip

See Cats integration cookbook for more information.

Protocol Buffers integration

If you want to improve support for types defined in ScalaPB, you need to add to your project:

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

import io.scalaland.chimney.protobufs._

Tip

See Protocol Buffers integration cookbook for more information.