Chimney Documentation

Chimney is a battle-tested Scala library designed for data transformations. It facilitates mapping between different data structures (e.g., converting one case class to another).

Supported Platforms:

• Scala versions: 2.13, 3.8.4+
• Runtimes: JVM, Scala.js, Scala Native

**Runtime Requirements (JVM):

• For Scala 2.13 artifacts: JDK 11+
• For Scala 3 artifacts: JDK 17+

Chimney is powered by Hearth.

Several libraries provide pre-built support for Chimney:

• Enumz: Provides integration for working with enumeration types (sealed traits, Scala 3 enums, Java enums, scala.Enumeration) uniformly.
• Neotype: Scala 3 only; provides support for working with opaque types.
• Refined4s: Scala 3 only; provides support for working with opaque types.
• Utils: Provides an integration between ZIO Prelude and Chimney.

The chimney-macro-commons module provides non-Chimney-specific macro utilities that can be used to build other macro libraries. It is a standalone artifact that does not depend on Chimney runtime types.

Key capabilities include:

• Extracting values and nullary defs from any class.
• Extracting public constructors and setters.
• Converting between singleton Type[A] and Expr[A].
• Providing platform-agnostic utilities for common types and expressions.

Note: Since Chimney 2.0.0, Chimney's derivation engine is built on top of Hearth, but chimney-macro-commons remains maintained as a standalone library.

Chimney can transform any type into a target class (like a case class or POJO) by matching field names in the source with constructor arguments in the target.

• Source: Every val can be used as a data source.
• Target: Any class with a public primary constructor (or exactly one public constructor) can be the target.
• Matching: By default, Chimney matches fields by name. It handles cases where the source has extra fields or where fields are in a different order.
• Recursion: Transformations are applied recursively. If a field in the target is a different type, Chimney will attempt to transform it if a valid transformation exists for that pair.

The Chimney DSL tracks two distinct types of configuration at the type level:

• TransformerCfg: Stores information regarding specific field and coproduct overrides. These are typically accompanied by a runtime value (like a constant or a function).
• TransformerFlags: Stores global options that are not tied to a specific field or subtype (e.g., enabling or disabling certain transformation behaviors). These can be shared across derivations in the same scope using TransformerConfiguration.

In Scala 2, these are implemented using whitebox macros to turn field selectors (like _.fieldName) into string singleton types. In Scala 3, this is achieved using transparent inline macros.

Chimney can be used for deep updates in nested structures, similar to how optics or libraries like Quicklens work. You can use the .into[T] DSL to target specific fields deep within a structure and apply constant values using .withFieldConst(path, value).

Common path combinators include:

• .matchingSome: For Option types (targets the value if Some).
• .everyItem: For collections (targets every element).
• .everyMapValue: For Map types (targets every value).
• .everyMapKey: For Map types (targets every key).
• .matching[Subtype]: For type-based filtering.
• .matchingLeft / .matchingRight: For left/right side of structures.

import io.scalaland.chimney.dsl._

foo
  .into[Foo]
  .withFieldConst(_.bar.matchingSome.baz.everyItem.a, 10)
  .withFieldConst(_.bar.matchingSome.baz.everyItem.b, "new")
  .transform

When calling source.transformInto[Target], Chimney follows a specific priority for selecting the transformation logic:

1. User-provided Transformer[Source, Target]: If you have explicitly defined a Transformer in the implicit scope, Chimney will use it first.
2. Automatic Derivation: If no user-provided Transformer is found, Chimney uses a macro to automatically derive the transformation logic.

If no transformation can be generated, Chimney is designed to produce a readable compiler error rather than a generic implicit not found message.

A Total Transformer is used when a conversion from a source type (From) to a target type (To) can be applied to every possible value of the source type. In Chimney, these are represented by the Transformer[From, To] type.

When an implicit Transformer is available in scope, you can use the .transformInto[To] extension method from io.scalaland.chimney.dsl._ to perform the conversion.

import io.scalaland.chimney.Transformer
import io.scalaland.chimney.dsl._

class MyType(val a: Int)
class MyOtherType(val b: String) { override def toString: String = s"MyOtherType($b)" }

// Manual definition of a Total Transformer
val transformer: Transformer[MyType, MyOtherType] = (src: MyType) => new MyOtherType(src.a.toString)

// Usage via extension method
val result = new MyType(10).transformInto[MyOtherType]