composable_validations 0.0.9

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 859b71a70691f26e28d171883bd5297af8897692
+  data.tar.gz: a2e612c3c41de11b37a828a4cf8466c01a6682b3
+SHA512:
+  metadata.gz: 35890438972b2e2898fe20aea2a8e25184b19ff863df5a69208ae4da10d66996cdc50c2b6dff42efb5cd6bb517c02a3b62f2b3cf928baf00564add5b1463ad67
+  data.tar.gz: 1613d3040d41f1fdbbefbfe4098bf4c901711e1a4eeee76a5d4a651da0f5846e57e8266228c5f04480d6a3c07e9f49dd7967409e2eb78a7dfaa64e334c665b15

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2016 Shutl Ltd
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,735 @@
+# Composable Validations
+
+Gem for validating complex JSON payloads.
+
+## Features
+* allows composition of generic validators into readable and reusable
+  validation rules ([Composability](#composability))
+* returned errors always contain exact path of the invalid payload element
+  ([Path to invalid element](#path-to-an-invalid-element))
+* easy to extend with new validators ([Custom validators](#custom-validators))
+* overridable error messages ([Overriding error messages](#overriding-error-messages))
+
+## Requirements
+
+* Ruby 2+
+* A tolerance to parantheses... the validator code has rather "lispy" functional look and feel
+
+## Install
+
+```
+gem install composable_validations
+```
+
+## Quick guide
+
+This gem allows you to build a validator - how/when you call this validation is up to you.
+
+### Basic example
+
+Say we want to validate a payload that specifies a person with name and age. E.g. `{"person" => {"name"
+=> "Bob", "age" => 28}}`
+
+```ruby
+require 'composable_validations'
+
+include ComposableValidations
+
+# building validator function
+validator = a_hash(
+  allowed_keys("person"),
+  key("person", a_hash(
+    allowed_keys("name", "age"),
+    key("name", non_empty_string),
+    key("age", non_negative_integer))))
+
+# invalid payload with non-integer age
+payload = {
+  "person" => {
+    "name" => 123,
+    "age" => "mistake!"
+  }
+}
+
+# container for error messages
+errors = {}
+
+# application of the validator to the payload with default error messages
+valid = default_errors(validator).call(payload, errors)
+
+if valid
+  puts "payload is valid"
+else
+  # examine error messages collected by validator
+  puts errors.inspect
+end
+```
+In the example above the payload is invalid and as a result `valid` has value
+`false` and `errors` contains:
+```
+{"person/name"=>["must be a string"], "person/age"=>["must be an integer"]}
+```
+Note that invalid elements of the payload are identified by exact path within
+the payload.
+
+### Sinatra app
+
+When using this gem in your application code you would only include
+`ComposableValidations` module in classes responsible for validation.
+
+Extending previous example into Sinatra app:
+
+```ruby
+require 'sinatra'
+require 'json'
+require 'composable_validations'
+
+post '/' do
+  payload = JSON.parse(request.body.read)
+  validator = PersonValidator.new(payload)
+
+  if validator.valid?
+    status(204)
+  else
+    status(422)
+    validator.errors.to_json
+  end
+end
+
+class PersonValidator
+  include ComposableValidations
+  attr_reader :errors
+
+  def initialize(payload)
+    @payload = payload
+    @errors = {}
+
+    @validator = a_hash(
+      allowed_keys("person"),
+      key("person", a_hash(
+        allowed_keys("name", "age"),
+        key("name", non_empty_string),
+        key("age", non_negative_integer))))
+  end
+
+  def valid?
+    default_errors(@validator).call(@payload, @errors)
+  end
+end
+```
+
+### Arrays
+
+The previous examples showed validation of a JSON object. We can also
+validate JSON arrays. Let's add list of hobbies to our person object from
+the previous examples:
+```ruby
+{
+  "person" => {
+    "name" => "Bob",
+    "age" => 28,
+    "hobbies" => ["knitting", "horse riding"]
+  }
+}
+```
+We will also not accept people with fewer than two hobbies. Validator for this
+payload:
+```ruby
+a_hash(
+  allowed_keys("person"),
+  key("person", a_hash(
+    allowed_keys("name", "age", "hobbies"),
+    key("name", non_empty_string),
+    key("age", non_negative_integer),
+    key("hobbies", array(
+      min_size(2),
+      each(non_empty_string))))))
+```
+Try to apply this validator to the payload containing invalid list of hobbies
+```
+...
+"hobbies" => ["knitting", {"not" => "allowed"}, "horse riding"]
+...
+```
+and you'll get errors specifying exactly where the invalid element is:
+```
+{"person/hobbies/1"=>["must be a string"]}
+```
+
+### Dependent validations
+
+Sometimes we need to ensure that elements of the payload are in certain
+relation.
+
+We can ensure simple relations between keys using validators
+`key_greater_than_key`, `key_less_than_key` etc. Check out
+[Composability](#composability) for example of simple relation between keys.
+
+### Uniqueness
+
+For uniqueness validation follow the example in [Custom
+validators](#custom-validators).
+
+## Key concepts
+
+### Validators
+
+Validator is a function returning boolean value and having following signature:
+```ruby
+lambda { |validated_object, errors_hash, path| ... }
+```
+* `errors_hash` is mutated while errors are collected by validators.
+* `path` represents a path to the invalid element within the JSON object. It is
+  an array of strings (keys in hash map) and integers (indexes of an array).
+  E.g.  if validated payload is `{"numbers" => [1, 2, "abc", 4]}`, path to
+  invalid element "abc" is `["numbers", 2]`.
+
+This gem comes with basic validators like `a_hash`, `array`, `string`,
+`integer`, `float`, `date_string`, etc. You can find complete list of
+validators [below](#api). Adding new validators is explained in ([Custom
+validators](#custom-validators)).
+
+### Combinators
+
+Validators can be composed using two combinators:
+
+* `run_all(*validators)` - applies all validators collecting errors from all of
+them and returning false if any of the validators returns false. Useful when
+collecting errors of independent validators e.g. fields of the hash.
+
+* `fail_fast(*validators)` - applies validators returning false on first failing
+validator. Useful when using validators depending on some preconditions. For
+example when checking that a value is non negative, you want to ensure first
+that it is a number: `fail_fast(float, non_negative)`.
+
+Return values of above combinators are themselves validators. This way they can
+be further composed into more powerful validation rules.
+
+### Composability
+
+We want to validate object representing opening hours of a store. E.g. store
+opened from 9am to 5pm would be represented by
+```ruby
+{"from" => 9, "to" => 17}
+```
+Let's start by building validator ensuring that payload is a hash where both
+`from` and `to` are integers:
+```ruby
+a_hash(
+  key("from", integer),
+  key("to", integer))
+```
+We also want to make sure that extra keys like
+```ruby
+{"from" => 9, "to" => 17, "something" => "wrong"}
+```
+are not allowed. Let's fix it by using `allowed_keys` validator:
+```ruby
+a_hash(
+  allowed_keys("from", "to"),
+  key("from", integer),
+  key("to", integer))
+```
+Better, but we don't want to allow negative hours like this:
+```ruby
+{"from" => -1, "to" => 17}
+```
+We can fix it by using more specific integer validator:
+```ruby
+a_hash(
+  allowed_keys("from", "to"),
+  key("from", non_negative_integer),
+  key("to", non_negative_integer))
+```
+Let's assume here that we represent store opened all day as
+```ruby
+{"from" => 0, "to" => 24}
+```
+so hours greater than 24 should also be invalid. We can validate hour by
+composing `non_negative_integer` validator with `less_or_equal` using
+`fail_fast` combinator:
+```ruby
+hour = fail_fast(non_negative_integer, less_or_equal(24))
+
+a_hash(
+  allowed_keys("from", "to"),
+  key("from", hour),
+  key("to", hour))
+```
+This validator still has a little problem. Opening hours like this are not
+rejected:
+```ruby
+{"from" => 21, "to" => 1}
+```
+We have to make sure that closing is not before opening. We can do it by using
+`key_greater_than_key` validator:
+```ruby
+key_greater_than_key("to", "from")
+```
+and our validator will look like this:
+```ruby
+a_hash(
+  allowed_keys("from", "to"),
+  key("from", hour),
+  key("to", hour),
+  key_greater_than_key("to", "from"))
+```
+That looks good, but it's not complete yet. `a_hash` validator applies all
+validators to the provided payload by using `run_all` combinator. This
+behaviour is problematic if our `from` or `to` keys are missing or are not
+valid integers. Payload
+```ruby
+{"from" => "abc", "to" => 17}
+```
+will cause an exception as `key_greater_than_key` can not compare string to
+integer. Let's fix it by using `fail_fast` and `run_all` combinators:
+```ruby
+a_hash(
+  allowed_keys("from", "to"),
+  fail_fast(
+    run_all(
+      key("from", hour),
+      key("to", hour)),
+    key_greater_than_key("to", "from")))
+```
+This way if `from` and `to` are not both valid hours we will not be comparing
+them.
+
+You can see this validator reused in a bigger example
+[below](#path-to-an-invalid-element).
+
+## Path to an invalid element
+
+Validation errors on deeply nested JSON structure will always contain exact
+path to the invalid element.
+
+### Example
+
+Let's say we validate stores. Example of store object:
+
+```ruby
+store = {
+  "store" => {
+    "name"        => "Scrutton Street",
+    "description" => "large store",
+    "opening_hours" => {
+      "monday"   => {"from" =>  9, "to" => 17},
+      "tuesday"  => {"from" =>  9, "to" => 17},
+      "wednesday"=> {"from" =>  9, "to" => 17},
+      "thursday" => {"from" =>  9, "to" => 17},
+      "friday"   => {"from" =>  9, "to" => 17},
+      "saturday" => {"from" => 10, "to" => 16}
+    },
+    "employees"=> ["bob", "alice"]
+  }
+}
+```
+
+Definition of the store validator (using `from_to` built in the [previous section](#composability)):
+```ruby
+hour = fail_fast(non_negative_integer, less_or_equal(24))
+
+from_to = a_hash(
+  allowed_keys("from", "to"),
+  fail_fast(
+    run_all(
+      key("from", hour),
+      key("to", hour)),
+    key_greater_than_key("to", "from")))
+
+store_validator = a_hash(
+  allowed_keys("store"),
+  key("store",
+    a_hash(
+      allowed_keys("name", "description", "opening_hours", "employees"),
+      key("name", non_empty_string),
+      optional_key("description"),
+      key("opening_hours",
+        a_hash(
+          allowed_keys("monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday"),
+          optional_key("monday",    from_to),
+          optional_key("tuesday",   from_to),
+          optional_key("wednesday", from_to),
+          optional_key("thursday",  from_to),
+          optional_key("friday",    from_to),
+          optional_key("saturday",  from_to),
+          optional_key("sunday",    from_to))),
+      key("employees", array(each(non_empty_string))))))
+```
+
+Let's say we try to validate store that has Wednesday opening hours invalid
+(closing time before opening time) like this:
+```ruby
+...
+"wednesday"=> {"from" => 9, "to" => 7},
+...
+```
+Now we use store validator to fill in the collection of errors using default
+error messages:
+```ruby
+  errors = {}
+  result = default_errors(store_validator).call(store, errors)
+```
+Result is `false` and we get validation error in the `errors` hash:
+```ruby
+{"store/opening_hours/wednesday/to" => ["must be greater than from"]}
+```
+You can find this example in
+[functional spec](https://github.com/shutl/composable_validations/blob/master/spec/functional/composable_validations_spec.rb)
+ready for experiments.
+
+## Overriding error messages
+
+This gem comes with set of [default error
+messages](https://github.com/shutl/composable_validations/blob/master/lib/composable_validations/default_error_messages.rb).
+There are few ways to provide your own error messages.
+
+### Local override
+
+You can override error message when building your validator:
+```ruby
+a_hash(
+  key("from", integer("custom error message")),
+  key("to", integer("another custom error message")))
+```
+This approach is good if you need just few specialized error messages for
+different parts of your payload.
+
+### Global override
+
+If you need to change some of the error messages across all your validators you
+can provide map of error messages. Keys in the map are symbols matching names
+of basic validators:
+```ruby
+  error_overrides = {
+    string:  "not a string",
+    integer: "not an integer"
+  }
+
+  errors = {}
+  errors_container = ComposableValidations::Errors.new(errors, error_overrides)
+  result = validator.call(valid_data, errors_container, nil)
+```
+Note that your error messages don't need to be strings. You could for example
+use rendering function that returns combination of error code, error context
+and human readable message:
+```ruby
+ error_overrides = {
+    key_greater_than_key: lambda do |validated_object, path, key1, key2|
+      {
+        code: 123,
+        context: [key1, key2],
+        message: "#{key1}=#{object[key1]} is not less than or equal to #{key2}=#{object[key2]}"
+      }
+    end
+  }
+
+  errors = {}
+  errors_container = ComposableValidations::Errors.new(errors, error_overrides)
+  result = validator.call(valid_data, errors_container, nil)
+```
+And when applied to invalid payload your validator will return an error:
+```ruby
+  {
+    "store/opening_hours/wednesday/to"=>
+      [
+        {
+          :code=>123,
+          :context=>["to", "from"],
+          :message=>"to=17 is not less than or equal to from=24"
+        }
+      ]
+  }
+```
+You can experiment with this example in the [specs](https://github.com/shutl/composable_validations/blob/master/spec/functional/error_overrides_spec.rb#L19).
+
+### Override error container
+
+You can override error container class and provide any error collecting
+behaviour you need. The only method error container must provide is:
+```ruby
+def add(msg, path, object)
+```
+where
+* `msg` is a symbol of an error or an array where first element is a symbol of
+error and remaining elements are context needed to render the error message.
+* `path` represents a path to the invalid element within the JSON object. It is
+  an array of strings (keys in hash map) and integers (indexes in array).
+* `object` is a validated object.
+
+Example of error container that just collects error paths:
+```ruby
+class CollectPaths
+  attr_reader :paths
+
+  def initialize
+    @paths = []
+  end
+
+  def add(msg, path, object)
+    @paths << path
+  end
+end
+
+validator = ...
+errors_container = CollectPaths.new
+result = validator.call(valid_data, errors_container, nil)
+```
+and example of the value of `errors_container.paths` after getting an error:
+```ruby
+[["store", "opening_hours", "wednesday", "to"]]
+```
+You can experiment with this example in the [spec](https://github.com/shutl/composable_validations/blob/master/spec/functional/error_overrides_spec.rb#L80).
+
+## Custom validators
+
+You can create your own validators as functions returning lambdas with signature
+```ruby
+lambda { |validated_object, errors_hash, path| ... }
+```
+Use `error` helper function to add errors to the error container and
+functions `validate`, `precheck` and `nil_or` to avoid boilerplate.
+
+### Example
+
+Let's say we have an ActiveRecord model Store and API allowing update of the
+store name. We will be receiving payload:
+```ruby
+{ name: 'new store name' }
+```
+We can build validator ensuring uniqueness of the store name:
+```ruby
+a_hash(
+  allowed_keys('name'),
+  key('name',
+    non_empty_string,
+    unique_store_name))
+```
+where `unique_store_name` is defined as:
+```ruby
+def unique_store_name
+  lambda do |store_name, errors, path|
+    if !Store.exists?(name: store_name)
+      true
+    else
+      error(errors, "has already been taken", store_name, path)
+    end
+  end
+end
+```
+Note that we could simplify this code by using `validate` helper method:
+```ruby
+def unique_store_name
+  validate("has already been taken") do |store_name|
+    !Store.exists?(name: store_name)
+  end
+end
+```
+We could also generalize this function and end up with generic ActiveModel
+attribute uniqueness validator ready to be reused:
+```ruby
+def unique(klass, attr_name)
+  validate("has already been taken") do |attr_value|
+    !klass.exists?(attr_name => attr_value)
+  end
+end
+
+a_hash(
+  allowed_keys('name'),
+  key('name',
+    non_empty_string,
+    unique(Store, :name)))
+```
+
+## API
+
+* `a_hash(*validators)` - ensures that the validated object is a hash and then
+  applies all `validators` in sequence using `run_all` combinator.
+
+* `allowed_keys(*allowed_keys)` - ensures that validated hash has only keys
+  provided as arguments.
+
+* `array(*validators)` - ensures that the validated object is an array and then
+  applies all `validators` in sequence using `run_all` combinator.
+
+* `at_least_one_of(*keys)` - ensures that the validated hash has at least one
+  of the keys provided as arguments.
+
+* `boolean` - ensures that validated object is `true` or `false`.
+
+* `date_string(format = /\A\d\d\d\d-\d\d-\d\d\Z/, msg = [:date_string,
+  'YYYY-MM-DD'])` - ensures that validated object is a string in a given
+  format and is parsable by `Date#parse`.
+
+* `default_errors(validator)` - helper function binding validator to the
+  default implementation of the error collection object. Returned function is
+  not a composable validator so it should only be applied to the top level
+  validator right before applying it to the object. Example:
+  ```ruby
+  errors = {}
+  default_errors(validator).call(validated_object, errors)
+  ```
+
+* `each_in_slice(range, validator)` - applies `validator` to each slice of the array. Example:
+  ```ruby
+  array(
+    each_in_slice(0..-2, normal_element_validator),
+    each_in_slice(-1..-1, special_last_element_validator))
+  ```
+
+* `each(validator)` - applies `validator` to each element of the array.
+
+* `equal(val, msg = [:equal, val])` - ensures that validated object is equal
+  `val`.
+
+* `error(errors, msg, object, *segments)` - adds error message `msg` to the
+  error collection `errors` under path `segments`. Use it in your custom
+  validators.
+
+* `exact_size(n, msg = [:exact_size, n])` - ensures that validated object has
+  size of exactly `n`. Can be applied only to objects responding to the method
+  `#size`.
+
+* `fail_fast(*validators)` - executes `validators` in sequence until one
+  of the validators returns `false` or all of them were executed.
+
+* `float(msg = :float)` - ensures that validated object is a number (parsable
+  as `Float` or `Fixnum`).
+
+* `format(regex, msg = :format)` - ensures that validated string conforms to
+  the regular expression provided.
+
+* `greater_or_equal(val, msg = [:greater_or_equal, val])` - ensures that
+  validated object is greater or equal than `val`.
+
+* `greater(val, msg = [:greater, val])` - ensures that validated object is
+  greater than `val`.
+
+* `guarded_parsing(format, msg, &blk)` - ensures that validated object is a
+  string of a given format and that it can be parsed by provided block (block
+  does not raise `ArgumentError` or `TypeError`).
+
+* `inclusion(options, msg = [:inclusion,  options])` - ensures that validated
+  object is one of the provided `options`.
+
+* `in_range(range, msg = [:in_range, range])` - ensures that validated object is
+  in given `range`.
+
+* `integer(msg = :integer)` - ensures that validated object is an integer
+  (parsable as `Fixnum`).
+
+* `just_array(msg = :just_array)` - ensures that validated object is of type
+  `Array`.
+
+* `just_hash(msg = :just_hash)` - ensures that validated object is of type
+  `Hash`.
+
+* `key_equal_to_key(key1, key2, msg = [:key_equal_to_key, key1, key2])` -
+  ensures that validated hash has equal values under keys `key1` and `key2`. If
+  any of the values are nil validator returns true.
+
+* `key_greater_or_equal_to_key(key1, key2, msg = [:key_greater_or_equal_to_key,
+  key1, key2])` - ensures that validated hash has values under keys `key1` and
+  `key2` in relation `h[key1] >= h[key2]`. If any of the values are nil
+  validator returns true.
+
+* `key_greater_than_key(key1, key2, msg = [:key_greater_than_key, key1, key2])`- 
+    ensures that validated hash has values under keys `key1` and `key2` in
+    relation `h[key1] > h[key2]`. If any of the values are nil validator
+    returns true.
+
+* `key(key, *validators)` - ensures presence of the key in the validated hash
+  and applies validators to the value under the `key` using `run_all`
+  combinator.
+
+* `key_less_or_equal_to_key(key1, key2, msg = [:key_less_or_equal_to_key, key1, key2])`- 
+    ensures that validated hash has values under keys `key1` and `key2` in
+    relation `h[key1] <= h[key2]`. If any of the values are nil validator
+    returns true.
+
+* `key_less_than_key(key1, key2, msg = [:key_less_than_key, key1, key2])`- 
+    ensures that validated hash has values under keys `key1` and `key2` in
+    relation `h[key1] < h[key2]`. If any of the values are nil validator
+    returns true.
+
+* `less_or_equal(val, msg = [:less_or_equal, val])` - ensures that
+  validated object is less or equal than `val`.
+
+* `less(val, msg = [:less, val])` - ensures that validated object is less than
+  `val`.
+
+* `max_size(n, msg = [:max_size, n])` - ensures that validated object has size
+  not greater than `n`. Can be applied only to objects responding to the method
+  `#size`.
+
+* `min_size(n, msg = [:min_size, n])` - ensures that validated object has size
+  not less than `n`. Can be applied only to objects responding to the method
+  `#size`.
+
+* `nil_or(*validators)` - helper function returning validator that returns true
+  if validated object is `nil` or applies all `validators` using `run_all`
+  combinator if validated object is not `nil`.
+
+* `non_empty(msg = :non_empty)` - ensures that validated object is not empty.
+
+* `non_empty_string(msg = :non_empty_string)` - ensures that validated object
+  is a non-empty string.
+
+* `non_negative_float` - ensures that validated object is a non-negative number.
+
+* `non_negative_integer` - ensures that validated object is a non-negative
+  integer.
+
+* `non_negative(msg = :non_negative)` - ensures that validated object is not
+  negative.
+
+* `non_negative_stringy_float` - ensures that validated object is a
+  non-negative number or string that can be parsed into non-negative number.
+  Example: both 0.1 and "0.1" are valid.
+
+* `non_negative_stringy_integer` - ensures that validated object is a
+  non-negative integer or string that can be parsed into non-negative integer.
+  Example: both 1 and "1" are valid.
+
+* `optional_key(key, *validators)` - applies `validators` to the value under
+  the `key` using `run_all` combinator. Returns `true` if `key` does not exist
+  in the validated hash.
+
+* `precheck(*validators, &blk)` - helper function returning validator that
+  returns `true` if `&blk` returns `true` or applies all `validators` using
+  `run_all` combinator if `&blk` returns `false`. Example - validate that value
+  is a number but also allow value "infinity":
+  ```ruby
+  precheck(float) { |v| v == 'infinity' }
+  ```
+
+* `presence_of_key(key, msg = :presence_of_key)` - ensures that validated hash
+  has `key`.
+
+* `run_all(*validators)` - executes all `validators` in sequence collecting all
+  error messages.
+
+* `size_range(range, msg = [:size_range, range])` - ensures that validated
+  object has size `n` in range `range`. Can be applied only to objects
+  responding to the method `#size`.
+
+* `string(msg = :string)` - ensures that validated object is of class `String`.
+
+* `stringy_float(msg = :stringy_float)` - ensures that validated object is a
+  number or string that can be parsed into number. Example: both 0.1 and "0.1"
+  are valid.
+
+* `stringy_integer(msg = :stringy_integer)` - ensures that validated object is
+  an integer or string that can be parsed into integer. Example: both 1 and
+  "1" are valid.
+
+* `time_string(format = //, msg = :time_string)` - ensures that validated
+  object is a string in a given format and is parsable by `Time#parse`.
+
+* `validate(msg, key = nil, &blk)` - helper method returning validator that
+  returns `true` if `&blk` returns `true` and `false` otherwise. `msg` is an
+  error message added to the error container when validation returns `false`.
+  Example - ensure that validated object is equal "hello":
+  ```ruby
+  validate('must be "hello"') { |v| v == 'hello' }
+  ```

data/lib/composable_validations/combinators.rb

@@ -0,0 +1,32 @@
+module ComposableValidations; end
+
+module ComposableValidations::Combinators
+  def run_all(*validators)
+    lambda do |object, errors, prefix|
+      validators.inject(true) do |acc, validator|
+        r = validator.call(object, errors, prefix)
+        acc && r
+      end
+    end
+  end
+
+  def fail_fast(*validators)
+    lambda do |object, errors, prefix|
+      validators.each do |validator|
+        return false if !validator.call(object, errors, prefix)
+      end
+      true
+    end
+  end
+
+  def nil_or(*validators)
+    precheck(*validators, &:nil?)
+  end
+
+  def precheck(*validators, &blk)
+    lambda do |object, errors, prefix|
+      return true if yield(object)
+      run_all(*validators).call(object, errors, prefix)
+    end
+  end
+end

data/lib/composable_validations/comparison.rb

@@ -0,0 +1,65 @@
+module ComposableValidations::Comparison
+  def key_to_key_comparison(key1, key2, msg, &compfun)
+    precheck(
+      validate(msg, key1) do |h|
+        v1 = h[key1]
+        v2 = h[key2]
+        compfun.call(v1, v2)
+      end
+    ) do |h|
+      h[key1].nil? || h[key2].nil?
+    end
+  end
+
+  def comparison(val, msg, &compfun)
+    validate(msg) do |v|
+      compfun.call(v, val)
+    end
+  end
+
+  def key_greater_or_equal_to_key(key1, key2, msg = [:key_greater_or_equal_to_key, key1, key2])
+    key_to_key_comparison(key1, key2, msg, &:>=)
+  end
+
+  def key_greater_than_key(key1, key2, msg = [:key_greater_than_key, key1, key2])
+    key_to_key_comparison(key1, key2, msg, &:>)
+  end
+
+  def key_less_or_equal_to_key(key1, key2, msg = [:key_less_or_equal_to_key, key1, key2])
+    key_to_key_comparison(key1, key2, msg, &:<=)
+  end
+
+  def key_less_than_key(key1, key2, msg = [:key_less_than_key, key1, key2])
+    key_to_key_comparison(key1, key2, msg, &:<)
+  end
+
+  def key_equal_to_key(key1, key2, msg = [:key_equal_to_key, key1, key2])
+    key_to_key_comparison(key1, key2, msg, &:==)
+  end
+
+  def greater_or_equal(val, msg = [:greater_or_equal, val])
+    comparison(val, msg, &:>=)
+  end
+
+  def greater(val, msg = [:greater, val])
+    comparison(val, msg, &:>)
+  end
+
+  def less_or_equal(val, msg = [:less_or_equal, val])
+    comparison(val, msg, &:<=)
+  end
+
+  def less(val, msg = [:less, val])
+    comparison(val, msg, &:<)
+  end
+
+  def equal(val, msg = [:equal, val])
+    comparison(val, msg, &:==)
+  end
+
+  def in_range(range, msg = [:in_range, range])
+    validate(msg) do |val|
+      range.include?(val)
+    end
+  end
+end

data/lib/composable_validations/default_error_messages.rb

@@ -0,0 +1,40 @@
+ComposableValidations::Errors::DEFAULT_MESSAGE_MAP = {
+  non_empty_string:            "can't be blank",
+  non_empty:                   "can't be empty",
+  allowed_keys:                "is not allowed",
+  presence_of_key:             "can't be blank",
+  just_hash:                   "must be a hash",
+  just_array:                  "must be an array",
+  string:                      "must be a string",
+  integer:                     "must be an integer",
+  stringy_integer:             "must be an integer",
+  float:                       "must be a number",
+  stringy_float:               "must be a number",
+  non_negative:                "must be greater than or equal to 0",
+  format:                      "is invalid",
+  time_string:                 "must be a time",
+  date_string:                 lambda { |object, path, format| "must be a date in format #{format}" },
+  at_least_one_of:             lambda { |object, path, keys| "at least one of #{keys.join(', ')} is required" },
+  key_greater_or_equal_to_key: lambda { |object, path, key1, key2| "must be greater than or equal to #{key2}" },
+  key_greater_than_key:        lambda { |object, path, key1, key2| "must be greater than #{key2}" },
+  key_less_or_equal_to_key:    lambda { |object, path, key1, key2| "must be less than or equal to #{key2}" },
+  key_less_than_key:           lambda { |object, path, key1, key2| "must be less than #{key2}" },
+  key_equal_to_key:            lambda { |object, path, key1, key2| "must be equal to #{key2}" },
+  greater_or_equal:            lambda { |object, path, val| "must be greater than or equal to #{val}" },
+  greater:                     lambda { |object, path, val| "must be greater than #{val}" },
+  less_or_equal:               lambda { |object, path, val| "must be less than or equal to #{val}" },
+  less:                        lambda { |object, path, val| "must be less than #{val}" },
+  equal:                       lambda { |object, path, val| "must be equal to #{val}" },
+  min_size:                    lambda { |object, path, n| "is too short (minium size is #{n})" },
+  max_size:                    lambda { |object, path, n| "is too long (maximum size is #{n})" },
+  exact_size:                  lambda { |object, path, n| "is the wrong size (should be #{n})" },
+  size_range:                  lambda { |object, path, range| "is the wrong size (minimum is #{range.min} and maximum is #{range.max})" },
+  in_range:                    lambda { |object, path, range| "must be in range #{range.min}..#{range.max}" },
+  inclusion:                   lambda do |object, path, options|
+    if options.length > 10
+      "is not allowed"
+    else
+      "must be one of: #{options.join(', ')}"
+    end
+  end
+}

data/lib/composable_validations/errors.rb

@@ -0,0 +1,48 @@
+class ComposableValidations::Errors
+  def initialize(errors, message_map = nil)
+    @errors = errors
+    @message_map = DEFAULT_MESSAGE_MAP.merge(message_map || {})
+  end
+
+  def add(msg, path, object)
+    merge(@errors, {join(path) => [render_message(msg, path, object)]})
+  end
+
+  def to_hash
+    @errors
+  end
+
+  private
+
+  def render_message(msg, path, object)
+    message = Array(msg)
+    message_builder = @message_map.fetch(message.first, msg)
+    if message_builder.is_a?(Proc)
+      message_builder.call(object, path, *msg[1..-1])
+    else
+      message_builder
+    end
+  end
+
+  def merge(e1, e2)
+    e2.keys.each do |k, v|
+      e1[k] = ((e1[k] || []) + (e2[k] || [])).uniq
+    end
+  end
+
+  def join(segments)
+    if segments.empty?
+      segments[0] = base_key
+    end
+
+    segments.compact.join(separator)
+  end
+
+  def base_key
+    'base'
+  end
+
+  def separator
+    '/'
+  end
+end

data/lib/composable_validations/utils.rb

@@ -0,0 +1,29 @@
+module ComposableValidations::Utils
+  def default_errors(validator)
+    lambda do |object, errors_hash|
+      errors = ComposableValidations::Errors.new(errors_hash)
+      validator.call(object, errors, nil)
+    end
+  end
+
+  def join(*segments)
+    segments.inject([]) do |acc, seg|
+      acc + Array(seg)
+    end
+  end
+
+  def validate(msg, key = nil, &blk)
+    lambda do |o, errors, prefix|
+      if yield(o)
+        true
+      else
+        error(errors, msg, o, prefix, key)
+      end
+    end
+  end
+
+  def error(errors, msg, object, *segments)
+    errors.add(msg, join(*segments), object)
+    false
+  end
+end

data/lib/composable_validations/version.rb

@@ -0,0 +1,3 @@
+module ComposableValidations
+  VERSION = '0.0.9'
+end

data/lib/composable_validations.rb

@@ -0,0 +1,218 @@
+require 'date'
+require 'time'
+
+require_relative 'composable_validations/version'
+require_relative 'composable_validations/combinators'
+require_relative 'composable_validations/utils'
+require_relative 'composable_validations/comparison'
+require_relative 'composable_validations/errors'
+require_relative 'composable_validations/default_error_messages'
+
+module ComposableValidations
+  include ComposableValidations::Combinators
+  include ComposableValidations::Utils
+  include ComposableValidations::Comparison
+
+  # it is named with prefix 'a_' to avoid conflict with built in hash method
+  def a_hash(*validators)
+    fail_fast(just_hash, run_all(*validators))
+  end
+
+  def array(*validators)
+    fail_fast(
+      just_array,
+      run_all(*validators))
+  end
+
+  def each(validator)
+    each_in_slice(0..-1, validator)
+  end
+
+  def each_in_slice(range, validator)
+    lambda do |a, errors, prefix|
+      slice = a.slice(range) || []
+      slice.inject([true, 0]) do |(acc, index), elem|
+        suffix = to_index(a, range.begin) + index
+        b = validator.call(elem, errors, join(prefix, suffix))
+        [acc && b, index + 1]
+      end.first
+    end
+  end
+
+  def to_index(array, range_index)
+    indexes = array.map.with_index { |_, i| i }
+    indexes[range_index]
+  end
+
+  def allowed_keys(*allowed_keys)
+    lambda do |h, errors, prefix|
+      h.keys.inject(true) do |acc, key|
+        if !allowed_keys.include?(key)
+          error(errors, :allowed_keys, h, prefix, key)
+        else
+          acc && true
+        end
+      end
+    end
+  end
+
+  def key(key, *validators)
+    fail_fast(
+      presence_of_key(key),
+      lambda do |h, errors, prefix|
+        run_all(*validators).call(h[key], errors, join(prefix, key))
+      end
+    )
+  end
+
+  def optional_key(key, *validators)
+    lambda do |h, errors, prefix|
+      if h.has_key?(key)
+        key(key, *validators).call(h, errors, prefix)
+      else
+        true
+      end
+    end
+  end
+
+  def just_hash(msg = :just_hash)
+    just_type(Hash, msg)
+  end
+
+  def just_array(msg = :just_array)
+    just_type(Array, msg)
+  end
+
+  def string(msg = :string)
+    just_type(String, msg)
+  end
+
+  def non_empty_string(msg = :non_empty_string)
+    fail_fast(
+      string,
+      validate(msg) { |s| s.strip != '' })
+  end
+
+  def integer(msg = :integer)
+    just_type(Fixnum, msg)
+  end
+
+  def stringy_integer(msg = :stringy_integer)
+    parsing(msg) { |v| Integer(v.to_s) }
+  end
+
+  def float(msg = :float)
+    just_types(msg, Float, Fixnum)
+  end
+
+  def stringy_float(msg = :stringy_float)
+    parsing(msg) { |v| Float(v.to_s) }
+  end
+
+  def non_negative_float
+    fail_fast(float, non_negative)
+  end
+
+  def non_negative_integer
+    fail_fast(integer, non_negative)
+  end
+
+  def non_negative_stringy_float
+    fail_fast(stringy_float, non_negative)
+  end
+
+  def non_negative_stringy_integer
+    fail_fast(stringy_integer, non_negative)
+  end
+
+  def non_negative(msg = :non_negative)
+    validate(msg) { |v| Float(v.to_s) >= 0 }
+  end
+
+  def date_string(format = /\A\d\d\d\d-\d\d-\d\d\Z/, msg = [:date_string, 'YYYY-MM-DD'])
+    guarded_parsing(format, msg) { |v| Date.parse(v) }
+  end
+
+  def time_string(format = //, msg = :time_string)
+    guarded_parsing(format, msg) { |v| Time.parse(v) }
+  end
+
+  def format(regex, msg = :format)
+    validate(msg) { |val| regex.match(val) }
+  end
+
+  def guarded_parsing(format, msg, &blk)
+    fail_fast(
+      string(msg),
+      format(format, msg),
+      parsing(msg, &blk))
+  end
+
+  def parsing(msg, &blk)
+    validate(msg) do |val|
+      begin
+        yield(val)
+        true
+      rescue ArgumentError, TypeError
+        false
+      end
+    end
+  end
+
+  def just_type(type, msg)
+    just_types(msg, type)
+  end
+
+  def just_types(msg, *types)
+    validate(msg) do |v|
+      types.inject(false) do |acc, type|
+        acc || v.is_a?(type)
+      end
+    end
+  end
+
+  def boolean
+    inclusion([true, false])
+  end
+
+  def inclusion(options, msg = [:inclusion,  options])
+    validate(msg) { |v| options.include?(v) }
+  end
+
+  def presence_of_key(key, msg = :presence_of_key)
+    validate(:presence_of_key, key) { |h| h.has_key?(key) }
+  end
+
+  def non_empty(msg = :non_empty)
+    validate(msg) { |v| !v.empty? }
+  end
+
+  def at_least_one_of(*keys)
+    validate([:at_least_one_of, keys]) do |h|
+      count = h.keys.count { |k| keys.include?(k) }
+      count > 0
+    end
+  end
+
+  def size(validator)
+    lambda do |object, errors, path|
+      validator.call(object.size, errors, path)
+    end
+  end
+
+  def min_size(n, msg = [:min_size, n])
+    size(greater_or_equal(n, msg))
+  end
+
+  def max_size(n, msg = [:max_size, n])
+    size(less_or_equal(n, msg))
+  end
+
+  def exact_size(n, msg = [:exact_size, n])
+    size(equal(n, msg))
+  end
+
+  def size_range(range, msg = [:size_range, range])
+    size(in_range(range, msg))
+  end
+end

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification
+name: composable_validations
+version: !ruby/object:Gem::Version
+  version: 0.0.9
+platform: ruby
+authors:
+- Kajetan Bojko
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-02-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3'
+description: Gem for validating complex JSON payloads in a functional way
+email: kai@shutl.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/composable_validations.rb
+- lib/composable_validations/combinators.rb
+- lib/composable_validations/comparison.rb
+- lib/composable_validations/default_error_messages.rb
+- lib/composable_validations/errors.rb
+- lib/composable_validations/utils.rb
+- lib/composable_validations/version.rb
+homepage: https://github.com/shutl/composable_validations
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- .
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.6
+signing_key: 
+specification_version: 4
+summary: Gem for validating complex JSON payloads
+test_files: []