NewTypes for Scala with no runtime overhead.

If you are using SBT, add the following line to your build file -

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

Make sure you have macro-paradise enabled

• for Scala 2.13.0-M3 and lower add the following line to your build file

addCompilerPlugin("org.scalamacros" % "paradise" % "2.1.1" cross CrossVersion.full)

• for Scala 2.13.0-M4 and above via compiler flag -Ymacro-annotations

For Maven or other build tools, see the Maven Central badge at the top of this README.

For generating newtypes via the @newtype macro, see @newtype macro For non-macro usage, see the section on Legacy encoding.

As of newtype 0.2, you can now encode newtypes using the @newtype macro. Its implementation and usage aligns closely with idiomatic Scala syntax, so IDE support just works out of the box.

import io.estatico.newtype.macros.newtype

package object types {

  @newtype case class WidgetId(toInt: Int)
}

This expands into a type and companion object definition, so newtypes must be defined in an object or package object.

The example above will generate code similar to the following -

package object types {
  type WidgetId = WidgetId.Type
  object WidgetId {
    type Repr = Int
    type Base = Any { type WidgetId$newtype }
    trait Tag extends Any
    type Type <: Base with Tag

    def apply(x: Int): WidgetId = x.asInstanceOf[WidgetId]

    implicit final class Ops$newtype(val $this$: Type) extends AnyVal {
      def toInt: Int = $this$.asInstanceOf[Int]
    }
  }
}

You can also create newtypes which have type parameters -

@newtype case class EitherT[F[_], L, R](x: F[Either[L, R]])

Note that it is impossible to have your newtype extend any types, which makes sense since it has its own distinct type at compile time and at runtime is just the underlying value.

Also, since the @newtype annotation gives your type a distinct type at compile-time, primitives will naturally box as they do when they are applied in any generic context. See the following section on @newsubtype for unboxed primitive newtypes.

As of newtype 0.4 you now have access to the @newsubtype macro. Its usage is identical to @newtype. The difference is that it functions as a subtype of the underlying type as opposed to having a completely different type at compile time. This may or may not be desirable, and it's recommended to use @newtype if you're not entirely sure you actually need @newsubtype.

The difference in the generated code is that @newsubtype defines its Base type defined as -

type Base = Repr

The main benefit of @newsubtype is that primitives are unboxed. For example, the following @newtype definition will box the Int, making it a java.lang.Integer at runtime -

@newtype case class Foo(x: Int)

However, the following @newsubtype definition will be a primitive int at runtime -

@newsubtype case class Bar(x: Int)

Note however that calling getClass on a newsubtype will fool you -

scala> Bar(1).getClass
res2: Class[_ <: Bar] = class java.lang.Integer

Reason is that scalac boxes unnecessarily when calling getClass, see scala/bug#10770

We can confirm that we do in fact have a primitive int at runtime back by inspecting the byte code -

scala> class Test { def test = Bar(1) }
scala> :javap Test

...
  public int test();
...

Another "feature" of @newsubtype is that its values can be passed to functions which accept its Repr type without needing to convert them first -

scala> def half(b: Int): Int = b / 2
scala> half(Bar(12))
res6: Int = 6

Note that this feature can be undesirable since the newsubtype will be automatically unwrapped, even when you might not mean to. Again, unless you have a good reason to use @newsubtype, it's recommend to use @newtype by default.

This library gives you a few choices when it comes to defining smart constructors and accessor methods for your newtypes. Efforts have been made to keep things idiomatic. Note that extractors (unapply methods) are not generated by newtypes.

Using case class gives us a smart constructor (an apply method on the companion object) that will accept a value of type A and return the newtype N.

@newtype case class N(a: A)

You also get an accessor extension method to get the underlying A. Note that you can prevent this by defining the field as private.

@newtype case class N(private val a: A)

Using class will not generate a smart constructor (no apply method). This allows you to specify your own. Note that new never works for newtypes and will fail to compile.

If you wish to generate an accessor method for your underlying value, you can define it as val just as if you were dealing with a normal class.

@newtype class N(val a: A)

If you need to define your own smart constructor, use the .coerce extension method to cast to your newtype.

import io.estatico.newtype.ops._

@newtype class Id(val strValue: String)

object Id {
  def fromString(str: String): Either[String, Id] = {
    if (str.isEmpty) Left("Id cannot be empty")
    else Right(str.coerce)
  }
}

Defining extension methods are as simple as defining normal methods in any class -

