Scala 3 Type Classes

A type class defines an abstraction with optional state (fields) and behavior (methods). They provide a another way to implement mixin composition (TraitsInterfacesAndMixinsInScala). The abstraction is valuable for ensuring that all “instances” of the type class follow the same protocol uniformly.

First, we need a trait for the state and behavior we want to add. To keep things simple, we’ll return JSON-formatted strings, not objects from some JSON library (of which there are many…):

// src/main/scala/progscala3/contexts/json/ToJSON.scala
package progscala3.contexts.json

trait ToJSON[T]:
  extension (t: T) def toJSON(name: String, level: Int): String

  protected val INDENTATION = "  "
  protected def indentation(level: Int): (String,String) =
    (INDENTATION * level, INDENTATION * (level+1))

This is the Scala 3 type class pattern. We define a trait with a type parameter and we define extension methods. Although we don’t actually use the type parameter in the body of this particular type class, the parameter will be essential for disambiguating one type class instance, such as the one for Circle, from another, such as the one for Rectangle.

The public method users care about is toJSON. The protected method, indentation, and immutable state, INDENTATION, are implementation details.

The type class pattern solves the limitation discussed above for extension methods alone. We can define and implement an abstraction and we can add arbitrary state as fields.

Now we create instances for our Shapes:

// src/main/scala/progscala3/contexts/typeclass/new1/ToJSONTypeClasses.scala
package progscala3.contexts.typeclass.new1

import progscala3.introscala.shapes.{Point, Shape, Circle, Rectangle, Triangle}
import progscala3.contexts.json.ToJSON

given ToJSON[Point]:                                            
  extension (point: Point) def toJSON(name: String, level: Int): String =
    val (outdent, indent) = indentation(level)
    s""""$name": {
      |${indent}"x": "${point.x}",
      |${indent}"y": "${point.y}"
      |$outdent}""".stripMargin

given ToJSON[Circle]:                                           
  extension (circle: Circle) def toJSON(name: String, level: Int): String =
    val (outdent, indent) = indentation(level)
    s""""$name": {
      |${indent}${circle.center.toJSON("center", level + 1)},
      |${indent}"radius": ${circle.radius}
      |$outdent}""".stripMargin

// And similarly for Rectangle and Triangle

@main def TryJSONTypeClasses() =
  println(Circle(Point(1.0,2.0), 1.0).toJSON("circle", 0))
  println(Rectangle(Point(2.0,3.0), 2, 5).toJSON("rectangle", 0))
  println(Triangle(
    Point(0.0,0.0), Point(2.0,0.0), Point(1.0,2.0)).toJSON("triangle", 0))

The given keyword declares a conversion for ToJSON[Point]. The extension method for ToJSON is implemented as required for point

A given for ToJSON[Circle].

Running TryJSONTypeClasses prints the following:

> runMain progscala3.contexts.typeclass.new1.TryJSONTypeClasses
...
"circle": {
  "center": {
    "x": "1.0",
    "y": "2.0"
  },
  "radius": 1.0
}
...

There’s a flaw with our implementation, though. If we put those shapes in a sequence, shapes, and try shapes.foreach(s ⇒ println(s.toJSON("shape", 0))), we get an error that Shape doesn’t have a toJSON method. Polymorphic dispatch doesn’t work here.

What if we add a given for Shape that delegates to the others?

given ToJSON[Shape]:
  extension (shape: Shape) def toJSON(name: String, level: Int): String =
    shape.toJSON(name, level)

Seems legit, but the compiler says we have an “infinite recursion”. Again, we aren’t actually calling a polymorphic method toJSON defined in the old-fashioned way for the hierarchy. So, the call shape.toJSON(level) attempts to call the extension method recursively.

What about pattern matching on the type of Shape?

given ToJSON[Shape]:
  extension (shape: Shape) def toJSON(name: String, level: Int): String =
    shape match
      case c: Circle    => c.toJSON(name, level)
      case r: Rectangle => r.toJSON(name, level)
      case t: Triangle  => t.toJSON(name, level)

We still get an infinite recursion at runtime, but the compiler can’t detect it! So, instead, let’s call the compiler generated toJSON implementations directly. A synthesized object is output for each specific given:

