validator

∠(・.-)―〉 →◎ validator is a Crystal data validation module.
Very simple and efficient, all validations return true or false.

Also validator/check (not exposed by default) provides:

• Error message handling intended for the end user.
• Also (optional) a powerful and productive system of validation rules. With self-generated granular methods for cleaning and checking data.

Validator respects the KISS principle and the Unix Philosophy. It's a great basis tool for doing your own validation logic on top of it.

Installation

1. Add the dependency to your shard.yml:

dependencies:
  validator:
    github: nicolab/crystal-validator
    version: ~> 1.0.1 # Check the latest version!

2. Run shards install

Usage

• Validator - API docs

There are 3 main ways to use validator:

• As a simple validator to check rules (eg: email, url, min, max, presence, in, ...) which return a boolean.
• As a more advanced validation system which will check a series of rules and returns all validation errors encountered with custom or standard messages.
• As a system of validation rules (inspired by the Laravel framework's Validator) which makes data cleaning and data validation in Crystal very easy! With self-generated granular methods for cleaning and checking data of each field.

By default the validator module expose only Validator and Valid (alias) in the scope:

require "validator"

Valid.email? "contact@example.org" # => true
Valid.url? "https://github.com/Nicolab/crystal-validator" # => true
Valid.my_validator? "value to validate", "hello", 42 # => true

An (optional) expressive validation flavor, is available as an alternative. Not exposed by default, it must be imported:

require "validator/is"

is :email?, "contact@example.org" # => true
is :url?, "https://github.com/Nicolab/crystal-validator" # => true
is :my_validator?, "value to validate", "hello", 42 # => true


# raises an error if the email is not valid
is! :email?, "contact@@example..org" # => Validator::Error

is is a macro, no overhead during the runtime 🚀 By the nature of the macros, you can't pass the validator name dynamically with a variable like that is(validator_name, "my value to validate", arg). But of course you can pass arguments with variables is(:validator_name?, arg1, arg2).

• Validator - API docs

Validation rules

require "validator/check"

class User
    # Mixin
    Check.checkable

    property email : String
    property age : Int32

    Check.rules(
      email: {
        # Checker (all validators are supported)
        check: {
          not_empty: {"Email is required"},
          email:     {"It is not a valid email"},
        },

        # Cleaner
        clean: {
          # Data type
          type: String,

          # Converter (if union or other)
          # Example if the input value is i32, but i64 is expected
          # Here is a String
          to: :to_s,

          # Formatter (any Crystal Proc)
          format: ->self.format_email(String),

          # Error message
          # Default is "Wrong type" but it can be customized
          message: "Oops! Wrong type.",
        },
      },
      age: {
        check: {
          not_null: {"Age is required"},
          min:     {"Age should be more than 18", 18},
          between: {"Age should be between 25 and 35", 25, 35},
        },
        clean: {type: Int32, to: :to_i32, message: "Unable to cast to Int32"},
      }
    )

    def initialize(@email, @age); end

    # ---------------------------------------------------------------------------
    # Lifecycle methods (hooks)
    # ---------------------------------------------------------------------------

    # Triggered on instance: `user.check`
    def before_check(v : Check::Validation, format : Bool)
      # Code...
    end

    # Triggered on instance: `user.check`
    def after_check(v : Check::Validation, format : Bool)
      # Code...
    end

    # Triggered on a static call: `User.check(h)` (with a `Hash` or `JSON::Any`)
    def self.before_check(v : Check::Validation, h, format : Bool)
      # Code...
      pp h
    end

    # Triggered on a static call: `User.check(h)` (with a `Hash` or `JSON::Any`)
    def self.after_check(v : Check::Validation, h, cleaned_h, format : Bool)
      # Code...
      pp cleaned_h
      cleaned_h # <= returns cleaned_h!
    end

    # --------------------------------------------------------------------------
    #  Custom checkers
    # --------------------------------------------------------------------------

    # Triggered on instance: `user.check`
    @[Check::Checker]
    def custom_checker(v, format)
      self.custom_checker_called = true
    end

     # Triggered on a static call: `User.check(h)` (with a `Hash` or `JSON::Any`)
    @[Check::Checker]
    def self.custom_checker(v, h, cleaned_h, format)
      @@custom_checker_called = true
      cleaned_h # <= returns cleaned_h!
    end

    # --------------------------------------------------------------------------
    #  Formatters
    # --------------------------------------------------------------------------

    # Format (convert) email.
    def self.format_email(email)
      puts "mail stripped"
      email.strip
    end

    # --------------------------------------------------------------------------
    # Normal methods
    # --------------------------------------------------------------------------

    def foo()
      # Code...
    end

    def self.bar(v)
      # Code...
    end

    # ...
  end

Check with this example class (User):

# Check a Hash (statically)
v, user_h = User.check(input_h)

pp v # => Validation instance
pp v.valid?
pp v.errors

pp user_h # => Casted and cleaned Hash

# Check a Hash (on instance)
user = user.new("demo@example.org", 38)

v = user.check # => Validation instance
pp v.valid?
pp v.errors

# Check field
v, email = User.check_email(value: "demo@example.org")
v, age = User.check_age(value: 42)

v, email = User.check_email(value: "demo@example.org ", format: true)
v, email = User.check_email(value: "demo@example.org ", format: false)

# Using an existing Validation instance
v = Check.new_validation
v, email = User.check_email(v, value: "demo@example.org")

Clean with this example class (User):

# `check` method cleans all values of the Hash (or JSON::Any),
# before executing the validation rules
v, user_h = User.check(input_h)

pp v # => Validation instance
pp v.valid?
pp v.errors

pp user_h # => Casted and cleaned Hash

# Cast and clean field
ok, email = User.clean_email(value: "demo@example.org")
ok, age = User.clean_age(value: 42)

ok, email = User.clean_email(value: "demo@example.org ", format: true)
ok, email = User.clean_email(value: "demo@example.org ", format: false)

puts "${email} is casted and cleaned" if ok
# or
puts "Email type error" unless ok

• clean_* methods are useful to caste a union value (like Hash or JSON::Any).
• Also clean_* methods are optional and handy for formatting values, such as the strip on the email in the example User class.

More details about cleaning, casting, formatting and return values:

By default format is true, to disable:

ok, email = User.clean_email(value: "demo@example.org", format: false)
# or
ok, email = User.clean_email("demo@example.org", false)

Always use named argument if there is only one (the value):

ok, email = User.clean_email(value: "demo@example.org")

ok is a boolean value that reports whether the cast succeeded. Like the type assertions in Go (lang). But the ok value is returned in first (like in Elixir lang) for easy handling of multiple return values (Tuple).

Example with multiple values returned:

ok, value1, value2 = User.clean_my_tuple({1, 2, 3})

Considering the example class above (User). As a reminder, the email field has been defined with the formatter below:

Check.rules(
  email: {
    clean: {
      type:    String,
      to:      :to_s,
      format:  ->self.format_email(String), # <= Here!
      message: "Wrong type",
    },
  },
)

# ...

# Format (convert) email.
def self.format_email(email)
  puts "mail stripped"
  email.strip
end

So clean_email cast to String and strip the value " demo@example.org ":

# Email value with one space before and one space after
ok, email = User.clean_email(value: " demo@example.org ")

puts email # => "demo@example.org"

If the email was taken from a union type (json["email"]?), the returned email variable would be a String too.

See more examples.

Validation#check

To perform a series of validations with error handling, the validator/check module offers this possibility 👍

A Validation instance provides the means to write sequential checks, fine-tune each micro-validation with their own rules and custom error message, the possibility to retrieve all error messages, etc.

Validation is also used with Check.rules and Check.checkable that provide a powerful and productive system of validation rules which makes data cleaning and data validation in Crystal very easy. With self-generated granular methods for cleaning and checking data.

To use the checker (check) includes in the Validation class:

require "validator/check"

# Validates the *user* data received in the HTTP controller or other.
def validate_user(user : Hash) : Check::Validation
  v = Check.new_validation

  # -- email

  # Hash key can be a String or a Symbol
  v.check :email, "The email is required.", is :presence?, :email, user

  v.check "email", "The email is required.", is :presence?, "email", user
  v.check "email", "#{user["email"]} is an invalid email.", is :email?, user["email"]

  # -- username

  v.check "username", "The username is required.", is :presence?, "username", user

  v.check(
    "username",
    "The username must contain at least 2 characters.",
    is :min?, user["username"], 2
  )

  v.check(
    "username",
    "The username must contain a maximum of 20 characters.",
    is :max?, user["username"], 20
  )
end

v = validate_user user

pp v.valid? # => true (or false)

# Inverse of v.valid?
if v.errors.empty?
  return "no error"
end

# Print all the errors (if any)
pp v.errors

# It's a Hash of Array
errors = v.errors

puts errors.size
puts errors.first_value

errors.each do |key, messages|
  puts key   # => "username"
  puts messages # => ["The username is required.", "etc..."]
end

3 methods #check:

# check(key : Symbol | String, valid : Bool)
# Using default error message
v.check(
  "username",
  is(:min?, user["username"], 2)
)

# check(key : Symbol | String, message : String, valid : Bool)
# Using custom error message
v.check(
  "username",
  "The username must contain at least 2 characters.",
  is(:min?, user["username"], 2)
)

# check(key : Symbol | String, valid : Bool, message : String)
# Using custom error message
v.check(
  "username",
  is(:min?, user["username"], 2),
  "The username must contain at least 2 characters."
)

Check is a simple and lightweight wrapper. The Check::Validation is agnostic of the checked data, of the context (model, controller, CSV file, HTTP data, socket data, JSON, etc).

Use case example: Before saving to the database or process user data for a particular task, the custom error messages can be used for the end user response.

But a Validation instance can be used just to store validation errors:

v = Check.new_validation
v.add_error("foo", "foo error!")
pp v.errors # => {"foo" => ["foo error!"]}

See also Check.rules and Check.checkable.

Let your imagination run wild to add your logic around it.

Custom validator

Just add your own method to register a custom validator or to overload an existing validator.

module Validator
  # My custom validator
  def self.my_validator?(value, arg : String, another_arg : Int32) : Bool
    # write here the logic of your validator...
    return true
  end
end

# Call it
puts Valid.my_validator?("value to validate", "hello", 42) # => true

# or with the `is` flavor
puts is :my_validator?, "value to validate", "hello", 42 # => true

Using the custom validator with the validation rules:

require "validator/check"

class Article
  # Mixin
  Check.checkable

  property title : String
  property content : String

  Check.rules(
    content: {
      # Now the custom validator is available
      check: {
        my_validator: {"My validator error message"},
        between: {"The article content must be between 10 and 20 000 characters", 10, 20_000},
        # ...
      },
    },
  )
end

# Triggered with all data
v, article = Article.check(input_data)

# Triggered with one value
v, content = Article.check_content(input_data["content"]?)

Conventions

• The word "validator" is the method to make a "validation" (value validation).
• A validator returns true if the value (or/and the condition) is valid, false if not.
• The first argument(s) is (are) the value(s) to be validated.
• Always add the Bool return type to a validator.
• Always add the suffix ? to the method name of a validator.
• If possible, indicates the type of the validator arguments.
• Spec: Battle tested.
• KISS and Unix Philosophy.

Development

crystal spec
crystal tool format

TODO: add ameba?

Contributing

1. Fork it (https://github.com/nicolab/crystal-validator/fork)
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

LICENSE

MIT (c) 2020, Nicolas Talle.

Author

| | |---| | Nicolas Talle | | |

Thanks to ilourt for his great work on checkable mixins (clean_, check_, ...).