Chimney Files

Why 2.0.0?

Chimney was the first library that used sanely-automatic derivation to deliver better error messages, more optimal code, shorter compilation time - but it relied on some implicit priorities that got changed in 3.7.0. Code was adjusted to use new macro APIs that should be stable for the future but it forced us to break the bytecode backward-compatibility.

Since that door was opened (you had to recompile anyway), we used the opportunity to also:

• clean up internal representations
• optimize the runtime utilities used by the macros
• make use of Hearth macro plugins, so that importing implicits is less needed

It makes it the best Chimney version, that realized all of my ambitions about this library, and hopefully the new solutions will let it stay useful in the years to come with no further rewrites.

[!Note]

Scala 2.12 is dropped in the 2.x line. The 2.x artifacts are published for Scala 2.13 and Scala 3 only. If you need Scala 2.12 support, please stay on the latest 1.x release.

The Scala 3 artifacts of the 2.x line target Scala 3.9.0 (LTS) and JDK 17+ (the Scala 2.13 artifacts still target JDK 11+), following Hearth's own JDK 11+ baseline. Make sure your runtime matches. Since 3.9.0 is the new LTS, the minimum required Scala 3 version will stay at 3.9.x from now on.

[!note] As announced earlier, I have stepped down from actively maintaining Chimney. The Hearth migration and the 2.0.0 release are the last large effort I intend to make on this project — going forward, I intend to keep Chimney compatible with new Scala versions, but I do not plan to actively develop new features or fixes myself. No fixes from 2.0.0 will be backported to the 1.x line by me, though I am happy to share knowledge, mentor new contributors, review and merge PRs for both 1.x backports and new 2.x features/improvements from anyone willing to contribute. It's a healthy project, where most demanded things already landed and only some edge cases might need a correction.

Changelog (since 1.x):

• replaced the Vector[Any]-backed RuntimeDataStore with a cons-cell linked list (#602) - DSL chain construction (.withFieldConst, .withFieldComputed, etc.) replaces the per-step Vector overhead with a single-cons-cell prepend; additionally, the macros try to flatten DSL chains at compile time into a single pre-initialized array allocation (O(1) allocations when the whole chain is visible to the macro); the store materializes to an Array lazily on first indexed access, keeping lookup O(1)
• scoped Scala 3 path extension methods with context functions (#770) - path extensions (matching, everyItem, everyMapKey, everyMapValue, matchingSome, matchingLeft, matchingRight) are no longer available on every value once dsl.* or syntax.* is imported; they now require a ChimneySelector given, which is only provided inside DSL selector lambdas — not a breaking change since selector functions are inline macro parameters
• bumped Scala 3 to 3.9.0 (LTS), Hearth to 0.4.2, Kindlings to 0.3.2
• migrated the build to sbt 2.x
• bugfixes:
• [#935] - withEnumCaseHandled override was silently dropped when the target type was Option[T]
• migrated the macro backend from chimney-macro-commons to Hearth 0.4.1 (#903) - the whole derivation engine now runs on Hearth's cross-platform metaprogramming primitives, sharing the macro-utilities layer with other Hearth-based libraries; this also fixes several long-standing 1.x bugs that were resolved on the Hearth line (see the regression tests below)
• added map/contramap combinators (and the invariant imapFirst/imapSecond, imapDomain/imapDto) to Transformer, PartialTransformer, Iso and Codec by @danicheg (#913, re-lands @danicheg's original [#591]) - adapt an existing type class instance without re-deriving it; the PartialTransformer variants thread the failFast flag through
• added an opt-in derivation policy (#909) - -Xmacro-settings:chimney.policy.* (plus the io.scalaland.chimney.policy.allowDerivationForChimney import) let you gate automatic structural derivation to explicitly allowed scopes, so accidental deep derivations become compile-time errors
• added a Hearth-style debugging API (#908):
• import io.scalaland.chimney.debug._ places a LogDerivation implicit in scope, printing the derivation log per-file without touching the transformation
• -Xmacro-settings:chimney.logDerivation=true enables it project-wide
• -Xmacro-settings:chimney.timeout=30s overrides the macro-expansion timeout
• bugfixes (#914):
• [#707] - derive between a generic and a non-generic sealed hierarchy (an abstract type parameter on the source no longer drops every subtype)
• [#718] - relativize the renamed-field source path for recursive derivation (nested withFieldRenamed ending in everyItem/matchingSome/etc. now compiles)
• [#765] - drop the stray } in the ambiguous-override withFieldRenamed suggestion
• added regression tests for [#739], [#899] and [#720] (#919) - three bugs reported against 1.x that are already fixed on the 2.0.0/Hearth line, now guarded so they cannot silently regress
• rewrite API to not rely on the pattern that breaks in 3.7.0 (#713 for Scala 3.7+, [#753] for Scala 2.13.17+)
• cleanup the API (#712, [#713])
• remove deprecated withCoproduct methods
• remove .toPartialResult since .asResult is available (since 0.8.5)
• rework internal type-level config representation (which should not be used directly, but which has to be publicly visible to work)
• remove __mergeResultNullable method (which was documented to not be used but which was publicly visible, or at least package visible due to historical reasons)
• fix typo in Protobuf support trait name
• make com.google.protobuf.ByteString and com.google.protobuf.ByteValue TotallyBuildIterables (which are more flexible than just conversion to underlying type)
• remove unneeded implicits from java-collections Maps' implementation signatures
• rewrite API to not rely on the pattern that breaks in 3.7.0 (#713 for Scala 3.7+, [#753] for Scala 2.13.17+)
• cleanup the API (#712, [#713])
• remove deprecated withCoproduct methods
• remove .toPartialResult since .asResult is available (since 0.8.5)
• rework internal type-level config representation (which should not be used directly, but which has to be publicly visible to work)
• remove __mergeResultNullable method (which was documented to not be used but which was publicly visible, or at least package visible due to historical reasons)
• fix typo in Protobuf support trait name
• make com.google.protobuf.ByteString and com.google.protobuf.ByteValue TotallyBuildIterables (which are more flexible than just conversion to underlying type)
• remove unneeded implicits from java-collections Maps' implementation signatures
• rewrite API to not rely on the pattern that breaks in 3.7.0 (#713)
• cleanup the API (#712, [#713])
• remove deprecated withCoproduct methods
• remove .toPartialResult since .asResult is available (since 0.8.5)
• rework internal type-level config representation (which should not be used directly, but which has to be publicly visible to work)
• remove __mergeResultNullable method (which was documented to not be used but which was publicly visible, or at least package visible due to historical reasons)
• fix typo in Protobuf support trait name
• make com.google.protobuf.ByteString and com.google.protobuf.ByteValue TotallyBuildIterables (which are more flexible than just conversion to underlying type)
• remove unneeded implicits from java-collections Maps' implementation signatures

It contains also all the bugfixes and improvements implemented up to 1.11.0.