// src/main/scala/progscala3/contexts/typeclass/new2/ToJSONTypeClasses.scala
...
given ToJSON[Shape]:
  extension (shape: Shape) def toJSON(name: String, level: Int): String =
    shape match
      case c: Circle    =>
        given_ToJSON_Circle.extension_toJSON(c)(name, level)
      case r: Rectangle =>
        given_ToJSON_Rectangle.extension_toJSON(r)(name, level)
      case t: Triangle  =>
        given_ToJSON_Triangle.extension_toJSON(t)(name, level)
...
@main def TryJSONTypeClasses() =
  val c = Circle(Point(1.0,2.0), 1.0)
  val r = Rectangle(Point(2.0,3.0), 2, 5)
  val t = Triangle(Point(0.0,0.0), Point(2.0,0.0), Point(1.0,2.0))
  println("==== Use shape.toJSON:")
  Seq(c, r, t).foreach(s => println(s.toJSON("shape", 0)))
  println("==== call toJSON on each shape explicitly:")
  println(c.toJSON("circle", 0))
  println(r.toJSON("rectangle", 0))
  println(t.toJSON("triangle", 0))

The output of …typeclass.new2.TryJSONTypeClasses (not shown) indicates that calling shape.toJSON and circle.toJSON (for example) now both work as desired, but we are relying on an obscure implementation detail that could change in a future release of the compiler. Note the naming conventions, given_… and extension_…, which we saw previously.

There is an easy fix. We can give names to the givens and then call them:

// src/main/scala/progscala3/contexts/typeclass/new3/ToJSONTypeClasses.scala
...
given ToJSON[Shape]:
  extension (shape: Shape) def toJSON(name: String, level: Int): String =
    shape match
      case c: Circle    => circleToJSON.extension_toJSON(c)(name, level)
      case r: Rectangle => rectangleToJSON.extension_toJSON(r)(name, level)
      case t: Triangle  => triangleToJSON.extension_toJSON(t)(name, level)

given circleToJSON as ToJSON[Circle]:
  ...

Note the as keyword after the name. Instead of the synthesized name given_ToJSON_Circle, it will be circleToJSON, and similarly for the other shapes. We must still use the synthesized method name for the extension method, but at least we have more control over the object name.

At this point, if we still want to simulate polymorphic behavior, consider refactoring the code to move the implementations of the toJSON methods for each concrete Shape to a regular helper object. Then call its methods instead of using the compiler generated objects. See …typeclass.new4.TryJSONTypeClasses in the code examples for one approach.

Finally, note that Point and the concrete subtypes of Shape are not related in the type hierarchy (well, except for AnyRef way at the top). Hence, this extension mechanism is ad hoc polymorphism, because the polymorphic behavior of toJSON is not tied to the type system, as it would be in subtype polymorphism. Subtype polymorphism is nice for allowing parent types to declare behaviors that can can be defined in subtypes. We had to hack around this missing feature for toJSON! For completeness, recall that we discussed a third kind of polymorphism, parametric polymorphism, in AbstractTypesVsParameterizedTypes, where containers like Container[A] behave uniformly for any type A.

Sometimes a type class will define members that make more sense as the analogs of companion object members, rather than instance members. To see this, let’s look at type classes for Semigroup and Monoid. Semigroup generalizes the notion of addition or composition. You know how addition works for numbers, and even strings can be “added”. Monoid adds the idea of a “unit” value. If you add zero to a number, you get the number back. If you add a string to an empty string, you get the first string back.

Here are the definitions for these types:²

// src/script/scala/progscala3/contexts/MonoidTypeClass.scala

trait Semigroup[T]:
  extension (t: T):
    def combine(other: T): T                                         
    def <+>(other: T): T = t.combine(other)

trait Monoid[T] extends Semigroup[T]:
  def unit: T                                                        

given StringMonoid as Monoid[String]:                                
  def unit: String = ""
  extension (s: String) def combine(other: String): String = s + other

given IntMonoid as Monoid[Int]:
  def unit: Int = 0
  extension (i: Int) def combine(other: Int): Int = i + other

