Better support for collections outside Scala's std lib

[MateuszKubuszok]

Java collections module introduced on 0.8.0 solved some problems:

• provided support for Java optional type (java.util.Optional) similar to support for scala.Option
• provided support for Java collections

It has however a few drawbacks:

• it uses TransformerOrUpcast type to avoid issues with automatic vs semiautomatic derivation (prevents having to pick between 2 imports, one for automatically derived internal types and one for only semiautomatically derived)
• it only handles Scala StdLib <=> Java Collections, or Java Collections <=> Java Collections
• if we introduced support for e.g. Cata NonEmpty collection we could convert Cats' NonEmptyList to Scala's List and Scala's List to Java's List but not Cats' NonEmptyList to Java's list which might be counterintuitive
• problem would got even worse if someone wanted to add support for more collections from some other library

To handle it, the best solution would be to:

• create a typeclass for optional types
• create a typeclass for iterating over the collection
• create a typeclass for creating the collection
• define implicits using these typeclasses in core module (allowing to select automatic or semiautomatic support)
• make Java Collections module only a collections of instances for iterating and building collections
• allow creating instances for NonEmpty* Cats collection in some sane manner

This would be a breaking change, so it should not be merged as a part of 0.8.x but it can become a part of future 1.0.0-RC line.

TODO:

• define new type classes
• define new implicits (both automatic and semiautomatic) based on these type classes
  • test that these implicits work and do not create conflicts!
• define instances in Java Collections module
  • test them
• remove old solution
  • optionally make some "old" types deprecated aliases to the new types
• document changes in docs
  • document how to provide support for custom Option (update existing section) or custom collection (create a new section)

[codecov]

Codecov Report

Attention: Patch coverage is 0% with 6 lines in your changes are missing coverage. Please review.

Project coverage is 90.08%. Comparing base (a85aec3) to head (d070c16).
Report is 10 commits behind head on master.

Files	Patch %	Lines
...calaland/chimney/integrations/TotalFactoryOf.scala	0.00%	4 Missing ⚠️
...io/scalaland/chimney/integrations/IteratorOf.scala	0.00%	1 Missing ⚠️
...laland/chimney/integrations/PartialFactoryOf.scala	0.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #444      +/-   ##
==========================================
+ Coverage   90.06%   90.08%   +0.01%     
==========================================
  Files         125      128       +3     
  Lines        4763     4761       -2     
  Branches      430      426       -4     
==========================================
- Hits         4290     4289       -1     
+ Misses        473      472       -1     

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

[MateuszKubuszok]

I have a better idea now:

• define new type classes (iteration, total builder, partial builder)
• define something similar to IterableOrArray in macros logic which would fetch these type classes
• handle code generation inside a macro

This collection-awareness would let us define something like withFieldComputed(_.foo.eachIndex.bar.eachMapValue.baz, a => ...) in the future.

[MateuszKubuszok]

This one will be much easier to implement one #490 lands

[MateuszKubuszok]

Postponed until #493 lands - then providing integrations would not require providing nested path improvements in the same PR.

[MateuszKubuszok]

Closed in favor of #505