datacaster 3.1.0 → 3.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c42f42112214378de25b126640a7bb578532c1db0ac9fbb73914ef3c08db76e2
-  data.tar.gz: 0abba877a155d717b0aa2cb605c9214789c839b381492984cb277a1523c5a7a1
+  metadata.gz: 22f1741420c172f91fba9bf20a341a785f609a7e0132e74bcd3a07e6069eaca4
+  data.tar.gz: 641fb863b7a40931f481d066e09062cddff1a4e3ff642d5981dacf9bfaa036eb
 SHA512:
-  metadata.gz: 4b07733981e971af666cf9a7688cd35f4a32b80eb2e4a53505620425027f5fdd963c7c63717f6888fe700df4ef6c5eb175a07aac7183cb0df29dd1e8b97fe446
-  data.tar.gz: a596b40d1ebff4e8abc455bdde09c01b0f1499a35cee44daca329885277448cbe6f66268d568a091fa78e83e0da7adf9d9cb09df0c5711d4bc3243d3b909a886
+  metadata.gz: 2a3573aac6a44ef0a5849da04325c9089119ad529cc6f6384d18bb6dda97f66358081c27d1fc260d95f7adaec5937bda7769cd9207ea9be6b01f2547f4425659
+  data.tar.gz: '04765854fbe156b3418728d4d2392b78ce0837ead8e1e72b76a51d55e6227bb68eebf8a98e672c924205bbe731610f21c72a1be355c51c2f014886ab160efdb7'

data/README.md