Define an instance extension method combine and an alternative operator methods <+> that calls combine. Note that combining one element with another of the same type returns a new element of the same type, like adding numbers. For given instances of the type class, we will only need to define combine.

The definition for unit, i.e., zero for addition of numbers. It’s not defined as an extension method, but an object method, because we only need one instance of the value for all T.

Instances of the type class for String and Int. Note how unit and combine are defined.

The Monoid combine operation is associative, so here are examples of both instances in action.

"2" <+> ("3" <+> "4")             // "234"
("2" <+> "3") <+> "4"             // "234"
StringMonoid.unit <+> "2"         // "2"
"2" <+> StringMonoid.unit         // "2"

2 <+> (3 <+> 4)                   // 9
(2 <+> 3) <+> 4                   // 9
IntMonoid.unit <+> 2              // 2
2 <+> IntMonoid.unit              // 2

Notice how each unit is referenced. This is why we gave these given instances explicit names, so it’s easier to remember what to call them, instead of the default given_Monoid_String, etc.

Finally, we don’t actually need to define separate instances for each numeric type. Here is how to implement it once for a T for which Numeric[T] exists:

given NumericMonoid[T](using num: Numeric[T]) as Monoid[T]:
  def unit: T = num.zero
  extension (t: T) def combine(other: T): T = num.plus(t, other)

2.2 <+> (3.3 <+> 4.4)             // 9.9
(2.2 <+> 3.3) <+> 4.4             // 9.9

BigDecimal(3.14) <+> NumericMonoid.unit
NumericMonoid[BigDecimal].unit <+> BigDecimal(3.14)
//tag::numericdefinition[]

When accessing NumericMonoid[BigDecimal].unit, the type parameter could be inferred when it was used as the argument for the extension method <+>. However, when it was used as the instance to be extended with <+>, the type parameter was required.

Scala 2 Type Classes

To implement the same type class and instances in Scala 2 sytanx (which is still allowed), you write an implicit conversion that wraps the Point and Shape instances in a new instance of a type that has the toJSON method, then call the method.

First, we need a slightly different ToJSON trait, because the extension method code in ToJSON won’t work with Scala 2:

// src/main/scala/progscala3/contexts/typeclass/old/ToJSONOldTypeClasses.scala
package progscala3.contexts.typeclass.old

import scala.language.implicitConversions                       

trait ToJSONOld[T]:
  def toJSON(level: Int): String                                

  protected val INDENTATION = "  "
  protected def indentation(level: Int): (String,String) =
    (INDENTATION * level, INDENTATION * (level+1))

We must enable implicit conversions.

Now this is a regular method. In the previous ToJSON implementation, it was an extension method.

Indiscriminate use of implicit conversions can be confusing for code comprehension and it sometimes leads to unexpected behavior. Therefore, implicit conversions are treated as an optional feature by Scala. This means you must enable the feature explicitly with the import statement used for implicitConversions or use the global -language:implicitConversions compiler flag.

Now here is an implementation of a toJSON type class instances for Scala 2, which also works in Scala 3. We’ll only show the implementations for Point and Circle:

implicit final class PointToJSON(
    point: Point) extends ToJSONOld[Point]:                     
  def toJSON(name: String, level: Int): String =
    val (outdent, indent) = indentation(level)
    s""""$name": {
      |${indent}"x": "${point.x}",
      |${indent}"y": "${point.y}"
      |$outdent}""".stripMargin

implicit final class CircleToJSON(
    circle: Circle) extends ToJSONOld[Circle]:                  
  def toJSON(name: String, level: Int): String =
    val (outdent, indent) = indentation(level)
    s""""$name": {
      |${indent}${circle.center.toJSON("center", level + 1)},
      |${indent}"radius": ${circle.radius}
      |$outdent}""".stripMargin
...

@main def TryJSONOldTypeClasses() =
  val c = Circle(Point(1.0,2.0), 1.0)
  val r = Rectangle(Point(2.0,3.0), 2, 5)
  val t = Triangle(Point(0.0,0.0), Point(2.0,0.0), Point(1.0,2.0))
  println(c.toJSON("circle", 0))
  println(r.toJSON("rectangle", 0))
  println(t.toJSON("triangle", 0))

