Add PartialUnwrapsOption flag

[MateuszKubuszok]

TODO:

• add tests with and without flag
• add MkDocs documentation explaining the flag
• replace TODO with a proper section link in Scaladocs @see section of the flags methods

---

ATM I am leaning towards adding this flag in 1.0.0. However, I am against enabling it by default:

The issue only arises when one uses Chimney as a compile time proof that some transformation is valid. This is WRONG. Chimney is only able to prove that there exists a path of a least resistance converting value of one type into another.

If the input type is String but the output expects non-empty String - without making it explicitly a distinct type with a smart constructor (e.g. NonEmptyString from Refined/Iron/etc) compile-time logic would not be able to validate that. Same with Ints and non-negative Ints, checking regexps, etc. If types are the same, then anything more than passing the value unchanged can only be verified by runtime tests. Basically, by default A => A conversion always succeeds for every A.

Option, most of the time, is a replacement for nullable values. In a world when null is not supposed to be a thing, verifying that nullable has to be different than null to make it non-nullable is rather obvious and expected outcome. Requiring explicit Option[A] => A (or Option[A] => B) parsing is rather non-standard.

And that's the problem: handling empty Options is a primary reason users try to use PartialTransformers. It is the main use case that advertised the feature on landing page, half the documentation examples, it lowers the barrier to entry for everyone who uses Chimney to decode JSONs or Protobufs into domain models. Disabling it by default would be discouraging as suddenly 90% of use cases would require additional flag. I would stop using Partials myself if I had to do this every time.

If the code performs any sort of validation PartialTransformers helps write that logic - but that logic would inevitably have branches depending on runtime data, and as such Chimney was, is, and will be only removing the boilerplate in the production code, tests still have to be written and run. (For similar reasons I still write JSON roundtrip tests even if I derive codecs with Circe, Play JSON, Jsoniter or whatever - the fact that I used derivation doesn't remove the need to write tests, and writing tests don't undermine usability of code generators).

If one intends to make Option[A] => A "type-safe", I suggest:

• replacing the target A with opaque type or NewType
• optionally, creating a smart constructor for it

then types would enforce a manual intervention.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 89.85%. Comparing base (df35686) to head (40b587d).

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #477      +/-   ##
==========================================
- Coverage   90.05%   89.85%   -0.21%     
==========================================
  Files         124      124              
  Lines        4576     4602      +26     
  Branches      387      375      -12     
==========================================
+ Hits         4121     4135      +14     
- Misses        455      467      +12     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.