@newtype case class OptionT[F[_], A](value: F[Option[A]]) {

  def fold[B](default: => B)(f: A => B)(implicit F: Functor[F]): F[B] =
    F.map(value)(_.fold(default)(f))

  def cata[B](default: => B, f: A => B)(implicit F: Functor[F]): F[B] =
    fold(default)(f)

  def map[B](f: A => B)(implicit F: Functor[F]): OptionT[F, B] =
    OptionT(F.map(value)(_.map(f)))
}

The companion object works just as you'd expect. You can place your type class instances there and implicit resolution just works.

Companion objects also contain special deriving and derivingK methods to auto-derive instances for you if one exists for your underlying type. This is similar to GHC Haskell's GeneralizedNewtypeDeriving extension.

deriving is used for type classes whose type parameter is not higher kinded.

@newtype case class Text(s: String)
object Text {
  implicit val arb: Arbitrary[Text] = deriving
}

derivingK is used for type classes whose type parameter is higher kinded.

@newtype class Nel[A](val toList: List[A])
object Nel {
  def apply[A](head: A, tail: List[A]): Nel[A] = (head +: tail).coerce[Nel[A]]
  implicit val functor: Functor[Nel] = derivingK
}

Note that since these methods are created by the @newtype macro, IDEs will generally not be able to resolve them. If the red highlighting bothers you, you can use .coerce to safely cast the base type class to support your newtype -

import io.estatico.newtype.ops._

@newtype case class Text(s: String)
object Text {
  implicit val arb: Arbitrary[Text] = implicitly[Arbitrary[String]].coerce
}

@newtype class Nel[A](val toList: List[A])
object Nel {
  def apply[A](head: A, tail: List[A]): Nel[A] = (head +: tail).coerce[Nel[A]]
  implicit val functor: Functor[Nel] = implicitly[Functor[List]].coerce
}

Note that this is NOT recommended!

In some cases, you may want to automatically derive a type class instance for all newtypes by leveraging Coercible. While seemingly convenient, this is NOT recommended as it in some ways goes against the spirit of using a newtype in the first place. Specializing a specific instance for a newtype will be tricky and will require clever implicit scoping. Also, it can greatly increase your compile times. Instead, it's generally better to explicitly define instances for your newtypes.

You have been warned!

The following example generates an Eq instance for all newtypes in which their underlying Repr type has an Eq instance.

scala> :paste

import cats._, cats.implicits._

/** If we have an Eq instance for Repr type R, derive an Eq instance for newtype N. */
implicit def coercibleEq[R, N](implicit ev: Coercible[Eq[R], Eq[N]], R: Eq[R]): Eq[N] =
  ev(R)

@newtype case class Foo(x: Int)

// Exiting paste mode, now interpreting.

scala> Foo(1) === Foo(2)
res0: Boolean = false

However, as mentioned, it's generally better to explicitly define your instances.

@newtype case class Foo(x: Int)
object Foo {
  implicit val eq: Eq[Foo] = deriving
}

You may not always be able to put your instance in the companion object, likely because the type class is not available where you are defining your newtype. In this case, simply define an orphan instance and import it where you need.

object EqOrphans {
  implicit val eqFoo: Eq[Foo] = implicitly[Eq[Int]].coerce
}

If you don't wish to use the macro API, you can still use the legacy API for building newtypes manually via companion objects. Note that this method does not support newtypes with type parameters. If you need type parameters, use the macro API.

The easiest way to get going with the legacy encoding is to create an object that extends from NewType.Default -

import io.estatico.newtype.NewType

object WidgetId extends NewType.Default[Int]

This will be the companion object for your newtype. Use the .Type type member to get access to the type for signatures. A common pattern is to include this in a package object so it can be easily imported.

package object types {
  type WidgetId = WidgetId.Type
  object WidgetId extends NewType.Default[Int]
}

Now you can import types.WidgetId and use it in type signatures as well as the companion object.

Extending NewType.Of simply creates the newtype wrapper; however, you will often want to extend NewType.Default to provide some helper methods on the companion object -

// Safely casts an Int to a WidgetId
scala> WidgetId(1)
res0: WidgetId.Type = 1

// Safely casts M[Int] to M[WidgetId]
scala> WidgetId.applyM(List(1, 2))
res1: List[WidgetId.Type] = List(1, 2)

See NewTypeExtras for the available mixins for creating newtype wrappers.

If you wish to do something different, you can supply your own smart-constructor instead -

object Nat extends NewType.Of[Int] {
  def apply(n: Int): Option[Type] = if (n < 0) None else Some(wrap(n))
}

The wrap method you see here is actually just explicit usage of the implicit instance of Coercible[Int, Nat.Type]. See the section on Coercible for more info.

You probably want to be able to add methods to your newtypes. You can do this using Scala's extension methods via implicit classes -

