Quick Start

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

(Scala 3.3+ was supported on the 1.x line, 2.12 for whole 1.x line, and 2.11 on 0.5.x line)

JDK requirements

On the JVM, since 2.0.0, Chimney's Scala 2.13 artifacts require JDK 11+ and Scala 3 artifacts require JDK 17+ (the macros are built on top of Hearth, which is JDK 11+). Scala.js and Scala Native are unaffected (but compilation still happens on a JVM meeting these requirements).

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" % "2.0.0-M4"
// if you cross-compile to Scala.js and/or Scala Native
libraryDependencies += "io.scalaland" %%% "chimney" % "2.0.0-M4"

or try it in Scala CLI:

# Scala 2.13
scala-cli repl --scala "2.13.18" --dependency "io.scalaland::chimney::2.0.0-M4"
# Scala 3
scala-cli repl --scala "3.8.4" --dependency "io.scalaland::chimney::2.0.0-M4"

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, Java boxed primitives (java.lang.Integer and friends) and other Java's types - since 2.0.0 they are supported out of the box on the JVM. No extra dependency, no import needed (the chimney-java-collections artifact is gone).

Tip

See Java collections integration cookbook for more information.

Cats integration

If you are interested in Cats type class instances for Chimney's types (and conversions between partial.Result and Validated), you need to add to your project:

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

import io.scalaland.chimney.cats._

Conversions to/from cats.data collections (NonEmptyList, Chain, ...) are since 2.0.0 served by a separate library - Kindlings' kindlings-cats-integration - which only needs to be added to the classpath (no import):

libraryDependencies += "com.kubuszok" %%% "kindlings-cats-integration" % "0.3.0"

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" % "2.0.0-M4"
// if you cross-compile to Scala.js and/or Scala Native
libraryDependencies += "io.scalaland" %%% "chimney-protobufs" % "2.0.0-M4"

Since 2.0.0 having the artifact on the classpath is enough for the ScalaPB well-known types (wrappers.*Value, ByteString, Timestamp). The import:

import io.scalaland.chimney.protobufs._

is only needed for the remaining utilities (Empty, the Duration family, empty oneof handling, UnrecognizedEnum, DefaultValue[UnknownFieldSet]).

Tip

See Protocol Buffers integration cookbook for more information.