Better runtime errors for refined types

[Iltotore]

Iron provides several methods to refine a value at runtime (e.g refineEither, refineValidation)... These methods use a String as error containing the message field of the constraint (e.g "Should be positive").

While it make things simple for a beginer and small demos, it does not make things ergonomic in common cases.

Use cases

Example 1: different fields

opaque type Username = String :| Not[Blank]
object Username extends RefinedTypeOps[String, Not[Blank], Username]

case class User(name: Username, aka: Username)

def createUser(name: String, aka: String): Either[String, User] =
  for
    validName <- Username.either(name)
    validAka  <- Username.either(password)
  yield
    User(name, aka)

createUser("Iltotore", "") //Left("!(Should only contain whitespaces)")
createUser("", "Raphaël FROMENTIN") //Left("!(Should only contain whitespaces)")

Different errors, same message. Note that you cannot solve this problem by using DescribedAs since both name and aka store the same type: a Username (assuming they have the same properties in this example, making a specific AKA type would be overkill).

Instead, such case often looks like:

case class InvalidValue(field: String, message: String)

def createUser(name: String, aka: String): Either[InvalidValue, User] =
  for
    validName <- Username.either(name).left.map(InvalidValue("name", _))
    validAka  <- Username.either(password).left.map(InvalidValue("aka", _))
  yield
    User(name, aka)

createUser("Iltotore", "") //InvalidValue("name", "!(Should only contain whitespaces)")
createUser("", "Raphaël FROMENTIN") //InvalidValue("password", "!(Should only contain whitespaces)")

One might also want to include the value in the error message.

case class InvalidValue[A](field: String, value: A, message: String)

def createUser(name: String, aka: String): Either[InvalidValue, User] =
  for
    validName <- Username.either(name).left.map(InvalidValue("name", name, _))
    validAka  <- Username.either(password).left.map(InvalidValue("aka", aka, _))
  yield
    User(name, aka)

Example 2: refining a collection of values

Since 2.5.0, Iron provides utility methods to refine collection of values:

val alternativeNames = List("totore", "Il_totore", "rfromentin").refineAllEither[Not[Blank]]

But they might not be useful in several use cases:

val alternativeNames = List("totore", "Il_totore", "", "rfromentin")
  .refineAllEither[Not[Blank]] ////Left("!(Should only contain whitespaces)")

It would have been useful to know which value did not pass.

Solution

As @vbergeron suggested, errors could be more structured than a plain String. I think a case class containing the value and the error message is a good starting point:

case class InvalidValue[A](value: A, message: String)

And since the field problem (see the first example) is very common an Option[String] field looks good to me:

case class InvalidValue[A](value: A, message: String, field: Option[String] = None):

  def withField(field: String): InvalidValue[A] = this.copy(field = field)

I am not in favor of changing refineEither, refineUnsafe etc. (at least not before 3.0) in order to preserve retrocompatibility but I think the cost is affordable for all variants since:

• They are recent (since 2.5.0)
• They are not much useful in their current state

Then, example 2 would become:

val alternativeNames = List("totore", "Il_totore", "", "rfromentin")
  .refineAllEither[Not[Blank]] ////Left(InvalidValue("", "!(Should only contain whitespaces)"))

Such error structure would also be used for future validation variants like refineAllValidation:

List(" ", "totore", "", "Il_totore").refineAllValidation[Not[Blank]]
/*
Failure(NonEmptyChunk(
  InvalidValue(" ", "!(Should only contain whitespaces"),
  InvalidValue("", "!(Should only contain whitespaces")
))
*/

• What do you think of such system?
• Is there a better approach?
• Is compatiblity break with refineAllEither etc. affordable?