Automatic Derivation of Config

By bringing in zio-config-magnolia we avoid all the boilerplate required to define the config. With a single import, Config is automatically derived.

Example

Config

sealed trait X

object X {
  case object A extends X
  case object B extends X
  case object C extends X
  case class  DetailsWrapped(detail: Detail) extends X
  
  case class Detail(firstName: String, lastName: String, region: Region)
  case class Region(suburb: String, city: String)
}

case class MyConfig(x: X)

AutoDerivation

// Setting up imports

import zio._
import zio.config._, 
import zio.config.typesafe._
import zio.config.magnolia._

  import X._

// Defining different possibility of HOCON source

val aHoconSource =
  ConfigProvider
    .fromHoconString("x = A")

val bHoconSource =
  ConfigProvider
    .fromHoconString("x = B")

val cHoconSource =
  ConfigProvider
    .fromHoconString("x = C")

val dHoconSource =
  ConfigProvider
    .fromHoconString(
      s"""
         | x {
         |   DetailsWrapped {
         |    detail  {
         |      firstName : ff
         |      lastName  : ll
         |      region {
         |        city   : syd
         |        suburb : strath
         |     }
         |   }
         |  }
         |}
         |""".stripMargin
    )

// Let's try automatic derivation

aHoconSource.load(deriveConfig[MyConfig])
// res0: Right(MyConfig(A))

bHoconSource.load(deriveConfig[MyConfig])
// res0: Right(MyConfig(B))

cHoconSource.load(deriveConfig[MyConfig])
// res0: Right(MyConfig(C))

dHoconSource.load(deriveConfig[MyConfig])
// res0: Right(MyConfig(DetailsWrapped(Detail("ff", "ll", Region("strath", "syd")))))

NOTE

The fieldNames and class-names remain the same as that of case-classes and sealed-traits.

If you want custom names for your fields, use name annotation.

import zio.config.derivation.name

@name("detailsWrapped")
case class  DetailsWrapped(detail: Detail) extends X

import zio.config._

deriveConfig[MyConfig].mapKey(toKebabCase)

With the above changefirstName and lastName in the above HOCON example can be first-name and last-name respectively.

There are various ways in which you can customise the derivation of sealed traits. This is a bit involving, and more documentations will be provided soon.

Documentation while automatic derivation

With describe annotation you can still document your config while automatically generating the config

import zio.config.magnolia.describe

@describe("This config is about aws")
case class Aws(region: String, dburl: DbUrl)
case class DbUrl(value: String)

This will be equivalent to the manual configuration of:

string("region").zip(string("dburl").to[DbUrl]).to[Aws] ?? "This config is about aws"

You could provide describe annotation at field level

Example:

case class Aws(@describe("AWS region") region: String, dburl: DbUrl)

This will be equivalent to the manual configuration of:

(string("region") ?? "AWS region" zip string("dburl").to[DbUrl]).to[Aws] ?? "This config is about aws"

Custom Config

Every field in a case class should have an instance of DeriveConfig (and not Config) in order for the automatic derivation to work. This doesn't mean the entire design of zio-config is typeclass based. For the same reason, the typeclass DeriveConfig exists only in zio-config-magnolia.

As an example, given below is a case class where automatic derivation won't work, and result in a compile time error: Assume that, AwsRegion is a type that comes from AWS SDK.

import java.time.ZonedDateTime

case class Execution(time: AwsRegion, id: Int)

In this case, deriveConfig[Execution] will give us the following descriptive compile error.

magnolia: could not find Descriptor.Typeclass for type <outside.library.package>.AwsRegion
  in parameter 'time' of product type <your.packagename>.Execution

This is because zio-config-magnolia failed to derive an instance of Descriptor for AwsRegion.

In order to provide implicit instances, following choices are there

import zio.config.magnolia._

implicit val awsRegionConfig: DeriveConfig[Aws.Region] =
  DeriveConfig[String].map(string => AwsRegion.from(string))

