datacaster 3.0.0 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3b77dec970a054162cb38f106f29f74a505d5c0e3084d46b8c578c2657b63078
-  data.tar.gz: ea0b92d48730865ed975c5354e304a6f2baaafd3672af83796763ea968aafe73
+  metadata.gz: c42f42112214378de25b126640a7bb578532c1db0ac9fbb73914ef3c08db76e2
+  data.tar.gz: 0abba877a155d717b0aa2cb605c9214789c839b381492984cb277a1523c5a7a1
 SHA512:
-  metadata.gz: 196c625a37388f5debe9ae393f2abcddbedef154e874ce37bc7b5c392d19cfe67921f5aca62321c38fb4d7e7ca8cc825f903e69ebc9e36c62780c9f545116b15
-  data.tar.gz: f2e4dbe9fa520f51080ad6140fefed7ca87dab429f7af9d720582ee6378be5279607340d444ccdd8125ea0b8f23eff9da7b2c0e5c0055faff92bb10b3235887c
+  metadata.gz: 4b07733981e971af666cf9a7688cd35f4a32b80eb2e4a53505620425027f5fdd963c7c63717f6888fe700df4ef6c5eb175a07aac7183cb0df29dd1e8b97fe446
+  data.tar.gz: a596b40d1ebff4e8abc455bdde09c01b0f1499a35cee44daca329885277448cbe6f66268d568a091fa78e83e0da7adf9d9cb09df0c5711d4bc3243d3b909a886

data/README.md

