Here is the release of zio-config 1.0.0-RC23. From now on, we shouldn't see significant API change in zio-config. In the next couple of releases, we will be focussed on fixing bugs if any, take feedback from users and cleaning up the API as much as we can. Please expect another couple of releases in coming weeks as part of making its way to 1.0. The library is planning to hit 1.0 when zio hits 1.0. However these changes shouldn't stop you from using the library in its current state.

Notable Changes

zio-config-magnolia and zio-config-shapeless

Improving documentation

We realise there was far less documentation regarding automatic derivation of configuration description. We have tried to improve the documentation in this release.

https://zio.github.io/zio-config/docs/automatic/automatic_index

There are even more features in zio-config-magnolia and zio-config-shapeless which we are yet to document. However these features are not major ones and you should be good to start using zio-config-magnolia and zio-config-shapeless using the documentation in the current release.

Improving the default behaviours.

Behaviour of List type

For a HOCON source, list("key")(string) used to be a success for non-list value in previous releases.

 {
    key : value
 }

With this PR, this will now be a failure. For HOCON, lists has to be in square brackets.

i.e,

 {
   key : [value]
 }

All other sources remain the same. i.e, a single value can be considered as list as they work on simple delimiters. For example export KAFKA_BROKERS="abc.au" in system environment can be retrieved as a List. i.e, list("KAFKA_BROKERS")(string) will work.

The behaviour is the same regardless of whether you use automatic derivation of configuration description or write manual description.

Behaviour of sealed trait

From now on, default derivation of sealed trait don't require the name of the sealed trait to be part of the config.

For example:

sealed trait A 
case object B extends A
case object C extends A
case class D(e: String) extends A

case class Config(config: A)

Previously descriptor[Config] requires to have the following HOCON file to successfully parse.

{
   config : {
      a : {
        e : "value"
      }
   }
}

With this release, the default behaviour is such that the name of the SealedTrait isn't required anymore.

{
   config : {
        e : "value"
   }
}

This should bring back those users who were a little baffled with this behaviour of zio-config. Again, this behaviour is configurable, and we will produce more documentations into the microsite as soon as possible.

Improving ergonomics on Custom Derivation

When using zio-config-magnolia or zio-config-shapeless, defining an instance of Descriptor has been verbose before. This is now as simple as

 import zio.config.magnolia.DeriveConfigDescriptor.{Descriptor, descriptor}

 implicit val awsRegionDescriptor: Descriptor[Aws.Region] =
   Descriptor[String].xmap(string => AwsRegion.from(string), _.toString)

This will make it easy for users to give any types in their case class as long as they define an implicit instance of Descriptor in the companion object of the type, or in the scope of wherever users are trying to form the descriptor of the entire config.

More details are here: https://zio.github.io/zio-config/docs/automatic/automatic_index#custom-configdescription

Core (zio-config)

Better Error Reporting of Missing Values

It's much preferred users make use of the awesome prettyPrint that zio-config provides for reporting ReadErrors.
This has been available from previous releases. However, in this release we add more details when reporting errors for MissingValues.

    ReadError:
    ╥
    ╠══╦══╗
    ║  ║  ║
    ║  ║  ╠─MissingValue
    ║  ║  ║ path: var2
    ║  ║  ║ Details: value of type string
    ║  ║  ║
    ║  ║  ╠─MissingValue
    ║  ║  ║ path: var3
    ║  ║  ║ Details: value of type string
    ║  ║  ║ 
    ║  ║  ▼
    ║  ║
    ║  ╠─MissingValue
    ║  ║ Details: value of type int
    ║  ║ region: var1
    ║  ▼
    ▼

You can see Details added to the missing value fields. This is quite important when the path are same but the types differ. For example case class Config(currency: Either[Int, String], region: String).
It then produce the following error report, if none of them is provided, for instance.

    ReadError:
    ╥
    ╠══╦══╗
    ║  ║  ║
    ║  ║  ╠─MissingValue
    ║  ║  ║ path: currency
    ║  ║  ║ Details: value of type int
    ║  ║  ║
    ║  ║  ╠─MissingValue
    ║  ║  ║ path: currency
    ║  ║  ║ Details: value of type string
    ║  ║  ║ 
    ║  ║  ▼
    ║  ║
    ║  ╠─MissingValue
    ║  ║ Details: value of type string
    ║  ║ region: key
    ║  ▼
    ▼

Bug Fixes

One of the issues with Optional fields was that, if any of the values in an optional product exist and others are missing, it retrieves as None. Please find the details in this issue:

#356

With this release zio-config produces error specifying all the partial missing values in an optional product (i.e, a case class). In other words, the value is considered optional only if all of the values in the product is missing. zio-config already produce errors when there are format errors in optional value.

There needs to be a re-design in handling optional fields which you can expect in next releases.

PS: Re-ran the release to avoid scaladoc error

zio/zio-config v1.0.0-RC23 on GitHub