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, *}

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.

Fail fast

The fail-fast approach is useful when you need the precedent step to be successful before continuing.

import io.github.iltotore.iron.*, constraint.{given, *}, string.constraint.{given, *}

def parse(input: String ==> Match["[0-9]"]): Either[IllegalValueError[String], Double] = input.map(_.toDouble)

def inverse(x: Double \ 0d): Double \ 0d = x.map(1 / _)

//input can be some user input caught via cats
def process(input: String): Either[IllegalValueError[?], Double] = for {
  parsed <- parse(input)
  result <- inverse(parsed)
} yield result

process("5") //Right(0.2)
process("0") //Left(IllegalValueError)
process("a") //Left(IllegalValueError)

Accumulative failure

When you have multiple, independents, values to build a single result (Example: a form), we don't want to stop once the first illegal value: we want to fail for all bad inputs, we want to accumulate them.

Here is an example of error accumulation in a form

import io.github.iltotore.iron.*, constraint.{given, *}, string.constraint.{given, *}, catsSupport.*
import cats.implicits.*, cats.syntax.apply.*

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]+"]
  
  //Input values passed by the user
  def createAccount(username: Username, email: Email, password: Password): RefinedNec[String] = (
    username
    email
    password
  ).map3(Account)
}

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

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

/* 
 * Left(NonEmptyChain(
 *   IllegalValueError("Il_totore", constraintOfUsername),
 *   IllegalValueError("this_is_not_fine", constraintOfPassword)
 * ))
 */
Account.createAccount("Il_totore", "[email protected]", "this_is_not_fine")

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