Value Classes in Scala Explained

Introduction

One of the main rules of functional developers is that we should always trust a function’s signature. Hence, when we use functional programming, we prefer to define ad-hoc types to represent simple information such as an identifier, a description, or a currency. Ladies and gentlemen, please welcome the value classes.

The Problem

First, let’s define an example to work with. Imagine we have an e-commerce business and that we model a product to sell using the following representation:

case class Product(code: String, description: String)

So, every product is represented by a code (which can mean some barcode), and a description. So far, so good. Now, we want to implement a repository that retrieves products from a persistent store, and we want to allow our users to search by code and by description:

trait ProductRepository {
  def findByCode(code: String): Option[Product]
  def findByDescription(description: String): List[Product]
}

We cannot avoid using a description in the search by code or a code in the search by description. As we are representing both pieces of information through a String, we can wrongly pass a description to the search by code, and vice versa:

val aCode = "8-000137-001620"
val aDescription = "Multivitamin and minerals"

ProductRepository.findByCode(aDescription)
ProductRepository.findByDescription(aCode)

The compiler cannot warn us of our errors because we represent both pieces of information, i.e. the code and the description, using simple Strings. This fact can lead to subtle bugs, which are very difficult to intercept at runtime as well.

Using Straight Case Classes

However, we are smart developers, and we want the compiler to help us identify such errors as soon as possible. Fail fast, they said. Hence, we define two dedicated types, both for the code, and for the description:

case class BarCode(code: String)
case class Description(txt: String)

The new types, BarCode and Description, are nothing more than wrappers around strings. In jargon, we call them value classes. However, they allow us to refine the functions of our repository to avoid the previous information mismatch:

trait AnotherProductRepository {
  def findByCode(barCode: BarCode): Option[Product] =
    Some(Product(barCode.code, "Some description"))
  def findByDescription(description: Description): List[Product] =
    List(Product("some-code", description.txt))
}

As we can see, it is not possible anymore to search a product by code while accidentally passing a description. Indeed, we can try to pass a Description instead of a BarCode:

val anotherDescription = Description("A fancy description")
AnotherProductRepository.findByCode(anotherDescription)

As desired, the compiler diligently warns us that we are bad developers:

[error] /Users/daniel/Documents/value-types/src/main/scala/ValuesTypes.scala:33:39: type mismatch;
[error]  found   : com.rockthejvm.value.ValuesTypes.Description
[error]  required: com.rockthejvm.value.ValuesTypes.BarCode
[error]   AnotherProductRepository.findByCode(anotherDescription)
[error]                                       ^

However, we can still create a BarCode using a String representing a description:

val aFakeBarCode: BarCode = BarCode("I am a bar-code")

To overcome this issue we must use the smart constructor design pattern. Though the description of the pattern is beyond the scope of this article, the smart constructor pattern hides to developers the main constructor of the class, and adds a factory method that performs any needed validation. In its final form, smart constructor pattern for the BarCode type is the following:

sealed abstract class BarCodeWithSmartConstructor(code: String)
object BarCodeWithSmartConstructor {
  def mkBarCode(code: String): Either[String, BarCodeWithSmartConstructor] =
    Either.cond(
      code.matches("\\d-\\d{6}-\\d{6}"),
      new BarCodeWithSmartConstructor(code) {},
      s"The given code $code has not the right format"
    )
}

val theBarCode: Either[String, BarCodeWithSmartConstructor] =
  BarCodeWithSmartConstructor.mkBarCode("8-000137-001620")

Awesome! We reach our primary goal. Now, we have fewer problems to worry about…or not?

An Idiomatic Approach

The above approach resolves some problems, but it adds many others. In fact, since we are using a class to wrap Strings, the compiler must instantiate a new BarCode and Description every single time. The over instantiation of objects can lead to a problem concerning performance and the amount of consumed memory.

Fortunately, Scala provides an idiomatic way to implement value classes. Idiomatic value classes avoid allocating runtime objects and the problems we just enumerated.

A idiomatic value class is a class (or a case class) that extends the type AnyVal, and declares only one single public val attribute in the constructor. Moreover, a value class can declare def:

case class BarCodeValueClass(val code: String) extends AnyVal {
  def countryCode: Char = code.charAt(0)
}

However, value classes have many constraints: They can define def, but not val other than the constructor’s attribute, cannot be extended, and cannot extend anything but universal traits (for the sake of completeness, a universal trait is a trait that extends the Any type, has only def as members, and does no initialization).

The main characteristic of a value class is that the compiler treats it as a case class at compile-time. Still, at runtime, its representation is equal to the type declared in the constructor. Roughly speaking, the BarCodeValueClass type is transformed as a simple String at runtime.

Hence, due to the lack of runtime overhead, value classes are a valuable tool used in the SDK to define extension methods for basic types such as Int, Double, Char, etc.

def show[T](obj: T): String = obj.toString
println(show(BarCodeValueClass("1-234567-890234")))

val macBookBarCode = BarCodeValueClass("1-234567-890234")
val iPhone12ProBarCode = BarCodeValueClass("0-987654-321098")
val barCodes = Array[BarCodeValueClass](macBookBarCode, iPhone12ProBarCode)

def madeInItaly(barCode: BarCodeValueClass): Boolean = barCode match {
  case BarCodeValueClass(code) => code.charAt(0) == '8'
}