@@ -15,9 +15,10 @@ It is currently used in production in several projects (mainly as request parame
   - [Result value](#result-value)
   - [Hash schema](#hash-schema)
   - [Logical operators](#logical-operators)
-    - [*AND operator*:](#and-operator)
-    - [*OR operator*:](#or-operator)
-    - [*IF... THEN... ELSE operator*:](#if-then-else-operator)
+    - [*AND operator*](#and-operator)
+    - [*OR operator*](#or-operator)
+    - [*IF... THEN... ELSE operator*](#if-then-else-operator)
+    - [*SWITCH... ON... ELSE operator*](#switch-on-else-operator)
 - [Built-in types](#built-in-types)
   - [Basic types](#basic-types)
     - [`array(error_key = nil)`](#arrayerror_key--nil)
@@ -38,6 +39,7 @@ It is currently used in production in several projects (mainly as request parame
     - [`must_be(klass, error_key = nil)`](#must_beklass-error_key--nil)
     - [`optional(base)`](#optionalbase)
     - [`pass`](#pass)
+    - [`pass_if(base)`](#pass_ifbase)
     - [`pick(key)`](#pickkey)
     - [`remove`](#remove)
     - [`responds_to(method, error_key = nil)`](#responds_tomethod-error_key--nil)
@@ -266,7 +268,7 @@ And one special: AND with error aggregation (`*`).
 
 The former 3 is described immediately below, and the latter is described in the section on hash schemas further in this file.
 
-#### *AND operator*:
+#### *AND operator*
 
 ```ruby
 even_number = Datacaster.schema { integer & check { |x| x.even? } }
@@ -282,7 +284,7 @@ even_number.("test")
 
 If left-hand validation of AND operator passes, *its result* (not the original value) is passed to the right-hand validation. See below in this file section on transformations where this might be relevant.
 
-#### *OR operator*:
+#### *OR operator*
 
 ```ruby
 # 'compare' custom type returns ValidResult if and only if validated value == compare's argument
@@ -296,12 +298,57 @@ person_or_entity.(:ngo)    # => Datacaster::ErrorResult(["does not equal :entity
 
 Notice that OR operator, if left-hand validation fails, passes the original value to the right-hand validation. As you see in the example above resultant error messages are not always convenient (i.e. to show something like "value must be :person or :entity" is preferable to showing somewhat misleading "must be equal to :entity"). See the next section on "IF... THEN... ELSE" for closer to the real world example.
 
-#### *IF... THEN... ELSE operator*:
+#### *IF... THEN... ELSE operator*
 
-Let's suppose we want to validate that incoming hash is either 'person' or 'entity', where
+Let's support we want to run different validations depending on some value, e.g.:
 
-- 'person' is a hash with 3 keys (kind: `:person`, name: string, salary: integer),
-- 'entity' is a hash with 4 keys (kind: `:entity`, title: string, form: string, revenue: integer).
+* if 'salary' is more than 100_000, check for the additional key, 'passport'
+* otherwise, ensure 'passport' key is absent
+* in any case, check that 'name' key is present and is a string
+
+```ruby
+applicant =
+  Datacaster.schema do
+    base = hash_schema(
+      name: string,
+      salary: integer
+    )
+
+    large_salary = check { |x| x[:salary] > 100_000 }
+
+    base &
+      large_salary.
+        then(passport: string).
+        else(passport: absent)
+  end
+
+applicant.(name: 'John', salary: 50_000)
+# => Datacaster::ValidResult({:name=>"John", :salary=>50000})
+
+applicant.(name: 'Jane', salary: 101_000, passport: 'AB123CD')
+# => Datacaster::ValidResult({:name=>"Jane", :salary=>101000, :passport=>"AB123CD"})
+
+applicant.(name: 'George', salary: 101_000)
+# => Datacaster::ErrorResult({:passport=>["is not a string"])
+```
+
+Formally, with `a.then(b).else(c)`:
+
+* if `a` returns `ValidResult`, then `b` is called *with the result of `a`* (not the original value) and whatever `b` returns is returned;
+* otherwise, `c` is called with the original value, and whatever `c` returns is returned.
+
+`else`-part is required and could not be omitted.
+
+Note: this construct is *not* an equivalent of `a & b | c`.
+
+With `a.then(b).else(c)` if `a` and `b` fails, then `b`'s error is returned. With `a & b | c`, instead, `c`'s result would be returned.
+
+#### *SWITCH... ON... ELSE operator*
+
+Let's suppose we want to validate that incoming hash is either 'person' or 'entity', where:
+
+* 'person' is a hash with 3 keys (kind: `:person`, name: string, salary: integer),
+* 'entity' is a hash with 4 keys (kind: `:entity`, title: string, form: string, revenue: integer).
 
 ```ruby
 person_or_entity =
@@ -317,7 +364,25 @@ person_or_entity =
     # separate entity validator (excluding validation of 'kind' field)
     entity = hash_schema(title: string, form: string, revenue: integer)
 
-    kind_is_valid & hash_schema(kind: compare(:person)).then(person).else(entity)
+
+    # 1. First option, explicit definition
+
+    kind_is_valid &
+      switch(pick(:kind)).
+        on(compare(:person), person).
+        on(compare(:entity), entity)
+
+    # 2. Second option, shortcut definiton
+
+    kind_is_valid &
+      switch(:kind).
+        on(:person, person).
+        on(:entity, entity)
+
+    # 3. Third option, using keywords args and Ruby 3.1 value omission in hash literals
+
+    kind_is_valid &
+      switch(:kind, person:, entity:)
   end
 
 person_or_entity.(
@@ -341,22 +406,27 @@ person_or_entity.(
 # => Datacaster::ErrorResult({:kind=>["is invalid"]})
 ```
 
-See below documentation on 'check' custom type to know how to provide custom error message instead of 'is invalid'.
+In our opinion the above example shows most laconic way to express underlying 'business-logic' (including elaborate error reporting on all kinds of failures) among all available competitor approaches/gems.
 
-Schema, defined above, behaves in all aspects (shown in the example and in other practical applications which might come to your mind) just as you might expect it to, after reading previous examples and the code above.
+Notice that shortcut definitions are available (illustrated in the example above) for the switch caster:
 
-In our opinion the above example shows most laconic way to express underlying 'business-logic' (including elaborate error reporting on all kinds of failures) among all available competitor approaches/gems.
+* `switch(:key)` is exactly the same as `switch(pick(:key))` (works for a string, a symbol, or an array thereof)
+* `on(:key, ...)` is exactly the same as `on(compare(:key), ...)` (works for a string or a symbol)
+* `switch([caster], on_check => on_caster, ...)` is exactly the same as `switch([caster]).on(on_check, on_caster).on(...)`
 
-Formally, with `a.then(b).else(c)`:
+`switch()` without a `base` argument will pass the incoming value to the `.on(...)` casters.
 
-* if `a` returns `ValidResult`, then `b` is called *with the result of `a`* (not the original value) and whatever `b` returns is returned;
-* otherwise, `c` is called with the original value, and whatever `c` returns is returned.
+Formally, with `switch(a).on(on_check, on_caster).else(c)`:
 
-`else`-part is required and could not be omitted.
+* if `a` returns ErrorResult, it is the result of the switch
+* otherwise, all `on_check` casters from the `.on` blocks are called with the result of `a`, until the first one which returns ValidResult is found – corresponding `on_caster` is called with the original value and its result is the result of the switch
+* if all `on_check`-s returned ErrorResult
+  * and there is an `.else` block, `c` is called with the original value and its result is the result of the switch
+  * if there is no `.else` block, `ErrorResult(['is invalid'])` is returned from the switch
 
-Note: this construct is *not* an equivalent of `a & b | c`.
+I18n keys:
 
-With `a.then(b).else(c)` if `a` and `b` fails, then `b`'s error is returned. With `a & b | c`, instead, `c`'s result would be returned.
+* all `.on` checks resulted in an error and there is no `.else`: `'.switch'`, `'datacaster.errors.switch'`
 
 ## Built-in types
 
@@ -450,10 +520,10 @@ Always returns ValidResult.
 
 Returns `default_value` in the following cases:
 
-* if value is `Datacaster.absent` (`on` is disregarded in such case)
-* if `on` is set to method name to which the value responds and yields truthy
+* 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
 
-Returns initial value otherwise.
+Returns the initial value otherwise.
 
 Set `on` to `:nil?`, `:empty?` or similar method names.
 
@@ -594,6 +664,12 @@ Always returns ValidResult. Doesn't transform the value.
 
 Useful to "mark" the value as validated (see section below on hash schemas, where this could be applied).
 
+#### `pass_if(base)`
+
+Returns ValidResult if and only if base returns ValidResult. Returns base's error result otherwise.
+
+Doesn't transform the value: if base succeeds returns the original value (not the one that base returned).
+
 #### `pick(key)`
 
 Returns ValidResult if and only if the value `#is_a?(Enumerable)`.
@@ -642,15 +718,7 @@ I18n keys: `error_key`, `'.responds_to'`, `'datacaster.errors.responds_to'`. Add
 
 #### `transform_to_value(value)`
 
-Always returns ValidResult. The value is transformed to provided argument. Is used to provide default values, e.g.:
-
-```ruby
-max_concurrent_connections = Datacaster.schema { compare(nil).then(transform_to_value(5)).else(integer) }
-
-max_concurrent_connections.(9)   # => Datacaster::ValidResult(9)
-max_concurrent_connections.("9") # => Datacaster::ErrorResult(["is not an integer"])
-max_concurrent_connections.(nil) # => Datacaster::ValidResult(5)
-```
+Always returns ValidResult. The value is transformed to provided argument (disregarding the original value). See also [`default`](#defaultdefault_value-on-nil).
 
 ### "Web-form" types
 
@@ -1375,7 +1443,7 @@ en:
       wrong_format: wrong format
 ```
 
-Let's gradually reduce the boilerplate, starting with the most explicit example. Notice that all relative keys (i.e. keys which will be scoped during the execution) starts with `'.'`:
+Let's gradually reduce the boilerplate, starting with the most explicit example. Notice that all relative keys (i.e. keys which will be scoped during the execution) start with `'.'`:
 
 ```ruby
 schema =
@@ -1436,7 +1504,6 @@ schema =
   Datacaster.schema(i18n_scope: 'user') do
     check { |v| v[:id] == 1 } &
       hash_schema(
-        # '.wrong_format' inferred to be '.name.wrong_format'
         name: check { false }
       )
   end
@@ -1470,9 +1537,9 @@ Every caster will automatically provide `value` variable for i18n interpolation.
 
 All keyword arguments of `#i18n_key`, `#i18n_scope` and designed for that sole purpose `#i18n_vars` are provided as interpolation variables on i18n.
 
-It is possible to add i18n variables at the runtime (e.g. inside `check { ... }` block) by calling `i18n_vars!(variable: 'value')` (or `i18n_var!(:variable, 'value')`.
+It is possible to add i18n variables at the runtime (e.g. inside `check { ... }` block) by calling `i18n_vars!(variable: 'value')` or `i18n_var!(:variable, 'value')`.
 
-Outer calls of `#i18n_key` (`#i18n_scope`, `#i18n_vars`) have presedence before the inner if variable names collide. However, runtime calls of `#i18n_vars!` and `#i18n_var!` overwrites compile-time variables from the next nearest key, scope or vars on collision.
+Outer calls of `#i18n_key` (`#i18n_scope`, `#i18n_vars`) have presedence before the inner if variable names collide. However, runtime calls of `#i18n_vars!` and `#i18n_var!` overwrite compile-time variables from the next nearest key, scope or vars on collision.
 
 ## Registering custom 'predefined' types
 

data/config/locales/en.yml

@@ -21,4 +21,5 @@ en:
       to_float: does not look like a float
       to_integer: does not look like an integer
       non_empty_string: should be non-empty string
+      switch: is invalid
       try: raised an error

data/datacaster.gemspec

@@ -26,7 +26,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'rake', '~> 12.0'
   spec.add_development_dependency 'rspec', '~> 3.0'
   spec.add_development_dependency 'i18n', '~> 1.14'
+  spec.add_development_dependency 'dry-monads', '>= 1.3', '< 1.4'
 
-  spec.add_runtime_dependency 'dry-monads', '>= 1.3', '< 1.4'
   spec.add_runtime_dependency 'zeitwerk', '>= 2', '< 3'
 end

data/lib/datacaster/base.rb

@@ -46,7 +46,7 @@ module Datacaster
     end
 
     def then(other)
-      ThenNode.new(self, other)
+      ThenNode.new(self, DefinitionDSL.expand(other))
     end
 
     def with_context(context)

data/lib/datacaster/comparator.rb

@@ -18,7 +18,7 @@ module Datacaster
     end
 
     def inspect
-      "#<Datacaster::Comparator>"
+      "#<Datacaster::Comparator(#{@value.inspect})>"
     end
   end
 end

data/lib/datacaster/context_nodes/pass_if.rb

@@ -0,0 +1,11 @@
+module Datacaster
+  module ContextNodes
+    class PassIf < Datacaster::ContextNode
+      def cast(object, runtime:)
+        @runtime = create_runtime(runtime)
+        result = @base.with_runtime(@runtime).call(object)
+        result.valid? ? Datacaster::ValidResult(object) : result
+      end
+    end
+  end
+end

data/lib/datacaster/definition_dsl.rb

@@ -4,7 +4,6 @@ require 'date'
 module Datacaster
   class DefinitionDSL
     include Datacaster::Predefined
-    include Dry::Monads[:result]
 
     # Translates hashes like {a: <IntegerChecker>} to <HashSchema {a: <IntegerChecker>}>
     #   and arrays like [<IntegerChecker>] to <ArraySchema <IntegerChecker>>

data/lib/datacaster/predefined.rb

@@ -53,6 +53,18 @@ module Datacaster
       Validator.new(active_model_validations)
     end
 
+    def schema(base)
+      ContextNodes::StructureCleaner.new(base, strategy: :fail)
+    end
+
+    def choosy_schema(base)
+      ContextNodes::StructureCleaner.new(base, strategy: :remove)
+    end
+
+    def partial_schema(base)
+      ContextNodes::StructureCleaner.new(base, strategy: :pass)
+    end
+
     # 'Meta' types
 
     def absent(error_key = nil)
@@ -90,7 +102,25 @@ module Datacaster
       transform(&:itself)
     end
 
-    def pick(*keys)
+    def switch(*base, **on_clauses)
+      switch =
+        if base.length == 0
+          SwitchNode.new
+        else
+          SwitchNode.new(base)
+        end
+      on_clauses.reduce(switch) do |result, (k, v)|
+        result.on(k, v)
+      end
+    end
+
+    def pass_if(base)
+      ContextNodes::PassIf.new(base)
+    end
+
+    def pick(*keys, strict: false)
+      raise RuntimeError.new("provide keys to pick, e.g. pick(:key)") if keys.empty?
+
       must_be(Enumerable) & transform { |value|
         result =
           keys.map do |key|
@@ -209,7 +239,7 @@ module Datacaster
         elsif ['false', '0', false].include?(x)
           Datacaster.ValidResult(false)
         else
-          Datacaster.ErrorResult(Datacaster::I18nValues::Key.new(error_keys, value: x))
+          Datacaster.ErrorResult(I18nValues::Key.new(error_keys, value: x))
         end
       end
     end

data/lib/datacaster/result.rb

@@ -1,9 +1,5 @@
-require 'dry/monads'
-
 module Datacaster
   class Result
-    include Dry::Monads[:result]
-
     def initialize(valid, value_or_errors)
       @value_or_errors = value_or_errors
       if !valid && !@value_or_errors.is_a?(Hash) && !@value_or_errors.is_a?(Array)
@@ -43,7 +39,11 @@ module Datacaster
     end
 
     def to_dry_result
-      @valid ? Success(@value_or_errors) : Failure(errors)
+      if @valid
+        Dry::Monads::Result::Success.new(@value_or_errors)
+      else
+        Dry::Monads::Result::Failure.new(errors)
+      end
     end
 
     private

data/lib/datacaster/switch_node.rb

@@ -0,0 +1,72 @@
+module Datacaster
+  class SwitchNode < Base
+    def initialize(base = nil, on_casters = [], else_caster = nil)
+      base = base[0] if base.is_a?(Array) && base.length == 1
+
+      case base
+      when nil
+        @base = nil
+      when Datacaster::Base
+        @base = base
+      when String, Symbol, Array
+        @base = Datacaster::Predefined.pick(base)
+      else
+        raise RuntimeError, "provide a Datacaster::Base instance, a hash key, or an array of keys to switch(...) caster", caller
+      end
+
+      @ons = on_casters
+      @else = else_caster
+    end
+
+    def on(caster_or_value, clause)
+      caster =
+        case caster_or_value
+        when Datacaster::Base
+          caster_or_value
+        else
+          Datacaster::Predefined.compare(caster_or_value)
+        end
+
+      clause = DefinitionDSL.expand(clause)
+
+      self.class.new(@base, @ons + [[caster, clause]], @else)
+    end
+
+    def else(else_caster)
+      raise ArgumentError, "Datacaster: double else clause is not permitted", caller if @else
+      self.class.new(@base, @ons, else_caster)
+    end
+
+    def cast(object, runtime:)
+      if @ons.empty?
+        raise RuntimeError, "switch caster requires at least one 'on' statement: switch(...).on(condition, cast)", caller
+      end
+
+      if @base.nil?
+        switch_result = object
+      else
+        switch_result = @base.with_runtime(runtime).(object)
+        return switch_result unless switch_result.valid?
+        switch_result = switch_result.value
+      end
+
+      @ons.each do |check, clause|
+        result = check.with_runtime(runtime).(switch_result)
+        next unless result.valid?
+
+        return clause.with_runtime(runtime).(object)
+      end
+
+      # all 'on'-s have failed
+      return @else.with_runtime(runtime).(object) if @else
+
+      Datacaster.ErrorResult(
+        I18nValues::Key.new(['.switch', 'datacaster.errors.switch'], value: object)
+      )
+    end
+
+    def inspect
+      "#<Datacaster::SwitchNode base: #{@base.inspect} on: #{@ons.inspect} else: #{@else.inspect}>"
+    end
+  end
+end

data/lib/datacaster/then_node.rb

@@ -9,7 +9,7 @@ module Datacaster
     def else(else_caster)
       raise ArgumentError.new("Datacaster: double else clause is not permitted") if @else
 
-      self.class.new(@left, @then, else_caster)
+      self.class.new(@left, @then, DefinitionDSL.expand(else_caster))
     end
 
     def cast(object, runtime:)

data/lib/datacaster/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: datacaster
 version: !ruby/object:Gem::Version
-  version: 3.0.0
+  version: 3.1.0
 platform: ruby
 authors:
 - Eugene Zolotarev
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-09-29 00:00:00.000000000 Z
+date: 2023-10-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -76,7 +76,7 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '1.4'
-  type: :runtime
+  type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
@@ -140,6 +140,7 @@ files:
 - lib/datacaster/context_nodes/errors_caster.rb
 - lib/datacaster/context_nodes/i18n.rb
 - lib/datacaster/context_nodes/i18n_keys_mapper.rb
+- lib/datacaster/context_nodes/pass_if.rb
 - lib/datacaster/context_nodes/structure_cleaner.rb
 - lib/datacaster/context_nodes/user_context.rb
 - lib/datacaster/definition_dsl.rb
@@ -157,6 +158,7 @@ files:
 - lib/datacaster/runtimes/structure_cleaner.rb
 - lib/datacaster/runtimes/user_context.rb
 - lib/datacaster/substitute_i18n.rb
+- lib/datacaster/switch_node.rb
 - lib/datacaster/then_node.rb
 - lib/datacaster/transformer.rb
 - lib/datacaster/trier.rb