type Point = Point.Type
object Point extends NewType.Of[(Int, Int)] {

  def apply(x: Int, y: Int): Type = wrap((x, y))

  implicit final class Ops(val self: Type) extends AnyVal {
    def toTuple: (Int, Int) = unwrap(self)
    def x: Int = toTuple._1
    def y: Int = toTuple._2
  }
}

scala> val p = Point(1, 2)
p: Point.Type = (1,2)

scala> p.toTuple
res7: (Int, Int) = (1,2)

scala> p.x
res8: Int = 1

scala> p.y
res9: Int = 2

As mentioned, the object you create via extending one of the NewType helpers functions as the companion object for your newtype. As such, you can leverage this for type class instances to avoid orphan instances -

object Nat extends NewType.Of[Int] {
  implicit val show: Show[Type] = Show.instance(_.toString)
}

If you use NewType.Default, you can use the deriving method to derive type class instances for those that exist for your newtype's base type.

object Nat extends NewType.Default[Int] {
  implicit def show: Show[Type] = deriving
}

As long as an implicit instance of Show[Int] exists in scope, deriving will cast the instance to one suitable for your newtype. This is similar to GHC Haskell's GeneralizedNewtypeDeriving extension.

With NewType, you get a brand new type that can't be used as the type you are wrapping.

type Nat = Nat.Type
object Nat extends NewType.Default[Int]

def plus(x: Int, y: Int): Int = x + y

scala> plus(Nat(1), Nat(2))
<console>:19: error: type mismatch;
 found   : Nat.Type
 required: Int

If you wish for your newtype to be a subtype of the type you are wrapping, you can use NewSubType -

type Nat = Nat.Type
object Nat extends NewSubType.Default[Int]

def plus(x: Int, y: Int): Int = x + y

scala> plus(Nat(1), Nat(2))
res0: Int = 3

This library introduces the Coercible type class for types that can safely be cast to/from newtypes. This is mostly useful when you want to write code that can work generically with newtypes or to simply leverage the compiler to tell you when you can do .asInstanceOf.

NOTE: You generally shouldn't be creating instances of Coercible yourself. This library is designed to create the instances needed for you which are safe. If you manually create instances, you may be permitting unsafe operations which will lead to runtime casting errors.

With that out of the way, here's how we can do safe casting with Coercible -

type Point = Point.Type
object Point extends NewType.Of[(Int, Int)]

scala> Coercible[Point, (Int, Int)]
res10: io.estatico.newtype.Coercible[Point,(Int, Int)] = io.estatico.newtype.Coercible$$anon$1@56c24c2a

scala> Coercible[(Int, Int), Point]
res11: io.estatico.newtype.Coercible[(Int, Int),Point] = io.estatico.newtype.Coercible$$anon$1@56c24c2a

scala> Coercible[String, Point]
<console>:21: error: could not find implicit value for parameter ev: io.estatico.newtype.Coercible[String,Point]
       Coercible[String, Point]

This library provides extension methods for safe casting as well -

scala> import io.estatico.newtype.ops._
import io.estatico.newtype.ops._

scala> val p = Point(1, 2)
p: Point.Type = (1,2)

scala> p.coerce[(Int, Int)]
res14: (Int, Int) = (1,2)

scala> (3, 4).coerce[Point]
res15: Point = (3,4)

scala> (3.2, 4.3).coerce[Point]
<console>:24: error: could not find implicit value for parameter ev: io.estatico.newtype.Coercible[(Double, Double),Point]
       (3.2, 4.3).coerce[Point]
                        ^

The Haskell language provides a newtype keyword for creating new types from existing ones without runtime overhead.

newtype WidgetId = WidgetId Int

lookupWidget :: WidgetId -> Maybe Widget
lookupWidget (WidgetId wId) = lookup wId widgetDB

In the example above, the WidgetId type is simply an Int at runtime; however, the compiler will treat it as its own type at compile time, helping you to avoid errors. In this case, we can be sure that the ID we are providing to our lookupWidget function refers to a WidgetId and not some other entity nor an arbitrary Int value.

This library attempts to bring newtypes to Scala.

Both Scalaz and Shapeless provide a feature known as Tagged Types. This library operates on roughly the same principle except provides the proper infrastructure needed to -

• Control whether newtypes are or are not subtypes of their wrapped type instead of picking a side (Shapeless' are subtypes, Scalaz's are not)
• Easily provide methods for newtypes
• Resolve implicits and type class instances defined in the companion object
• Optimize constructing newtypes via casting with automatic smart constructors
• Provide facilities to operate generically on newtypes
• Support safe casting generically via the Coercible type class