The NewType Library

The NewType library allows us to create new types without the overhead of extra runtime allocations, avoiding the pitfalls of Scala values classes. To use it, we need to import the proper dependency in the build.sbt file:

libraryDependencies += "io.estatico" %% "newtype" % "0.4.4"

It uses the experimental feature of Scala macros. So, it is necessary to enable it at compile-time, using the -Ymacro-annotations. In details, the library defines the @newtype annotation macro:

import io.estatico.newtype.macros.newtype
@newtype case class BarCode(code: String)

The macro expansion generates a new type definition and an associated companion object. Moreover, the library expands the class marked with the @newtype annotation with its underlying value at runtime. So, a @newtype class can’t extend any other type.

Despite these limitations, the NewType library works like a charm and interacts smoothly with IDEs.

Using two @newtypes, one representing a bar-code and one representing a description, we can easily improve the definition of the initial Product class:

@newtype case class BarCode(code: String)
@newtype case class Description(descr: String)

case class Product(code: BarCode, description: Description)

Moreover, creating a new instance of a newtype it’s as easy as creating an instance of a Scala regular type:

val iPhoneBarCode: BarCode = BarCode("1-234567-890123")
val iPhoneDescription: Description = Description("Apple iPhone 12 Pro")
val iPhone12Pro: Product = Product(iPhoneBarCode, iPhoneDescription)

As we can see, the code looks like the original Product definition. However, we altogether avoid the runtime instantiation of the wrapper classes. Such an improvement!

What about smart constructors? If we choose to use a case class, the library will generate the apply method in the companion object. If we want to avoid access to the apply method, we can use a class instead and create our smart constructor in a dedicated companion object:

@newtype class BarCodeWithCompanion(code: String)

object BarCodeWithCompanion {
  def mkBarCode(code: String): Either[String, BarCodeWithCompanion] =
    Either.cond(
      code.matches("\\d-\\d{6}-\\d{6}"),
      code.coerce,
      s"The given code $code has not the right format")
}

val barCodeToString: Coercible[BarCode, String] = Coercible[BarCode, String]
val stringToBarCode: Coercible[String, BarCode] = Coercible[String, BarCode]

val code: String = barCodeToString(iPhoneBarCode)
val iPhone12BarCode: BarCode = stringToBarCode("1-234567-890123")

val doubleToBarCode: Coercible[Double, BarCode] = Coercible[Double, BarCode]

[error] could not find implicit value for parameter ev: io.estatico.newtype.Coercible[Double,in.rcard.value.ValuesClasses.NewType.BarCode]
[error]       val doubleToBarCode: Coercible[Double, BarCode] = Coercible[Double, BarCode]
[error]                                                                  ^

val anotherCode: String = iPhoneBarCode.coerce
val anotherIPhone12BarCode: BarCode = "1-234567-890123".coerce

implicit val eq: Eq[BarCodeWithCompanion] = deriving

Scala 3 Opaque Types Aliases

As many of us might already know, Dotty is the former name of the new major version of Scala. Dotty introduces many changes and enhancements to the language. One of these is opaque type aliases, which addresses the same issue as the previous value classes: Creating zero-cost abstraction.

In effect, opaque types let us define a new type alias with an associated scope. Hence, Dotty introduces a new reserved word for opaque type aliases, opaque:

object BarCodes {
  opaque type BarCode = String
}

To create a BarCode from a String, we must provide one or many smart constructors:

object BarCodes {
  opaque type BarCode = String

  object BarCode {
    def mkBarCode(code: String): Either[String, BarCode] = {
      Either.cond(
        code.matches("\\d-\\d{6}-\\d{6}"),
        code,
        s"The given code $code has not the right format"
      )
    }
  }
}

Inside the BarCodes scope, the type alias BarCode works as a String: We can assign a String to a variable of type BarCode, and we have access to the full API of String through an object of type BarCode. So, there is no distinction between the two types:

object BarCodes {
  opaque type BarCode = String
  val barCode: BarCode = "8-000137-001620"

  extension (b: BarCode) {
    def country: Char = b.head
  }
}

As we can see, if we want to add a method to an opaque type alias, we can use the extension method mechanism, which is another new feature of Dotty.

Outside the BarCodes scope, the compiler treats a String and a BarCode as completely different types. In other words, the BarCode type is opaque with respect to the String type outside the definition scope:

object BarCodes {
  opaque type BarCode = String
}
val anotherBarCode: BarCode = "8-000137-001620"

Hence, in the above example, the compiler diligently warns us that the two types are incompatible:

[error] 20 |  val anotherBarCode: BarCode = "8-000137-001620"
[error]    |                      ^^^^^^^
[error]    |                      Not found: type BarCode

Finally, we can say that the opaque type aliases seem to be the idiomatic replacement to the NewType library in Dotty / Scala 3. Awesome!

Conclusion

Summing up, in this article, we have first introduced the reason why we need the so-called value classes. The first attempt to give a solution uses case classes directly. However, due to performance concerns, we introduced the idiomatic solution provided by Scala. This approach, too, had limitations due to random memory allocations.

Then, we turned to additional libraries, and we found the NewType library. Through the use of a mix of type and companion objects definition, the library solved the value classes problem in a very brilliant way.

Finally, we looked at the future, introducing opaque type aliases from Dotty that give us the idiomatic language solution we were searching for.