β (γ».-)βγ ββ 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.
- Add the dependency to your
shard.yml
:
dependencies:
validator:
github: nicolab/crystal-validator
- Run
shards install
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)
.
The validation rules can be defined directly when defining properties (with getter
or property
).
Or with the macro Check.rules
. Depending on preference, it's the same under the hood.
require "validator/check"
class User
# Mixin
Check.checkable
# required
property email : String, {
required: true,
# Optional lifecycle hook to be executed on `check_email` call.
# Before the `check` rules, just after `clean_email` called inside `check_email`.
# Proc or method name (here is a Proc)
before_check: ->(v : Check::Validation, content : String?, required : Bool, format : Bool) {
puts "before_check_content"
content
},
# Optional lifecycle hook to be executed on `check_email` call, after the `check` rules.
# Proc or method name (here is the method name)
after_check: :after_check_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) to the expected value type.
# Example if the input value is i32, but i64 is expected
# Here is a String
to: :to_s,
# Formatter (any Crystal Proc) or method name (Symbol)
format: :format_email,
# Error message
# Default is "Wrong type" but it can be customized
message: "Oops! Wrong type.",
}
}
# required
property age : Int32, {
required: "Age is required", # Custom message
check: {
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"},
}
# nilable
property bio : String?, {
check: {
between: {"The user bio must be between 2 and 400 characters.", 2, 400},
},
clean: {
type: String,
to: :to_s,
# `nilable` means omited if not provided,
# regardless of Crystal type (nilable or not)
nilable: true
},
}
def initialize(@email, @age)
end
# ---------------------------------------------------------------------------
# Lifecycle methods (hooks)
# ---------------------------------------------------------------------------
# Triggered on instance: `user.check`
private def before_check(v : Check::Validation, required : Bool, format : Bool)
# Code...
end
# Triggered on instance: `user.check`
private def after_check(v : Check::Validation, required : Bool, format : Bool)
# Code...
end
# Triggered on a static call: `User.check(h)` (with a `Hash` or `JSON::Any`)
private def self.before_check(v : Check::Validation, h, required : Bool, format : Bool)
# Code...
pp h
end
# Triggered on a static call: `User.check(h)` (with a `Hash` or `JSON::Any`)
private def self.after_check(v : Check::Validation, h, cleaned_h, required : Bool, format : Bool)
# Code...
pp cleaned_h
cleaned_h # <= returns cleaned_h!
end
# Triggered on a static call and on instance call: `User.check_email(value)`, `User.check(h)`, `user.check`.
private def self.after_check_content(v : Check::Validation, content : String?, required : Bool, format : Bool)
puts "after_check_content"
puts "Valid? #{v.valid?}"
content
end
# --------------------------------------------------------------------------
# Custom checkers
# --------------------------------------------------------------------------
# Triggered on instance: `user.check`
@[Check::Checker]
private def custom_checker(v : Check::Validation, required : Bool, format : Bool)
# Code...
end
# Triggered on a static call: `User.check(h)` (with a `Hash` or `JSON::Any`)
@[Check::Checker]
private def self.custom_checker(v : Check::Validation, h, cleaned_h, required : Bool, format : Bool)
# Code...
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
# Same but raise if there is a validation error
user_h = User.check!(input_h)
# Check a Hash (on instance)
user = user.new("demo@example.org", 38)
v = user.check # => Validation instance
pp v.valid?
pp v.errors
# Same but raise if there is a validation error
user.check! # => Validation instance
# Example with an active record model
user.check!.save
# Check field
v, email = User.check_email(value: "demo@example.org")
v, age = User.check_age(value: 42)
# Same but raise if there is a validation error
email = User.check_email!(value: "demo@example.org")
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")
# Same but raise if there is a validation error
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 (likeHash
orJSON::Any
).- Also
clean_*
methods are optional and handy for formatting values, such as the strip on the email in the exampleUser
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})
# Same but raise if there is a validation error
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"
# Same but raise if there is a validation error
# Email value with one space before and one space after
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.
NOTE: Require more explanations about
required
,nilable
rules. Also about the converters JSON / Crystal Hash:h_from_json
,to_json_h
,to_crystal_h
. In the meantime see the API doc.
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 withCheck.rules
andCheck.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
andCheck.checkable
.
Let your imagination run wild to add your logic around it.
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"]?)
- 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.
crystal spec
crystal tool format
./bin/ameba
- Fork it (https://github.com/nicolab/crystal-validator/fork)
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create a new Pull Request
MIT (c) 2020, Nicolas Talle.
Nicolas Talle |
Thanks to ilourt for his great work on
checkable
mixins (clean_, check_, ...).