The type class “instance” that implements ToJSONOld.toJSON for Point. It is called a type class instance following Haskell conventions, but we actually declare a class for it, which can be confusing.

The type class instance that implements toJSON for Circle.

Because these classes are declared as implicit, when the compiler sees circle.toJSON(), for example, it will look for an implicit conversion in scope that returns some wrapper type that has this method.

The output of TryJSONOldTypeClasses works as expected. However, we didn’t solve the problem of iterating through some Shapes and calling toJSON polymorphically. You can try that yourself.

We didn’t declare our implicit classes as cases classes. In fact, Scala doesn’t allow an implicit class to also be a case class. It wouldn’t make much sense anyway, because the extra, auto-generated code for the case class would never be used. Implicit classes have a very narrow purpose. Similarly, declaring them final is recommended to eliminate some potential surprises when the compiler resolves which type classes to use.

If you need to support Scala 2 code for a while, then using the original type class pattern will work for a few versions of Scala 3. However, in most cases, it will be better to migrate to the new type class syntax, because it is more concise and purpose-built, and it doesn’t require implicit conversions.

Rules for Implicit Conversion Resolution

Here is a summary of the lookup rules used by the compiler to find and apply conversions conversions. I’ll use given and given instances to refer to both new and old style conversions:

1. No conversion will be attempted if the object and method combination type check successfully.

2. Only given instances for conversion are considered.

3. Only given instances in the current scope are considered, as well as givens defined in the companion object of the target type.

4. Given conversions aren’t chained to get from the available type, through intermediate types, to the target type. Only one conversion will be considered.

5. No conversion is attempted if more than one possible conversion could be applied and have the same scope. There must be one and only one, unambiguous possibility.

Givens and Imports

In ATasteOfFutures we imported an implicit ExecutionContext, scala.concurrent.ExecutionContext.Implicits.global. The name of the enclosing object Implicits reflects a common convention in Scala 2 for making implicit definitions more explicit in code that uses them, at least if you pay attention to the import statements.

Scala 3 introduces a new way to control imports of givens and implicits, which provides an effective alternative form of visibility, as well as allowing developers to use wild-card imports frequently while restricting if and when givens and implicits are also imported.

Consider the following example adapted from the Dotty documentation:

// src/script/scala/progscala3/contexts/GivenImports.scala

object O1:
  val name = "O1"
  val m(s: String) = s"$s, hello from $name"
  class C1
  given c1 as C1
  class C2
  given c2 as C2

Now consider these import statements:

import O1._             // Imports everything EXCEPT the givens, c1 and c2
import O1.{given _}     // Imports ONLY the givens, c1 and c2
import O1.{given c1}    // Imports just c1 explicitly
import O1.{given _, _}  // Imports everything in O1

A given import selector also brings old style implicits into scope.

What if the given instances are anonymous and you don’t want to use the wild card?

object O2:
  class C1
  given C1
  class C2
  given C2
  given intOrd as Ordering[Int]
  given listOrd[T: Ordering] as Ordering[List[T]]

You can import by type. Note the ? wild card for the type parameter, which means both Ordering givens will be imported:

import O2.{given C1, given Ordering[?]}

Because this is a breaking change in how _ wild cards work for imports, it is being implemented gradually:

• In Scala 3.0 an old-style implicit definition can be brought into scope either by a _ or a given _ wildcard selector.

• In Scala 3.1 an old-style implicit accessed through a _ wildcard import will give a deprecation warning.

• In some version after 3.1, old-style implicits accessed through a _ wildcard import will give a compiler error.

Finally, the older Scala 2 implicit conversions are still allowed, where an implicit def is used, for example:

implicit def doubleToDollars(d: Double): Dollars = Dollars(d)

Unlike the Scala 2 alternative to extension methods, we don’t need an implicit class here, like ArrowAssoc above, because Dollars has all the methods we need. This method would be invoked to do the conversion exactly the same way as the given Conversion[Double,Dollars] above.

Build Your Own String Interpolator

Let’s look at a final example of extension, one that lets us define our own string interpolation capability. Recall from InterpolatedStrings that Scala has several built-in ways to format strings through interpolation. For example:

