Constraint Usage

This page informs on how to use Iron's constraints.

Note: When using Iron, you usually want to use the following imports:

//You can specify constraints you want if needed but be sure to import `given` or the given instance of your constraint
import io.github.iltotore.iron.*, constraint.{given, *}

//If you have other Iron modules like numeric:
import numeric.constraint.{given, *}

The following examples will assume you use these imports.

Basic usage

You can attach a constraint to:

• Variables
• Methods (Return type)
• Parameters

using the type Constrained[A, B] or its alias ==>[A, B]:

inline def log(x: Double ==> Greater[0d]): Refined[Double] = x.map(Math.log)

You can also use type aliases:

type >[A, V] = A ==> Greater[V]

inline def log(x: Double > 0d): Refined[Double] = x.map(Math.log)

Note: You need to have a suitable constraint behaviour in the implicit scope.

Bad value handling

A Constrained[A, B] is a Refined[A] ensuring that A passed (successfully or not) the B constraint. Refined[A] is simply an alias for Either[IllegalValueError[A], A]. This Either-based structure allows functional error handling.

This functional approach allows constraints to synergise efficiently with other functional libraries like Cats or ZIO.

Here is an example using Iron for a user account:

case class Account(username: String, email: String, password: String)

object Account {

  //Here, the Match[String] constraint isn't natively implemented in Iron and is only used as example.
  
  //Type aliases are not mandatory. They can be used for readability purpose.
  type Username = String ==> Match["^[a-zA-Z0-9]+"]
  type Email = String ==> Match["^[\\w-\\.]+@([\\w-]+\\.)+[\\w-]{2,4}$"]
  //At least one upper, one lower and one number
  type Password = String ==> Match["^(?=.*?[A-Z])(?=.*?[a-z])(?=.*?[0-9])[a-zA-Z0-9]+"]
  
  def createAccount(username: Username, email: Email, password: Password): Either[IllegalValueError[String], Account] = for {
    a <- username
    b <- email
    c <- password
  } yield Account(a, b, c)
}

Usage:

//Right(Account(...))
val validAccount = Account.createAccount("Iltotore", "[email protected]", "SafePassword1")

//Left(IllegalValueError("Il_totore", constraintOfUsername))
val invalidAccount = Account.createAccount("Il_totore", "[email protected]", "SafePassword1")

Compile time evaluation

A constraint is evaluated at compile time if the value and the behaviour is fully inline. Otherwise, the compiler will inline as much as possible the constraint then evaluate at runtime.

Runtime fallback

The fallback behaviour can be configured using the -Diron.fallback argument:

• error: Throw a compile time error
• warn: Warn, then fallback to runtime
• allow (default): Silently fallback to runtime

You can also configure this behaviour individually by extending the right trait:

• Constraint.CompileTimeOnly: Throw a compile-time error if unable to evaluate.
• Constraint.RuntimeOnly: Iron will not try to check this constraint at compile-time and directly fallback to runtime evaluation