Should I use "implicit def" or "implicit class" for an API ?

ImplicitClassExample.scala

package implicitclass

import scala.collection.JavaConverters._
import scala.collection.immutable._

import com.typesafe.config.{ Config, ConfigFactory }

trait ConfigSupport {

  def customLoadConfig(): Config = ConfigFactory.load()

}

object ConfigSupport extends ConfigSupport

object ConfigImplicits {

  implicit class RichConfig(val config: Config) extends AnyVal {
    def toMap: Map[String, String] = {
      config.entrySet().asScala.map(entry ⇒ (entry.getKey, entry.getValue.unwrapped().toString)).toMap
    }
  }

}


object UsageWithTrait extends ConfigSupport {
  def test(): Unit = {
    import ConfigImplicits._
    val config = customLoadConfig()
    val map = config.toMap
  }
}

object UsageWithObject {
  def test(): Unit = {
    import ConfigImplicits._
    import ConfigSupport._
    val config = customLoadConfig()
    val map = config.toMap
  }
}

ImplicitDefExample.scala

package implicitdef

import scala.collection.JavaConverters._
import scala.collection.immutable._

import com.typesafe.config.{ Config, ConfigFactory }

trait ConfigSupport {

  def customLoadConfig(): Config = ConfigFactory.load()

  implicit def enrichConfig(config: Config): RichConfig = new RichConfig(config)

}

object ConfigSupport extends ConfigSupport


class RichConfig(val config: Config) extends AnyVal {

  def toMap: Map[String, String] = {
    config.entrySet().asScala.map(entry ⇒ (entry.getKey, entry.getValue.unwrapped().toString)).toMap
  }
}


object UsageWithTrait extends ConfigSupport {
  def test(): Unit = {
    val config = customLoadConfig()
    val map = config.toMap
  }
}

object UsageWithObject {
  def test(): Unit = {
    import ConfigSupport._
    val config = customLoadConfig()
    val map = config.toMap
  }
}

NoTraitImplicitClass.scala

package notraitimplicitclass

import scala.collection.JavaConverters._
import scala.collection.immutable._

import com.typesafe.config.{ Config, ConfigFactory }

object ConfigSupport {

  def customLoadConfig(): Config = ConfigFactory.load()

  implicit class RichConfig(val config: Config) extends AnyVal {
    def toMap: Map[String, String] = {
      config.entrySet().asScala.map(entry ⇒ (entry.getKey, entry.getValue.unwrapped().toString)).toMap
    }
  }

}

object Usage {
  def test(): Unit = {
    import ConfigSupport._
    val config = customLoadConfig()
    val map = config.toMap
  }
}

I'm designing an internal library to simplify config code in our projects. This library will have utility methods (e.g. def customLoadConfig()) and implicit extension methods (e.g. RichConfig#toMap()).

I often see a pattern of providing a trait Foo and a companion object extending that trait, to let users choose between extends Foo or import Foo._ (useful in the Scala REPL). There is an example of this in Scalatra. But I can't put an implicit class Xxx extends AnyVal inside a trait, because value classes "must be a top-level class or a member of a statically accessible object".

I have multiple choices :

• move the implicit class to a separate object, and force users to specifically import that object (see ImplicitClass.scala)
• use an implicit def instead, and move the RichConfig outside the trait (see ImplicitDef.scala)
• stop using a trait and just provide a ConfigSupport object that users will import (see NoTraitImplicitClass.scala)
• stop extending AnyVal and take the negligibel performance hit (in this case, it wouldn't be a problem, since configuration code is usually called only once at startup, but it could be more problematic in performance-critical code that is called in a loop)