val (first, last) = ("Buck", "Trends")
println(s"Hello, ${first} ${last}")

There are also StringContext methods named f and raw, where f supports printf format directives and raw doesn’t interpret escape characters:

scala> val pi=3.14159

scala> f"$pi%5.3f or ${pi}%7.5f"
val res0: String = 3.142 or 3.14159

scala> raw"	 $pi 
 $pi again"
val res1: String = t 3.14159 n 3.14159 again

We’ll look at a simplistic implementation of a SQL query compiler named sql. When the compiler sees an expression like sql"SELECT $column FROM $table;", it will be translated to the following:

StringContext("SELECT ", "FROM ", ";").sql(column, table)

Note how the embedded expressions become arguments to sql, while the other string tokens are arguments to StringContext.apply. However, scala.StringContext doesn’t have a sql method, so an implicit conversion to another type or an extension method is required.

Let’s define sql for StringContext. For simplicity, it will only handle SQL queries of the form sql"SELECT columns FROM table;" with the columns and table strings specified as part of the string or using embedded expressions. The extracted column and table names are returned in an instance of a simple case class SQLQuery. It would be possible to use the same approach with a real SQL parser and return a query object for a library like JDBC. I won’t show the whole implementation (which is somewhat of a “hack” for this simple case), but just the declarations:

// src/main/scala/progscala3/contexts/SQLStringInterpolator.scala
package progscala3.contexts

object SimpleSQL:
  case class SQLQuery(columns: Seq[String] = Nil, table: String = "")

  extension (sc: StringContext):
    def sql(values: String*): SQLQuery =
      // Extract the column names and table name.
      SQLQuery(columns, table)

See the SQLStringInterpolator source code for the full details. Here is how to use it:

scala> import progscala3.contexts.SimpleSQL._

scala> val query1 = sql"SELECT one, two, three FROM t1;"
val query1: ...SimpleSQL.SQLQuery = SQLQuery(Vector(one, two, three),t1)

scala> val cols = Seq("four", "five").mkString(", ")
     | val table = "t2"
     | val query2 = sql"SELECT $cols FROM $table;"
val cols: Seq[String] = List(four, five)
val table: String = t2
val query2: ...SQLQuery = SQLQuery(Vector(four, five),t2)

As shown, custom string interpolators can return any type you want, not just a new String, like s, f, and raw return. Hence, they can function as instance factories that are driven by data encapsulated in strings.

The Expression Problem

Let’s step back for a moment and ponder what we just accomplished in the previous example. We added new functionality to an existing library type without editing the source code for it!

This desire to extend modules without modifying their source code is called the Expression Problem, a term coined by Philip Wadler.

Object-oriented programming solves this problem with subtyping, more precisely called subtype polymorphism. We program to abstractions and use derived classes when we need changed behavior. Bertrand Meyer coined the term Open/Closed Principle to describe a principled OOP approach, where base types declare the behaviors as abstract that should be open for extension or variation in subtypes, while keeping invariant behaviors closed to modification. The base types are never modified for extension.

Scala certainly supports this technique, but it has drawbacks. What if it’s questionable that we should have that behavior defined in the type hierarchy in the first place? What if the behavior is only needed in a few contexts, while for most contexts, it’s just a burden that the code carries around?

It can be a burden for several reasons. First, the extra, mostly-unused code is a maintenance burden. Developers have to understand it, even when working on other aspects of the code, so they don’t break it inadvertently. Second, it’s also inevitable that most defined behaviors will be refined over time. Every change to a feature that some clients aren’t using forces unwanted updates on client code.

This problem led to the Single Responsibility Principle, a classic design principle that encourages us to define abstractions and implement types with just a single behavior.

Still, in realistic scenarios, it’s sometimes necessary for an object to combine several behaviors. For example, a service often needs to “mix in” the ability to log messages. Scala makes these mixin features relatively easy to implement, as we saw in TraitsInterfacesAndMixinsInScala. We can even declare instances that mix in traits without first defining a class.

In general, mixins, extension methods, and type classes provide robust and principled solutions to the Open/Closed Principle while allowing the core implementations of types to obey the Single Responsibility Principle.