Now deriveConfig[Execution] compiles.

Custom descriptors are also needed in case you use value classes to describe your configuration. You can use them together with automatic derivation and those implicit custom descriptors will be taken automatically into account

import zio.config.magnolia._

final case class AwsRegion(value: String) extends AnyVal {
  override def toString: String = value
}

object AwsRegion {
  implicit val descriptor: DeriveConfig[AwsRegion] = 
    DeriveConfig[String].map(AwsRegion(_))
}

Where to place these implicits ?

If the types are owned by us, then the best place to keep implicit instance is the companion object of that type.

final case class MyAwsRegion(value: AwsRegion)

object MyAwsRegion {
  implicit val awsRegionDescriptor: DeriveConfig[MyAwsRegion] =
    DeriveConfig[String]
      .map(
        string => MyAwsRegion(AwsRegion.from(string))
      ) ?? "value of type AWS.Region"
}

However, sometimes, the types are owned by an external library.

In these situations, better off place the implicit closer to where we call the automatic derivation. Please find the example in magnolia package in examples module.

Change Keys (CamelCase, kebab-case etc)

Please find the examples in ChangeKeys.scala in magnolia module to find how to manipulate keys in an automatic derivation such as being able to specify keys as camelCase, kebabCase or snakeCase in the source config.

Scala3 Autoderivation

Works just like scala-2.12 and scala-2.13. If possible, we will make this behaviour consistent in scala-2.12 and scala-2.13 in future versions of zio-config.

Example:

The name of the sealed trait itself is skipped completely by default. However, if you put a name annotation on top of the sealed-trait itself, then it becomes part of the config.

The name of the case-class should be available in config-source, and by default it should the same name as that of the case-class.

sealed trait A
case class B(x: String) extends A
case class C(y: String) extends A

case class Config(a: A) 

With the above config, deriveConfig[A] can read following source.

{
  "a" : {
   "B" : {
      "x" : "abc"
     }
   }
  }
}

// or a.B.x="abc", if your source is just property file

However, if you give name annotation for A, the name of the sealed trait should be part of the config too. This is rarely used.

@name("aaaaa")
sealed trait A
case class B(x: String) extends A
case class C(y: String) extends A

case class Config(a: A) 

With the above config, deriveConfig[A] can read following source.

{
  "a" : {
    "aaaaa" : 
      "B" : {
        "x" : "abc"
     }
   }
  }
}

Similar to scala-2.x, you can give name annotations to any case-class as well (similar to scala 2.x)

Example:

sealed trait A

@name("b")
case class B(x: String) extends A
case class C(y: String) extends A

case class Config(a: A) 

In this case, the config should be

{
  "a" : {
   "b" : {
      "x" : "abc"
     }
   }
  }
}

No guaranteed behavior for scala-3 enum yet

With the current release, there is no guaranteed support of scala-3 enum. Use sealed trait and case class pattern.

No support for recursive config in auto-derivation, but we can make it work

There is no support for auto-deriving recursive config with scala-3. Please refer to examples in magnolia package (not in the main examples module)

Custom Keys

With zio-config-3.x, the only way to change keys is as follows:

// mapKey is just a function in `Config` that pre-existed

val config = deriveConfig[Config].mapKey(_.toUpperCase)

Inbuilt support for pure-config

Many users make use of the label type in HOCON files to annotate the type of the coproduct. Just put @nameWithLabel() in sealed trait name. By default the label name is type, but you can provide any custom name @nameWithLabel("foo")

import zio.config._, typesafe._, magnolia._

@nameWithLabel("type")
sealed trait X
case class A(name: String) extends X
case class B(age: Int) extends X

case class AppConfig(x: X)

val str =
  s"""
   x : {
     type = A
     name = jon
   }
  """

read(deriveConfig[AppConfig] from ConfigProvider.fromHoconString(str))