You have to wrap every value of your form inside this type. For example, if your model looked something like

type alias FormerModel =
    { username : String
    , email : String
    , password : String
    , passwordCopy : String
    }

you have to change it to

type alias Model =
    { username : Validatable String String
    , email : Validatable String String
    , password : Validatable String String
    , passwordCopy : Validatable String String
    }

Use this to initialize your values:

init : Model
init =
    { username = empty
    , email = empty
    , pasword = empty
    , passwordCopy = empty
    }

Use this to update a value in your model in reaction to user input:

update : Msg -> Model -> Model
update msg model =
    case msg of
        SetUsername string ->
            { model | username = unchecked string }


        ...

Set the value to unchecked if possible.

Create a valid value. Usefull for initializing with a default value.

Return the actual value if it has been successfully validated at least once.

Return all validation errors if the value has been tried to be validated at least once.

I am not sure if it is a good idea to have this function at all, so it may be removed in the future.

Return the value, no matter if it is valid or not.

Note: If the value is in an invalid state, there may not be a raw value anymore.

Note: Don't use this to extract the value for submitting the form. Use validValue instead, to ensure at compile time that you only submit valid values.

Check if the string value is non-empty. The first argument is the error which is recorded if the value is empty.

(unchecked "I am not empty!"
    |> isNotEmpty "the value must not be empty"
    |> validValue
)
    == Just "I am not empty!"


(unchecked ""
    |> isNotEmpty "the value must not be empty"
    |> errors
    |> Maybe.map toList
)
    == Just [ "the value must not be empty" ]

Check if the string value is at least the given count of characters long.

Check if the string value only consists of letters.

Check if the string value is a proper email address.

Try to cast a String to an Int.

Try to cast a String to a Float.

Run the provided computation which might result in an error. If it succeeds, we get a valid value, if it fails we get an invalid state with the given errors. So, you can do something like this:

("not a number"
    |> try String.toInt (\err -> "You must provide an integer: " ++ err)
    |> errors
    |> Maybe.map toList
)
    == Just [ "You must provide an integer: could not convert ..." ]

Check if the value satisfies the condition. If not add the provided error to the list of errors.

Note: If the value was in an invalid state before and satisfies the condition we drop the previous errors and return a valid value.

Given a reference value, check if the value equals it.

Add the given set of validation errors. This makes every value which is not empty invalid. You can use this function if you need to show validations to the user which can only be performed on the server, for example checking if a username is still available.

Note: If the set is empty, we do not change the state of the value.

Apply the given function on the actual value.

Apply the given function on the error values.

Apply the validator on maybe values. If the value is Nothing, it is left unchanged. This is usefull if you need to validate optional arguments, for example

nickname : Validatable (Maybe String) String
nickname =
    valid Nothing


(nickname
    |> maybe (consistsOfLetters "nickname must consist of letters only")
    |> validValue
)
    == Just Nothing




invalidNickname : Validatable (Maybe String) String
invalidNickname =
    unchecked (Just "123")


(invalidNickname
    |> maybe (consistsOfLetters "nickname must consist of letters only")
    |> errors
    |> Set.toList
)
    == Just [ "nickname must consist of letters only" ]

Apply a validation only if another value was successfully validated. This unchecks the value if the provided value was not valid. For example, you can do something like this

password : Validatable String String


passwordCopy : Validatable String String
passwordCopy =
    oldPasswordCopy
        |> Validate.with password
            (\validPassword ->
                Validate.equals validPassword "Both passwords have to match up."
            )