@@ -32,12 +32,12 @@ It is currently used in production in several projects (mainly as request parame
     - [`integer32(error_key = nil)`](#integer32error_key--nil)
     - [`non_empty_string(error_key = nil)`](#non_empty_stringerror_key--nil)
   - [Special types](#special-types)
-    - [`absent(error_key = nil)`](#absenterror_key--nil)
+    - [`absent(error_key = nil, on: nil)`](#absenterror_key--nil-on-nil)
     - [`any(error_key = nil)`](#anyerror_key--nil)
     - [`default(default_value, on: nil)`](#defaultdefault_value-on-nil)
     - [`merge_message_keys(*keys)`](#merge_message_keyskeys)
     - [`must_be(klass, error_key = nil)`](#must_beklass-error_key--nil)
-    - [`optional(base)`](#optionalbase)
+    - [`optional(base, on: nil)`](#optionalbase-on-nil)
     - [`pass`](#pass)
     - [`pass_if(base)`](#pass_ifbase)
     - [`pick(key)`](#pickkey)
@@ -56,6 +56,8 @@ It is currently used in production in several projects (mainly as request parame
     - [`try(error_key = nil, catched_exception:) { |value| ... }`](#tryerror_key--nil-catched_exception--value--)
     - [`validate(active_model_validations, name = 'Anonymous')`](#validateactive_model_validations-name--anonymous)
     - [`compare(reference_value, error_key = nil)`](#comparereference_value-error_key--nil)
+    - [`included_in(*reference_values, error_key: nil)`](#included_inreference_values-error_key-nil)
+    - [`relate(left, op, right, error_key: nil)`](#relateleft-op-right-error_key-nil)
     - [`transform { |value| ... }`](#transform--value--)
     - [`transform_if_present { |value| ... }`](#transform_if_present--value--)
   - [Array schemas](#array-schemas)
@@ -175,10 +177,10 @@ array = Datacaster.schema { array }
 array.(nil)
 
 # In this README
-#=> Datacaster::ErrorResult(['should be an array'])
+# => Datacaster::ErrorResult(['should be an array'])
 
 # In reality
-#=> <Datacaster::ErrorResult([#<Datacaster::I18nValues::Key(.array, datacaster.errors.array) {:value=>nil}>])>
+# => <Datacaster::ErrorResult([#<Datacaster::I18nValues::Key(.array, datacaster.errors.array) {:value=>nil}>])>
 ```
 
 See [section on i18n](#internationalization-i18n) for details.
@@ -502,9 +504,16 @@ Returns ValidResult if and only if provided value is a string and is not empty.
 
 ### Special types
 
-#### `absent(error_key = nil)`
+#### `absent(error_key = nil, on: nil)`
 
-Returns ValidResult if and only if provided value is `Datacaster.absent` (this is singleton instance). Relevant only for hash schemas (see below). Doesn't transform the value.
+Returns ValidResult if and only if provided value is absent. Relevant only for hash schemas (see below). Transforms the value to `Datacaster.absent`.
+
+The value is considered absent:
+
+* if the value is `Datacaster.absent` (`on` is disregarded in such case)
+* if `on` is set to a method name to which the value responds and yields truthy
+
+Set `on` to `:nil?`, `:empty?` or similar method names.
 
 I18n keys: `error_key`, `'.absent'`, `'datacaster.errors.absent'`.
 
@@ -636,18 +645,25 @@ Returns ValidResult if and only if the value `#is_a?(klass)`. Doesn't transform
 
 I18n keys: `error_key`,  `'.must_be'`, `'datacaster.errors.must_be'`. Adds `reference` i18n variable, setting it to `klass.name`. 
 
-#### `optional(base)`
+#### `optional(base, on: nil)`
 
-Returns ValidResult if and only if the value is either `Datacaster.absent` or passes `base` validation. See below documentation on hash schemas for details on `Datacaster.absent`.
+Returns ValidResult if and only if the value is either absent or passes `base` validation. In the value is absent, transforms it to the `Datacaster.absent`. Otherwise, returns `base` result.
+
+Value is considered absent:
+
+* if the value is `Datacaster.absent` (`on` is disregarded in such case)
+* if `on` is set to a method name to which the value responds and yields truthy
+
+Set `on` to `:nil?`, `:empty?` or similar method names.
 
 ```ruby
 item_with_optional_price =
-    Datacaster.schema do
-      hash_schema(
-        name: string,
-        price: optional(float)
-      )
-    end
+  Datacaster.schema do
+    hash_schema(
+      name: string,
+      price: optional(float)
+    )
+  end
 
 item_with_optional_price.(name: "Book", price: 1.23)
 # => Datacaster::ValidResult({:name=>"Book", :price=>1.23})
@@ -868,8 +884,6 @@ I18n is performed by ActiveModel gem.
 
 #### `compare(reference_value, error_key = nil)`
 
-This type is the way to ensure some value in your schema is some predefined "constant".
-
 Returns ValidResult if and only if `reference_value` equals value.
 
 ```ruby
@@ -883,6 +897,50 @@ agreed_with_tos =
 
 I18n keys: `error_key`, `'.compare'`, `'datacaster.errors.compare'`. Adds `reference` i18n variable, setting it to `reference_value.to_s`.
 
+#### `included_in(*reference_values, error_key: nil)`
+
+Returns ValidResult if and only if `reference_values.include?` the value.
+
+I18n keys: `error_key`, `'.included_in'`, `'datacaster.errors.included_in'`. Adds `reference` i18n variable, setting it to `reference_values.map(&:to_s).join(', ')`.
+
+#### `relate(left, op, right, error_key: nil)`
+
+Returns ValidResult if and only if `left`, `right` and `op` returns valid result. Doesn't transform the value.
+
+Use `relate` to check relations between object keys:
+
+```ruby
+ordered =
+  # Check that hash[:a] < hash[:b]
+  Datacaster.schema do
+    transform_to_hash(
+      a: relate(:a, :<, :b) & pick(:a),
+      b: pick(:b)
+    )
+  end
+
+ordered.(a: 1, b: 2)
+# => Datacaster::ValidResult({:a=>1, :b=>2})
+
+ordered.(a: 2, b: 1)
+# => Datacaster::ErrorResult({:a=>["a should be < b"]})
+
+ordered.({})
+# => Datacaster::ErrorResult({:a=>["a should be < b"]})
+```
+
+Notice that shortcut definitions are available (illustrated in the example above) for the `relate` caster:
+
+* `:key` provided as 'left' or 'right' argument is exactly the same as `pick(:key)` (works for a string, a symbol or an integer)
+* `:method` provided as 'op' argument is exactly the same as `check { |(l, r)| l.respond_to?(method) && l.public_send(method, r) }` (works for a string or a symbol)
+
+Formally, `relate(left, op, right, error_key: error_key)` will:
+
+* call the `left` caster with the original value, return the result unless it's valid
+* call the `right` caster with the original value, return the result unless it's valid
+* call the `op` caster with the `[left_result, right_result]`, return the result unless it's valid
+* return the original value as valid result
+
 #### `transform { |value| ... }`
 
 Always returns ValidResult. Transforms the value: returns whatever the block has returned.
@@ -1025,7 +1083,7 @@ restricted_params.(username: "test", is_admin: nil)
 
 More practical case is to include `absent` validator in logical expressions, e.g. `something: absent | string`. If `something` is set to `nil`, this validation will fail, which could be the desired (and hardly achieved by any other validation framework) behavior.
 
-Also, see documentation for [`optional(base)`](#optionalbase) and [`optional_param(base)`](#optional_parambase). If some value becomes `Datacaster.absent` in its chain of validations-transformations, it is removed from the resultant hash (on the same stage where the lack of extra/unchecked keys in the hash is validated):
+Also, see documentation for [`optional(base)`](#optionalbase-on-nil) and [`optional_param(base)`](#optional_parambase). If some value becomes `Datacaster.absent` in its chain of validations-transformations, it is removed from the resultant hash (on the same stage where the lack of extra/unchecked keys in the hash is validated):
 
 ```ruby
 person =

data/config/locales/en.yml

@@ -11,10 +11,12 @@ en:
       empty: should not be empty
       float: is not a float
       hash_value: is not a hash
+      included_in: is not one of %{reference}
       integer: is not an integer
       integer32: is not a 32-bit integer
       iso8601: is not a string with ISO-8601 date and time
       must_be: "is not %{reference}"
+      relate: "%{left} should be %{op} %{right}"
       responds_to: "does not respond to %{reference}"
       string: is not a string
       to_boolean: does not look like a boolean

data/lib/datacaster/and_with_error_aggregation_node.rb

@@ -17,7 +17,7 @@ module Datacaster
         if right_result.valid?
           left_result
         else
-          Datacaster.ErrorResult(self.class.merge_errors(left_result.raw_errors, right_result.raw_errors))
+          Datacaster.ErrorResult(Utils.merge_errors(left_result.raw_errors, right_result.raw_errors))
         end
       end
     end

data/lib/datacaster/base.rb

@@ -1,97 +1,5 @@
 module Datacaster
   class Base
-    def self.merge_errors(left, right)
-      add_error_to_base = ->(hash, error) {
-        hash[:base] ||= []
-        hash[:base] = merge_errors(hash[:base], error)
-        hash
-      }
-
-      return [] if left.nil? && right.nil?
-      return right if left.nil?
-      return left if right.nil?
-
-      result = case [left.class, right.class]
-      when [Array, Array]
-        left | right
-      when [Array, Hash]
-        add_error_to_base.(right, left)
-      when [Hash, Hash]
-        (left.keys | right.keys).map do |k|
-          [k, merge_errors(left[k], right[k])]
-        end.to_h
-      when [Hash, Array]
-        add_error_to_base.(left, right)
-      else
-        raise ArgumentError.new("Expected failures to be Arrays or Hashes, left: #{left.inspect}, right: #{right.inspect}")
-      end
-
-      result
-    end
-
-    def &(other)
-      AndNode.new(self, other)
-    end
-
-    def |(other)
-      OrNode.new(self, other)
-    end
-
-    def *(other)
-      AndWithErrorAggregationNode.new(self, other)
-    end
-
-    def cast_errors(error_caster)
-      ContextNodes::ErrorsCaster.new(self, error_caster)
-    end
-
-    def then(other)
-      ThenNode.new(self, DefinitionDSL.expand(other))
-    end
-
-    def with_context(context)
-      unless context.is_a?(Hash)
-        raise "with_context expected Hash as argument, got #{context.inspect} instead"
-      end
-      ContextNodes::UserContext.new(self, context)
-    end
-
-    def call(object)
-      call_with_runtime(object, Runtimes::Base.new)
-    end
-
-    def call_with_runtime(object, runtime)
-      result = cast(object, runtime: runtime)
-      unless result.is_a?(Result)
-        raise RuntimeError.new("Caster should've returned Datacaster::Result, but returned #{result.inspect} instead")
-      end
-      result
-    end
-
-    def with_runtime(runtime)
-      ->(object) do
-        call_with_runtime(object, runtime)
-      end
-    end
-
-    def i18n_key(*keys, **args)
-      ContextNodes::I18n.new(self, I18nValues::Key.new(keys, args))
-    end
-
-    def i18n_map_keys(mapping)
-      ContextNodes::I18nKeysMapper.new(self, mapping)
-    end
-
-    def i18n_scope(scope, **args)
-      ContextNodes::I18n.new(self, I18nValues::Scope.new(scope, args))
-    end
-
-    def i18n_vars(vars)
-      ContextNodes::I18n.new(self, I18nValues::Scope.new(nil, vars))
-    end
-
-    def inspect
-      "#<Datacaster::Base>"
-    end
+    include Mixin
   end
 end

data/lib/datacaster/caster.rb

@@ -9,13 +9,13 @@ module Datacaster
     def cast(object, runtime:)
       result = Runtimes::Base.(runtime, @cast, object)
 
-      raise TypeError.new("Either Datacaster::Result or Dry::Monads::Result " \
-        "should be returned from cast block") unless [Datacaster::Result, Dry::Monads::Result].any? { |k| result.is_a?(k) }
-
-      if result.is_a?(Dry::Monads::Result)
+      if defined?(Dry::Monads::Result) && result.is_a?(Dry::Monads::Result)
         result = result.success? ? Datacaster.ValidResult(result.value!) : Datacaster.ErrorResult(result.failure)
       end
 
+      raise TypeError.new("Either Datacaster::Result or Dry::Monads::Result " \
+        "should be returned from cast block") unless result.is_a?(Datacaster::Result)
+
       result
     end
 

data/lib/datacaster/hash_mapper.rb

@@ -45,9 +45,9 @@ module Datacaster
           end
         else
           if key.is_a?(Array)
-            errors = self.class.merge_errors(errors, key.zip(new_value.raw_errors).to_h)
+            errors = Utils.merge_errors(errors, key.zip(new_value.raw_errors).to_h)
           else
-            errors = self.class.merge_errors(errors, {key => new_value.raw_errors})
+            errors = Utils.merge_errors(errors, {key => new_value.raw_errors})
           end
         end
       end

data/lib/datacaster/mixin.rb

@@ -0,0 +1,68 @@
+module Datacaster
+  module Mixin
+    def &(other)
+      AndNode.new(self, other)
+    end
+
+    def |(other)
+      OrNode.new(self, other)
+    end
+
+    def *(other)
+      AndWithErrorAggregationNode.new(self, other)
+    end
+
+    def cast_errors(error_caster)
+      ContextNodes::ErrorsCaster.new(self, error_caster)
+    end
+
+    def then(other)
+      ThenNode.new(self, DefinitionDSL.expand(other))
+    end
+
+    def with_context(context)
+      unless context.is_a?(Hash)
+        raise "with_context expected Hash as argument, got #{context.inspect} instead"
+      end
+      ContextNodes::UserContext.new(self, context)
+    end
+
+    def call(object)
+      call_with_runtime(object, Runtimes::Base.new)
+    end
+
+    def call_with_runtime(object, runtime)
+      result = cast(object, runtime: runtime)
+      unless result.is_a?(Result)
+        raise RuntimeError.new("Caster should've returned Datacaster::Result, but returned #{result.inspect} instead")
+      end
+      result
+    end
+
+    def with_runtime(runtime)
+      ->(object) do
+        call_with_runtime(object, runtime)
+      end
+    end
+
+    def i18n_key(*keys, **args)
+      ContextNodes::I18n.new(self, I18nValues::Key.new(keys, args))
+    end
+
+    def i18n_map_keys(mapping)
+      ContextNodes::I18nKeysMapper.new(self, mapping)
+    end
+
+    def i18n_scope(scope, **args)
+      ContextNodes::I18n.new(self, I18nValues::Scope.new(scope, args))
+    end
+
+    def i18n_vars(vars)
+      ContextNodes::I18n.new(self, I18nValues::Scope.new(nil, vars))
+    end
+
+    def inspect
+      "#<Datacaster::Base>"
+    end
+  end
+end

data/lib/datacaster/predefined.rb

@@ -67,10 +67,20 @@ module Datacaster
 
     # 'Meta' types
 
-    def absent(error_key = nil)
+    def absent(error_key = nil, on: nil)
       error_keys = ['.absent', 'datacaster.errors.absent']
       error_keys.unshift(error_key) if error_key
-      check { |x| x == Datacaster.absent }.i18n_key(*error_keys)
+
+      cast do |x|
+        if x == Datacaster.absent ||
+          (!on.nil? && x.respond_to?(on) && x.public_send(on))
+          Datacaster.ValidResult(Datacaster.absent)
+        else
+          Datacaster.ErrorResult(
+            I18nValues::Key.new(error_keys, value: x)
+          )
+        end
+      end
     end
 
     def any(error_key = nil)
@@ -82,7 +92,7 @@ module Datacaster
     def default(value, on: nil)
       transform do |x|
         if x == Datacaster.absent ||
-          (on && x.respond_to?(on) && x.public_send(on))
+          (!on.nil? && x.respond_to?(on) && x.public_send(on))
           value
         else
           x
@@ -94,6 +104,52 @@ module Datacaster
       transform { value }
     end
 
+    # min_amount: has_relation(:min_amount, :>, :max_amount)
+
+    def relate(left, op, right, error_key: nil)
+      error_keys = ['.relate', 'datacaster.errors.relate']
+      additional_vars = {}
+
+      {left: left, op: op, right: right}.each do |k, v|
+        if [String, Symbol, Integer].any? { |c| v.is_a?(c) }
+          additional_vars[k] = v
+        elsif !Datacaster.instance?(v)
+          raise RuntimeError, "expected #{k} to be String, Symbol, Integer or Datacaster::Base, but got #{v.inspect}", caller
+        end
+      end
+
+      if op.is_a?(Integer)
+        raise RuntimeError, "expected op to be String, Symbol or Datacaster::Base, but got #{op.inspect}", caller
+      end
+
+      if [left, op, right].none? { |x| Datacaster.instance?(x) }
+        error_keys.unshift(".#{left}.#{op}.#{right}")
+      end
+      error_keys.unshift(error_key) if error_key
+
+      left = pick(left) unless Datacaster.instance?(left)
+      right = pick(right) unless Datacaster.instance?(right)
+      op_caster = op
+      unless Datacaster.instance?(op_caster)
+        op_caster = check { |(l, r)| l.respond_to?(op) && l.public_send(op, r) }
+      end
+
+      cast do |value|
+        left_result = left.(value)
+        next left_result unless left_result.valid?
+        i18n_var!(:left, left_result.value) unless additional_vars.key?(:left)
+
+        right_result = right.(value)
+        next right_result unless right_result.valid?
+        i18n_var!(:right, right_result.value) unless additional_vars.key?(:right)
+
+        result = op_caster.([left_result.value, right_result.value])
+        next Datacaster.ErrorResult([I18nValues::Key.new(error_keys)]) unless result.valid?
+
+        Datacaster.ValidResult(value)
+      end.i18n_vars(additional_vars)
+    end
+
     def remove
       transform { Datacaster.absent }
     end
@@ -153,8 +209,16 @@ module Datacaster
       check { |x| x.is_a?(klass) }.i18n_key(*error_keys, reference: klass.name)
     end
 
-    def optional(base)
-      absent | base
+    def optional(base, on: nil)
+      return absent | base if on == nil
+      cast do |x|
+        if x == Datacaster.absent ||
+          (!on.nil? && x.respond_to?(on) && x.public_send(on))
+          Datacaster.ValidResult(Datacaster.absent)
+        else
+          base.(x)
+        end
+      end
     end
 
     # Strict types
@@ -187,13 +251,19 @@ module Datacaster
     def hash_value(error_key = nil)
       error_keys = ['.hash_value', 'datacaster.errors.hash_value']
       error_keys.unshift(error_key) if error_key
-      check(error_key) { |x| x.is_a?(Hash) }
+      check { |x| x.is_a?(Hash) }.i18n_key(*error_keys)
     end
 
     def hash_with_symbolized_keys(error_key = nil)
       hash_value(error_key) & transform { |x| x.symbolize_keys }
     end
 
+    def included_in(*values, error_key: nil)
+      error_keys = ['.included_in', 'datacaster.errors.included_in']
+      error_keys.unshift(error_key) if error_key
+      check { |x| values.include?(x) }.i18n_key(*error_keys, reference: values.map(&:to_s).join(', '))
+    end
+
     def integer(error_key = nil)
       error_keys = ['.integer', 'datacaster.errors.integer']
       error_keys.unshift(error_key) if error_key

data/lib/datacaster/utils.rb

@@ -0,0 +1,34 @@
+module Datacaster
+  module Utils
+    extend self
+
+    def merge_errors(left, right)
+      add_error_to_base = ->(hash, error) {
+        hash[:base] ||= []
+        hash[:base] = merge_errors(hash[:base], error)
+        hash
+      }
+
+      return [] if left.nil? && right.nil?
+      return right if left.nil?
+      return left if right.nil?
+
+      result = case [left.class, right.class]
+      when [Array, Array]
+        left | right
+      when [Array, Hash]
+        add_error_to_base.(right, left)
+      when [Hash, Hash]
+        (left.keys | right.keys).map do |k|
+          [k, merge_errors(left[k], right[k])]
+        end.to_h
+      when [Hash, Array]
+        add_error_to_base.(left, right)
+      else
+        raise ArgumentError.new("Expected failures to be Arrays or Hashes, left: #{left.inspect}, right: #{right.inspect}")
+      end
+
+      result
+    end
+  end
+end

data/lib/datacaster/version.rb

@@ -1,3 +1,3 @@
 module Datacaster
-  VERSION = "3.1.0"
+  VERSION = "3.1.2"
 end

data/lib/datacaster.rb

@@ -24,6 +24,10 @@ module Datacaster
     Datacaster::Absent.instance
   end
 
+  def instance?(object)
+    object.is_a?(Mixin)
+  end
+
   private
 
   def build_schema(i18n_scope: nil, &block)
@@ -31,7 +35,7 @@ module Datacaster
 
     datacaster = DefinitionDSL.eval(&block)
 
-    unless datacaster.is_a?(Base)
+    unless Datacaster.instance?(datacaster)
       raise "Datacaster instance should be returned from a block (e.g. result of 'hash_schema(...)' call)"
     end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: datacaster
 version: !ruby/object:Gem::Version
-  version: 3.1.0
+  version: 3.1.2
 platform: ruby
 authors:
 - Eugene Zolotarev
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-10-02 00:00:00.000000000 Z
+date: 2023-10-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -150,6 +150,7 @@ files:
 - lib/datacaster/i18n_values/key.rb
 - lib/datacaster/i18n_values/scope.rb
 - lib/datacaster/message_keys_merger.rb
+- lib/datacaster/mixin.rb
 - lib/datacaster/or_node.rb
 - lib/datacaster/predefined.rb
 - lib/datacaster/result.rb
@@ -162,6 +163,7 @@ files:
 - lib/datacaster/then_node.rb
 - lib/datacaster/transformer.rb
 - lib/datacaster/trier.rb
+- lib/datacaster/utils.rb
 - lib/datacaster/validator.rb
 - lib/datacaster/version.rb
 homepage: https://github.com/EugZol/datacaster