README.md

clova

A "minimal" validation library for Clojure and ClojureScript.

• API Docs
• Change Log

Status

Installation

clova is available from Clojars

Usage

Validation sets are pairs of keys to validate and the functions used to validate them. When a map conforms to the validation set then the validate function returns the original map.

(validate
  [:email email?
   :age [between? 18 40]
   [:nested :value] [between? 0 10]] 
   {:email "[email protected]" :age 20 :nested {:value 9}})

;; {:email "[email protected]", :age 20, :nested {:value 9}}

When a map does not conform to the validation set then the validate function returns the original map with a sequence of validation errors transposed onto the applicable keys. All validation errors are available using the :clova.core/results key and the validation status is available using the :clova.core/invalid? key.

(validate
  [:email email?
   :age [between? 18 40]
   [:nested :value] [between? 0 10]] 
   {:email "testemail.com" :age 10 :nested {:value 19}})

;; {:clova.core/results ("email should be a valid email address." "age is 10 but it must be between 18 and 40." "nested value is 19 but it must be between 0 and 10.") 
;;  :clova.core/invalid? true 
;;  :email ("email should be a valid email address.") 
;;  :age ("age is 10 but it must be between 18 and 40."), 
;;  :nested {:value ("nested value is 19 but it must be between 0 and 10.")}}

You don't have to use pre-defined validator functions exposed by clova, you can also use arbitrary functions.

Arbitrary functions will not generate scenario specific failure messages but a generic message format of "%s has value %s, which is invalid." will be used.

(validate [:age [> 18]] {:age 21})

;; {:age 21}

If you want to compose multiple validators you can.

(validate [:age required? [greater? 18] [lesser? 30]] {:age 29})

;; {:age 29}

Most of the time it is useful to only apply and fail validation if a given key is present in the map under validation, this is the default behaviour in clova. However if this is not the case and you wish to make a validator fail if the key is not present you can do so by using a required? validator.

(validate [:email required? email?] {:email "[email protected]"})

;; {:email "[email protected]"}

(validate [:age required? [between? 18 30]] {:age 29})

;; {:age 29}

Get the validation status:

(:clova.core/invalid? (validate [:email required? email?] {:email "notanemail"}))

;; true

(:clova.core/invalid? (validate [:email required? email?] {:email "[email protected]"}))

;; nil

or

(valid? [:email required? email?] {:email "[email protected]"})

;; true

(valid? [:email required? email?] {:email "notanemail"})

;; false

Get the validation results (error messages):

(:clova.core/results (validate [:email required? email?] {:email "[email protected]"}))

;; nil
(:clova.core/results (validate [:email required? email?] {:email "notanemail"}))

;; ("email should be a valid email address.")

or

(results [:email required? email?] {:email "[email protected]"})

;; nil

(results [:email required? email?] {:email "notanemail"})

;; ("email should be a valid email address.")

You can also specify a custom function for providing validation error messages. This function will be called with the validator type, the target value and any arguments passed to the validator specified as arguments, if the custom function returns nil then the default validation message will be used.

For example, we can use the between? validator with a custom error message, like so:

(let [message-func (fn [v-type value args]
                    (case v-type
                      :between (str "Age is " value " but it must be between " (first args) " and " (second args))
                       nil))]
    (validate v-set {:age 9} {:default-message-fn message-func}))

By default clova will execute all validators and provide validation messages for all failures. You can override this behaviour using the :short-circuit? option. This will stop execution of subsequent validators after the first validation failure and will therefore only return one validation failure message.

(validate v-set {:email ""} {:short-circuit? true })

See more usage examples.

Validators

clova has the following built in validators

1. between?
2. email?
3. greater?
4. lesser?
5. matches?
6. negative?
7. positive?
8. post-code?
9. not-nil?
10. required?
11. url?
12. zip-code?
13. length?
14. longer?
15. shorter?
16. one-of?
17. all?
18. credit-card?
19. numeric?
20. stringy?
21. date?
22. before?
23. after?
24. =date?
25. =?
26. alphanumeric?
27. not-exists?
28. exists?

License

Copyright © 2015-2024 Mark Woodhall

Released under the MIT License: http://www.opensource.org/licenses/mit-license.php