A simple "tag" used to tell the Validatable type family that we are constructing the "error" type.

A simple type level function that is usefull to get rid of the boilerplate in case you want your error and data type to have the same shape / structure.

It takes in three arguments:

a

A type with a kind of * -> * that basically serves as a flag which determines if Validatable will return the error type wrapped in Maybe or a value type. To return the error type use Validate and to return value type use Identity.

e

Type that should be used for the error.

x

Type that should be used for the value.

Here is an example of how to use it to reduce boilerplate, instead of this (sill perfectly acceptable by Valor):

{ -# LANGUAGE DuplicateRecordFields #- }
--
module Test
--
import Data.Text ( Text )
--
data User = User
  { username :: Text
  , password :: Text
  } deriving ( Show )

data UserError = UserError
  { username :: Maybe String   -- this field will have only one error
  , password :: Maybe [String] -- this one can have multiple errors
  } deriving ( Show )

which can get painful to maintain an repetitive to write if you have a lot of fields in your records, you can just write the following:

{ -# LANGUAGE FlexibleInstances #- }
{ -# LANGUAGE StandaloneDeriving #- }
{ -# LANGUAGE TypeSynonymInstances #- }
--
module Test
--
import Data.Valor ( Validatable, Validate )
import Data.Text ( Text )
import Data.Functor.Identity ( Identity (..) )
--
data User' a = User
  { username :: Validatable a String   Text
  , password :: Validatable a [String] Text
  }

type User = User' Identity
deriving instance Show User

type UserError = User' Validate
deriving instance Show UserError

This approach requires a few language extensions to allow us instance derivation, but it removes a lot of the boilerplate and maintenance costs in the long run.

All in all, Validatable is quite easy to understand, it takes around 5 min to understand this type family even if you've never used type families before , just take a look at the Equations below:

Validator is basically a function that takes in an input i and returns an error e wrapped in your monad of choice m.

To construct a Validator you can use functions skip, check, mapCheck, checks, mapChecks, subValidator and mapSubValidator. Intended way of constructing a Validator is by using the Applicative interface.

Above mentioned functions expect a test (or tests) in the form of x -> ExceptT e m x. ExceptT was chosen here because it is a monad transformer and allows ust to throw an error and use a custom monad m. This is useful in case you have to check the database to validate some data or your test relies on success or failure of another field. You can use state monad or transformer to pass in the data being validated so that it is accessible within the test.

To run your Validator against some data you can use validate function, or validatePure if you don't want to use any particular monad and get the pure result wrapped in Maybe.

Here is an example of a few simple tests and construction of a Validator for the previously defined User record:

nonempty' :: Monad m => Text -> ExceptT String m Text
nonempty' t = if null t
  then throwE "can't be empty"
  else pure t

nonempty :: Monad m => Text -> ExceptT [String] m Text
nonempty t = if null t
  then throwE ["can't be empty"]
  else pure t

nonbollocks :: Monad m => Text -> ExceptT [String] m Text
nonbollocks t = if t == "bollocks"
  then throwE ["can't be bollocks"]
  else pure t

nonshort :: Monad m => Text -> ExceptT [String] m Text
nonshort t = if length t < 10
  then throwE ["too short"]
  else pure t

userValidator :: Monad m => Validator User m UserError
userValidator = User
  <$> check  email nonempty'
  <*> checks username [nonempty, nonbollocks, nonshort]

Use this in case you are not interested in validating a certain field.

Runs a single check against the specified field.

Runs a single check over every element of some Traversable "container".

This is quite useful if you for example have a field that contains array of items and you want to run a check against every single element of that list instead of the list as a whole.

Runs multiple checks against the specified field. Resulting error must be a Semigroup so that it can be combined or accumulated in some fashion, most convenient thing would be to use a list of "something".

Basically the same thing as mapCheck but it allows you to run multiple checks per element.

Runs a custom made Validator against the field data.

Runs a custom made Validator against the every element in a Traversable container.

This function is used to run the Validator against the input data i, once validation process is finished it will Maybe return the error e wrapped in the monad m of your choice.

In case you don't have a need for a monad you can use this function to run your Validator and get pure Maybe instead of Maybe wrapped in a monad.

Here is an example of running userValidator over some invalid data:

badUser :: User
badUser = User "boaty@mcboatface.com" "bollocks"

>>> validatePure userValidator badUser
Just (User {email = Nothing, username = Just ["can't be bollocks","too short"]})