v1.0.0

Release 1.0.0 is the culmination of 7 years of development.

If you are curious about the migration from 0.8.x you'll find the guideline here (tl;dr there should be nothing to worry about as long as you recompile).

Changelog since 0.8.x:

• revamped Cats' instances to match existing conventions (both in Cats as well as in Chimney) (fixed in #443)
  • Transformer, PartialTransformer and partial.Result have all instances that make sense for them
  • conversions from cats.Validated to partial.Result use the same convention as other types (using AsResult type class and asResult extension method introduced in 0.8.0)
  • for partial.Result and PartialTransformer one can combine values using sequential or parallel semantics (read about them in the docs!!!)
  • all instances are tested against Cats disciplines
• further improvements to Cats' instances for Chimney types - added Alternative type class to the list of provided instances, a few missed discipline tests were added (#465)
• provided a flag to disable automatic Option unwrapping by PartialTransformer (#322, addressed by #477) (disabling that behavior by default is not planned)
• added a way to customize how source fields/subtypes are matches against target fields/subtypes (#89 and #480, fixed in #478) - thanks to @saeltz for contributing to the PR as the first contribution!
• restored the behavior from before 0.8.x series when only methods returning Unit could be considered setters (provides a better fix to #424, fixed in #485). If needed non-Unit setters can be opted-in
• detect and report ambiguities with pairing field names (#449, #461, fixed in #485)
• improve error messages when there are def methods or other inherited accessors that could be enabled with a flag (fixed in #485)
• type-level config representation and internal macros overrides get heavily refactored (#490, #491, #492) (breaking change!)
• which unblocked the development of better nested paths (#493):
  • now it is possible to use overrides like withFieldConst(_.adt.matching[ADT.Subtype].either.matchingRight.collection.everyItem.map.everyMapValue, ...)
  • in this first iteration, improved paths to overridden values support only build-in Scala types: Option (matchingSome), Either (matchingLeft, matchingRight), Scala's collections (.everyItem, .everyMapKey, .everyMapValue) but it is planned to extends support for other collections
• suppress WartRemover/Scapegoat warnings (#496, fixe),d in #497)
• deprecate withCoproductInstance in favor or withSealedSubtypeHandled and withEnumCaseHandled (fixed in #500) - old name is still available but it was @deprecated since it uses the term "coproduct" basically unknown outside of library writers crowd
• documentation now has light/dark theme toggle with the default being whatever your system uses
• fixed to internal representation of subtype-matchiung configs (#499, fixed in #504)
• format scaladoc documentation with scalafmt wrap = yes config
• fix a bug that occurred in some cases when using withConstructorPartial (fixed in #508)
• add withContructorEither in PartialTransformers to make it easier to work with smart constructors based on Either[String, Type] (done in #509)
• created an integration API for providing custom optional types and custom collections (#505)
  • extended support for _.matchingSome, _.everyItem, _.everyMapKey,_.everyMapValue to every collection provided through integrations API
• migrated chimney-java-collections through new integration API (#510)
• provided support for transformation of cats.data types like Chain, NonEmptyChain, etc through integrations API (#421, fixed in #511)
• allow providing an override to a field shared between all subtypes of an ADT (sealed, enum) (#512)
• fix rare case of StackOverflow with Scala 3 enums (#528)
• hide the last API intended for internal usage (#540)
• tests Scala CLI snippets (#523, #524, #534) and extract snippet testing to an external library ScalaCLI.md Spec (#525)

v1.0.0-RC1

This release candidate contains all the functionality intended for 1.0.0 launch. Please help us testing it for bugs. If no bugs - requiring changes to API and breaking binary/source compatibility - are found, Chimney 1.0.0 is planned to be released at 23.05.2024. Then it will move from early-semver to proper semantic versioning.

If you are curious about the migration from 0.8.x you'll find the guideline here (tl;dr there should be nothing to worry about as long as you recompile).

Changelog since 0.8.x:

• revamped Cats' instances to match existing conventions (both in Cats as well as in Chimney) (fixed in #443)
  • Transformer, PartialTransformer and partial.Result have all instances that make sense for them
  • conversions from cats.Validated to partial.Result use the same convention as other types (using AsResult type class and asResult extension method introduced in 0.8.0)
  • for partial.Result and PartialTransformer one can combine values using sequential or parallel semantics (read about them in the docs!!!)
  • all instances are tested against Cats disciplines
• further improvements to Cats' instances for Chimney types - added Alternative type class to the list of provided instances, a few missed discipline tests were added (#465)
• provided a flag to disable automatic Option unwrapping by PartialTransformer (#322, addressed by #477) (disabling that behavior by default is not planned)
• added a way to customize how source fields/subtypes are matches against target fields/subtypes (#89 and #480, fixed in #478) - thanks to @saeltz for contributing to the PR as the first contribution!
• restored the behavior from before 0.8.x series when only methods returning Unit could be considered setters (provides a better fix to #424, fixed in #485). If needed non-Unit setters can be opted-in
• detect and report ambiguities with pairing field names (#449, #461, fixed in #485)
• improve error messages when there are def methods or other inherited accessors that could be enabled with a flag (fixed in #485)
• type-level config representation and internal macros overrides get heavily refactored (#490, #491, #492) (breaking change!)
• which unblocked the development of better nested paths (#493):
  • now it is possible to use overrides like withFieldConst(_.adt.matching[ADT.Subtype].either.matchingRight.collection.everyItem.map.everyMapValue, ...)
  • in this first iteration, improved paths to overridden values support only build-in Scala types: Option (matchingSome), Either (matchingLeft, matchingRight), Scala's collections (.everyItem, .everyMapKey, .everyMapValue) but it is planned to extends support for other collections
• suppress WartRemover/Scapegoat warnings (#496, fixed in #497)
• deprecate withCoproductInstance in favor or withSealedSubtypeHandled and withEnumCaseHandled (fixed in #500) - old name is still available but it was @deprecated since it uses the term "coproduct" basically unknown outside of library writers crowd
• documentation now has light/dark theme toggle with the default being whatever your system uses
• fixed to internal representation of subtype-matchiung configs (#499, fixed in #504)
• format scaladoc documentation with scalafmt wrap = yes config
• fix a bug that occurred in some cases when using withConstructorPartial (fixed in #508)
• add withContructorEither in PartialTransformers to make it easier to work with smart constructors based on Either[String, Type] (done in #509)
• created an integration API for providing custom optional types and custom collections (#505)
  • extended support for _.matchingSome, _.everyItem, _.everyMapKey,_.everyMapValue to every collection provided through integrations API
• migrated chimney-java-collections through new integration API (#510)
• provided support for transformation of cats.data types like Chain, NonEmptyChain, etc through integrations API (#421, fixed in #511)
• allow providing an override to a field shared between all subtypes of an ADT (sealed, enum) (#512)

v1.0.0-M7

Changelog:

• fix a bug that occurred in some cases when using withConstructorPartial (fixed in #508)
• add withContructorEither in PartialTransformers to make it easier to work with smart constructors based on Either[String, Type] (done in #509)

This pre-release is the fifth of the planned series of internal cleanups. The series is intended to make sure that when 1.0.0 is finally released it will not have any serious (known) issues that could be only addressed by breaking the backward compatibility. We will be really glad if you tested it, and let us know about any such issues while they are still easy to fix.

v1.0.0-M6

Changelog:

• suppress WartRemover/Scapegoat warnings (#496, fixed in #497)
• deprecate withCoproductInstance in favor or withSealedSubtypeHandled and withEnumCaseHandled (fixed in #500) - old name is still available but it was @deprecated since it uses the term "coproduct" basically unknown outside of library writers crowd
• documentation now has light/dark theme toggle with the default being whatever your system uses
• fixed to internal representation of subtype-matchiung configs (#499, fixed in #504)
• format scaladoc documentation with scalafmt wrap = yes config

This pre-release is the fifth of the planned series of internal cleanups. The series is intended to make sure that when 1.0.0 is finally released it will not have any serious (known) issues that could be only addressed by breaking the backward compatibility. We will be really glad if you tested it, and let us know about any such issues while they are still easy to fix.

v1.0.0-M5

Changelog:

• type-level config representation and internal macros overrides get heavily refactored (#490, #491, #492) (breaking change!)
• which unblocked the development of better nested paths (#493):
  • now it is possible to use overrides like withFieldConst(_.adt.matching[ADT.Subtype].either.matchingRight.collection.everyItem.map.everyMapValue, ...)
  • in this first iteration, improved paths to overridden values support only build-in Scala types: Option (matchingSome), Either (matchingLeft, matchingRight), Scala's collections (.everyItem, .everyMapKey, .everyMapValue) but it is planned to extends support for other collections

This pre-release is the fifth of the planned series of internal cleanups. The series is intended to make sure that when 1.0.0 is finally released it will not have any serious (known) issues that could be only addressed by breaking the backward compatibility. We will be really glad if you tested it, and let us know about any such issues while they are still easy to fix.

v1.0.0-M4

Changelog:

• restore the behavior from before 0.8.x series when only methods returning Unit could be considered setters (provides a better fix to #424, fixed in #485). If needed non-Unit setters can be opted-in
• detect and report ambiguities with pairing field names (#449, #461, fixed in #485)
• improve error messages when there are def methods or other inherited accessors that could be enabled with a flag (fixed in #485)

This pre-release is the fourth of the planned series of internal cleanups. The series is intended to make sure that when 1.0.0 is finally released it will not have any serious (known) issues that could be only addressed by breaking the backward compatibility. We will be really glad if you tested it, and let us know about any such issues while they are still easy to fix.

v1.0.0-M3

Changelog:

• added a way to customize how source fields/subtypes are matches against target fields/subtypes (#89 and #480, fixed in #478) - thanks to @saeltz for contributing to the PR as the first contribution!

This pre-release is the third from the planned series of internal cleanups. The series is intended to make sure that when 1.0.0 is finally released it will not have any serious (known) issues that could be only addressed by breaking the backward compatibility. We will be really glad if you tested it, and let us know about any such issues while they are still easy to fix.

v1.0.0-M2

Changelog:

• further improvements to Cats' instances for Chimney types - added Alternative type class to the list of provided instances, a few missed discipline tests were added (#465)
• provided a flag to disable automatic Option unwrapping by PartialTransformer (#322, addressed by #477) (disabling that behavior by default is not planned)

This pre-release is the second from the planned series of internal cleanups. The series is intended to make sure that when 1.0.0 is finally released it will not have any serious (known) issues that could be only addressed by breaking the backward compatibility. We will be really glad if you tested it, and let us know about any such issues while they are still easy to fix.

v1.0.0-M1

Changelog:

• revamped Cats' instances to match existing conventions (both in Cats as well as in Chimney) (fixed in #443)
  • Transformer, PartialTransformer and partial.Result have all instances that make sense for them
  • conversions from cats.Validated to partial.Result use the same convention as other types (using AsResult type class and asResult extension method introduced in 0.8.0)
  • for partial.Result and PartialTransformer one can combine values using sequential or parallel semantics (read about them in the docs!!!)
  • all instances are tested against Cats disciplines

This pre-release it the first from the planned series of internal cleanups. The series is intended to make sure that when 1.0.0 is finally released it will not have any serious (known) issues that could be only addressed by breaking the backward compatibility. We will be really glad if you tested it, and let us know about any such issues while they are still easy to fix.

v0.8.5

Changelog:

• added quality of life utilities for partial.Result (#446)
• new Chimney logo thanks to @NoemiRozpara! (#447)

Announcement

The past year was fully dedicated to creating a reliable 0.8.x line:

• addressing the tech debt and sorting out the internals - it was needed not only to enable Scala 3 support but also
  to unblock any future work - both new features as well as bugfixes - in a codebase of evergrowing complexity. I'd argue
  that this was more of an issue than the differences between Scala 2 and Scala 3 macro API, even though from the outside
  it might see as if the changes in the macro API were the main showstopper
• providing a support for Scala 3 - it's the most visible outcome of 0.8.0 release
• providing new features - some of them requested years ago! - enabled by the internals refactor:
  • providing better support for Protobuf oneOf transformations
  • allowing Java Beans transformations (well, all classes with public primary constructor) to be customized just like case classes
  • supporting Java's Enums
  • allowing macros to look at inherited properties (opt-in)
  • allowing Patchers to share configration flags through implicits just like transformers
  • allowing users to customize derivation using nested fields (withFieldConst(_.foo.bar.baz, value), see the last example in each section in provided values and computed values)
  • allowing users to provide their own constructor instead of relying on a public primary constructor
  • allowing users to preview (and debug) the whole derivation logic and generated code
• making the experience of working with PartialTransformers smoother, so that people could move away from TransformerF -
  having one dedicated result type make it easier to write reliable code without giving up on optimizations
• providing better integrations for Protobufs and kicking off integration for Java Collections
• stabilizing the API so that every other version would be a breaking change - since 0.8.0-RC1 we started checking for binary
  backward compatibility (as source compatibility is checked by tests)

That work was enabled by the 0.7.x line when we introduced PartialTransformers - it was then that we understood that TransformerF while useful, are

• too complex for most of the users - who only need something slightly better than Either[List[String], A] and working OOTB
• and too constraining for us - while we could assume that F is a monad or an applicative, the blackbox-ness of the arbitrary effect tied our hands when we wanted to optimize the code for the most common cases. Also we had to shove 1 or sometimes 2 extra type classes around in macros (TransformerFSupport and optional TransformerFErrorPathSupport - I wonder how many of you ever tried to provide your own instance for any of them rather than using some of the build-ins).

The work we did back then was both to improve the UX and to make the eventual refactor easier. We had to plan ahead.

Just like we are planning ahead now. We want to get to Chimney 1.0.0 in 2024. This will stabilize the API and behavior for years, and stable libraries is what we need right now.

Getting stable means many good things: users would be able to fearlessly update dependencies, no migration guides from one version to another would be needed, tutorials and examples will not go out of date.

But it also means that whatever API quirks we have will be to stay. At best we could provide a better API and deprecate the old one, but any improvement which would require e.g. changing how implicits works, changing what is enabled by default, optimization requiring different API representation (even if for kinda-internal type) would be rejected.

That's also one of the reasons why 0.8.x line attempted to push out as many features as it could while keeping backward compatibility - to encourage people to try out 0.8.x and give us some feedback. So that we could make the good use of one last breaking change opportunity - the future 1.0.0-RC line - to address as many issues (fixable only with breaking changes) as possible before committing to stability for years.

Mind, that it doesn't mean that the work would stop (although at some point a mature library with a defined scope needs less and less attention). It also doesn't mean that update to 1.0.0 would require of you any serious rewrites - the vast majority of changes that I have in mind right now would not change your code, only how implicits and internal data structures are organized.

Still, some of the current behavior might be undesirable. It might make sense to change it. Perhaps some of the undesirable behavior might come from poor explanation what is the intended use case for e.g. PartialTransformers and lack of best practices and sources on how to use them. Then we will improve the documentation, write blog posts, do presentations. Or perhaps it is a legitimate concern, and changing that behavior for every user would save them more pain than it causes.

But we would only know about your pain points if you test how 0.8.x works for you and gives us some feedback, so if you are using Chimney and have some issues with it, or if something is preventing you from using it, let us know!