datacaster 3.1.5 → 3.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 29c3f6c825f2c2d9a664e370079cde58df4ce9685d34d8428fb29aa7b98c52f3
-  data.tar.gz: 7d90ad442a4bd32ae4526d403629676c3aec9566973486bacd6565e8cb3d7bbd
+  metadata.gz: ed24c848eb7b909ee24655728013ccddad59fa7ad0c497326d767fcbe0ea369b
+  data.tar.gz: 6bc155f410e73bcd09a9941055e23c63aefc79caff1fcff47110d7d03b02b145
 SHA512:
-  metadata.gz: acc11fefd17414ba1400bd98d2105b194301ac63f4d6b4204f001f918984326ab711c92d89133b475fd09d51b10c5d6427f6d6f516742a4ceb0a3eb2cf07f983
-  data.tar.gz: 07f288ab4e44e0b7a931aa43b34bac1a98d34d68f9d72241fc34f1648aeedc0412b51bdbe1113d9c34674a283e5fc6c559d4d2c5c385f5ec55c65d3b8345fb73
+  metadata.gz: e59a0fc79dc9fbc350ec581d7741bc61d064439aea06f66cc814fba82e9678423f140ce0a5eeef17aa51a39c3f2457c5bc1b1909ab10db2b7e44ba1d214d2ac6
+  data.tar.gz: e53f422a189dcaee5f898f8f2b59fb9538fe26e9551b66f0bb3da467f4f1f91aad7480b2237df90b05892a4f72a2bdd56b446ad5691adca5f1d38b39ccfdb27a

data/README.md

@@ -44,6 +44,7 @@ It is currently used in production in several projects (mainly as request parame
     - [`pick(*keys)`](#pickkeys)
     - [`remove`](#remove)
     - [`responds_to(method, error_key = nil)`](#responds_tomethod-error_key--nil)
+    - [`with(key, caster)`](#withkey-caster)
     - [`transform_to_value(value)`](#transform_to_valuevalue)
   - ["Web-form" types](#web-form-types)
     - [`iso8601(error_key = nil)`](#iso8601error_key--nil)
@@ -57,8 +58,9 @@ 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)
+    - [`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)
+    - [`run { |value| ... }`](#run--value--)
     - [`transform { |value| ... }`](#transform--value--)
     - [`transform_if_present { |value| ... }`](#transform_if_present--value--)
   - [Array schemas](#array-schemas)
@@ -165,11 +167,15 @@ It is worth noting that in `a & b` validation composition as above, if `a` in so
 
 All datacaster validations, when called, return an instance of `Datacaster::Result` value, i.e. `Datacaster::ValidResult` or `Datacaster::ErrorResult`.
 
-You can call `#valid?`, `#value`, `#errors` methods directly, or, if preferred, call `#to_dry_result` method to convert `Datacaster::Result` to the corresponding `Dry::Monads::Result` (with all the included "batteries" of the latter, e.g. pattern matching, 'binding', etc.).
+You can call `#valid?`, `#value`, `#errors` methods directly, or, if preferred, call `#to_dry_result` method to convert `Datacaster::Result` to the corresponding `Dry::Monads::Result`.
 
-`#value` and `#errors` would return `#nil` if the result is, correspondingly, `ErrorResult` and `ValidResult`. No methods would raise an error.
+`#value` and `#errors` would return `#nil` if the result is, correspondingly, `ErrorResult` and `ValidResult`.
 
-Errors are returned as array or hash (or hash of arrays, or array of hashes, etc., for complex data structures). Errors support internationalization (i18n) natively. Each element of the returned array shows a separate error as a special i18n value object, and each key of the returned hash corresponds to the key of the validated hash.
+`#value!` would return value for `ValidResult` and raise an error for `ErrorResult`.
+
+`#value_or(another_value)` and `#value_or { |errors| another_value }` would return value for `ValidResult` and `another_value` for `ErrorResult`.
+
+Errors are returned as array or hash (or hash of arrays, or array of hashes, etc., for complex data structures). Errors support internationalization (i18n) natively. Each element of the returned array shows a separate error as a special i18n value object, and each key of the returned hash corresponds to the key of the validated hash. When calling `#errors` those i18n value objects are converted to strings using the configured/detected I18n backend (Rails or `ruby-i18n`).
 
 In this README, instead of i18n values English strings are provided for brevity:
 
@@ -285,7 +291,25 @@ even_number.("test")
 # => Datacaster::ErrorResult(["is not an integer"])
 ```
 
-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.
+If left-hand validation of AND operator passes, *its result* (not the original value) is passed to the right-hand validation.
+
+Alternatively, `steps` caster could be used, which accepts any number of "steps" as arguments and joins them with `&` logic:
+
+```ruby
+even_number =
+  Datacaster.schema do
+    steps(
+      integer,
+      check { |x| x.even? },
+      transform { |x| x * 2 }
+    )
+  end
+
+even_number.(6)
+# => Datacaster::ValidResult(12)
+```
+
+Naturally, if one of the "steps" returns an error, process short-circuits and this error is returned as a result.
 
 #### *OR operator*
 
@@ -764,6 +788,41 @@ Returns ValidResult if and only if the value `#responds_to?(method)`. Doesn't tr
 
 I18n keys: `error_key`, `'.responds_to'`, `'datacaster.errors.responds_to'`. Adds `reference` i18n variable, setting it to `method.to_s`.
 
+#### `with(key, caster)`
+
+Returns ValidResult if and only if value is enumerable and `caster` returns ValidResult. Transforms incoming hash, providing value described by `key` to `caster`, and putting its result back into the original hash.
+
+```ruby
+upcase_name =
+  Datacaster.schema do
+    with(:name, transform(&:upcase))
+  end
+
+upcase_name.(name: 'Josh')
+# => Datacaster::ValidResult({:name=>"JOSH"})
+```
+
+If an array is provided instead of string or Symbol for `key` argument, it is treated as array of key names for a deeply nested value:
+
+```ruby
+upcase_person_name =
+  Datacaster.schema do
+    with([:person, :name], transform(&:upcase))
+  end
+
+upcase_person_name.(person: {name: 'Josh'})
+# => Datacaster::ValidResult({:person=>{:name=>"JOSH"}})
+
+upcase_person_name.({})
+# => Datacaster::ErrorResult({:person=>["is not Enumerable"]})
+```
+
+Note that `Datacaster.absent` will be provided to `caster` if corresponding key is absent from the value.
+
+I18n keys:
+
+* is not enumerable – `'.must_be'`, `'datacaster.errors.must_be'`. Adds `reference` i18n variable, setting it to `"Enumerable"`.
+
 #### `transform_to_value(value)`
 
 Always returns ValidResult. The value is transformed to provided argument (disregarding the original value). See also [`default`](#defaultdefault_value-on-nil).
@@ -929,7 +988,7 @@ 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)`
+#### `included_in(reference_values, error_key: nil)`
 
 Returns ValidResult if and only if `reference_values.include?` the value.
 
@@ -973,6 +1032,12 @@ Formally, `relate(left, op, right, error_key: error_key)` will:
 * call the `op` caster with the `[left_result, right_result]`, return the result unless it's valid
 * return the original value as valid result
 
+#### `run { |value| ... }`
+
+Always returns ValidResult. Doesn't transform the value.
+
+Useful to perform some side-effect such as raising an exception, making a log entry, etc.
+
 #### `transform { |value| ... }`
 
 Always returns ValidResult. Transforms the value: returns whatever the block has returned.

data/lib/datacaster/and_node.rb

@@ -1,19 +1,21 @@
 module Datacaster
   class AndNode < Base
-    def initialize(left, right)
-      @left = left
-      @right = right
+    def initialize(*casters)
+      @casters = casters
     end
 
     def cast(object, runtime:)
-      left_result = @left.with_runtime(runtime).(object)
-      return left_result unless left_result.valid?
-
-      @right.with_runtime(runtime).(left_result.value)
+      Datacaster.ValidResult(
+        @casters.reduce(object) do |result, caster|
+          caster_result = caster.with_runtime(runtime).(result)
+          return caster_result unless caster_result.valid?
+          caster_result.value
+        end
+      )
     end
 
     def inspect
-      "#<Datacaster::AndNode L: #{@left.inspect} R: #{@right.inspect}>"
+      "#<Datacaster::AndNode casters: #{@casters.inspect}>"
     end
   end
 end

data/lib/datacaster/around_node.rb

@@ -0,0 +1,34 @@
+module Datacaster
+  class AroundNode < Base
+    def initialize(around = nil, &block)
+      raise "Expected block" unless block_given?
+
+      @around = around
+      @run = block
+    end
+
+    def around(*casters)
+      if @around
+        raise ArgumentError, "only one call to .around(...) is expect, tried to call second time", caller
+      end
+
+      unless casters.all? { |x| Datacaster.instance?(x) }
+        raise ArgumentError, "provide datacaster instance to .around(...)", caller
+      end
+
+      caster = casters.length == 1 ? casters[0] : Datacaster::Predefined.steps(*casters)
+
+      self.class.new(caster, &@run)
+    end
+
+    def cast(object, runtime:)
+      unless @around
+        raise ArgumentError, "call .around(caster) beforehand", caller
+      end
+    end
+
+    def inspect
+      "#<#{self.class.name}>"
+    end
+  end
+end

data/lib/datacaster/around_nodes/caster.rb

@@ -0,0 +1,11 @@
+module Datacaster
+  module AroundNodes
+    class Caster < Datacaster::AroundNode
+      def cast(object, runtime:)
+        super
+
+        Runtimes::Base.(runtime, @run, object, @around.with_runtime(runtime))
+      end
+    end
+  end
+end

data/lib/datacaster/caster.rb

@@ -14,7 +14,7 @@ module Datacaster
       end
 
       raise TypeError.new("Either Datacaster::Result or Dry::Monads::Result " \
-        "should be returned from cast block") unless result.is_a?(Datacaster::Result)
+        "should be returned from cast block, instead got #{result.inspect}") unless result.is_a?(Datacaster::Result)
 
       result
     end

data/lib/datacaster/context_nodes/object_context.rb

@@ -0,0 +1,20 @@
+module Datacaster
+  module ContextNodes
+    class ObjectContext < Datacaster::ContextNode
+      def initialize(base, object)
+        super(base)
+        @object = object
+      end
+
+      def inspect
+        "#<#{self.class.name}(#{@object.inspect}) base: #{@base.inspect}>"
+      end
+
+      private
+
+      def create_runtime(parent)
+        Runtimes::ObjectContext.new(parent, @object)
+      end
+    end
+  end
+end

data/lib/datacaster/context_nodes/structure_cleaner.rb

@@ -5,7 +5,7 @@ module Datacaster
         super(base)
 
         unless %i[fail remove pass].include?(strategy)
-          raise ArgumentError.new("Strategy should be :fail (return error on extra keys), :remove (remove extra keys) or :pass (ignore presence of extra keys)")
+          raise ArgumentError.new("Strategy should be :fail (return error on extra keys), :remove (remove extra keys) or :pass (ignore presence of extra keys), instead got #{strategy.inspect}")
         end
 
         @strategy = strategy
@@ -23,7 +23,11 @@ module Datacaster
 
       def transform_result(result)
         return result unless result.valid?
-        cast_success(result)
+        result = cast_success(result)
+        if @runtime.instance_variable_get(:@parent).respond_to?(:checked_schema=)
+          @runtime.instance_variable_get(:@parent).checked_schema = @runtime.checked_schema
+        end
+        result
       end
 
       def cast_success(result)

data/lib/datacaster/definition_dsl.rb

@@ -25,7 +25,7 @@ module Datacaster
     end
 
     def self.eval(&block)
-      new.instance_exec(&block)
+      new.instance_eval(&block)
     end
 
     def method_missing(m, *args)

data/lib/datacaster/hash_mapper.rb

@@ -27,9 +27,9 @@ module Datacaster
           unwrapped = new_value.valid? ? new_value.value : new_value.raw_errors
 
           if key.length != unwrapped.length
-            raise TypeError.new("When using transform_to_hash([:a, :b, :c] => validator), validator should return Array "\
+            raise TypeError, "When using transform_to_hash([:a, :b, :c] => validator), validator should return Array "\
               "with number of elements equal to the number of elements in left-hand-side array.\n" \
-              "Got the following (values or errors) instead: #{keys.inspect} => #{values_or_errors.inspect}.")
+              "Got the following (values or errors) instead: #{key.inspect} => #{unwrapped.inspect}."
           end
         end
 

data/lib/datacaster/mixin.rb

@@ -27,6 +27,10 @@ module Datacaster
       ContextNodes::UserContext.new(self, context)
     end
 
+    def with_object_context(object)
+      ContextNodes::ObjectContext.new(self, object)
+    end
+
     def call(object)
       call_with_runtime(object, Runtimes::Base.new)
     end
@@ -40,9 +44,22 @@ module Datacaster
     end
 
     def with_runtime(runtime)
-      ->(object) do
-        call_with_runtime(object, runtime)
+      result =
+        ->(object) do
+          call_with_runtime(object, runtime)
+        end
+
+      this = self
+
+      result.singleton_class.define_method(:with_runtime) do |new_runtime|
+        this.with_runtime(new_runtime)
       end
+
+      result.singleton_class.define_method(:without_runtime) do |new_runtime|
+        this
+      end
+
+      result
     end
 
     def i18n_key(*keys, **args)

data/lib/datacaster/predefined.rb

@@ -16,6 +16,10 @@ module Datacaster
       Comparator.new(value, error_key)
     end
 
+    def run(&block)
+      Runner.new(&block)
+    end
+
     def transform(&block)
       Transformer.new(&block)
     end
@@ -45,6 +49,14 @@ module Datacaster
       )
     end
 
+    def strict_hash_schema(fields, error_key = nil)
+      schema(hash_schema(fields, error_key))
+    end
+
+    def choosy_hash_schema(fields, error_key = nil)
+      choosy_schema(hash_schema(fields, error_key))
+    end
+
     def transform_to_hash(fields)
       HashMapper.new(fields.transform_values { |x| DefinitionDSL.expand(x) })
     end
@@ -65,6 +77,12 @@ module Datacaster
       ContextNodes::StructureCleaner.new(base, :pass)
     end
 
+    # 'Around' types
+
+    def cast_around(&block)
+      AroundNodes::Caster.new(&block)
+    end
+
     # 'Meta' types
 
     def absent(error_key = nil, on: nil)
@@ -151,8 +169,12 @@ module Datacaster
     end
 
     def pick(*keys)
-      if keys.empty? || keys.any? { |k| !Datacaster::Utils.pickable?(k) }
-        raise RuntimeError, "each argument should be String, Symbol, Integer or an array thereof", caller
+      if keys.empty?
+        raise RuntimeError, "pick(key, ...) accepts at least one argument", caller
+      end
+
+      if wrong = keys.find { |k| !Datacaster::Utils.pickable?(k) }
+        raise RuntimeError, "each argument should be String, Symbol, Integer or an array thereof, instead got #{wrong.inspect}", caller
       end
 
       retrieve_key = -> (from, key) do
@@ -242,6 +264,10 @@ module Datacaster
       check { |x| x.respond_to?(method) }.i18n_key(*error_keys, reference: method.to_s)
     end
 
+    def steps(*casters)
+      AndNode.new(*casters)
+    end
+
     def switch(base = nil, **on_clauses)
       switch = SwitchNode.new(base)
       on_clauses.reduce(switch) do |result, (k, v)|
@@ -253,6 +279,20 @@ module Datacaster
       transform { value }
     end
 
+    def with(keys, caster)
+      keys = Array(keys)
+
+      unless Datacaster::Utils.pickable?(keys)
+        raise RuntimeError, "provide String, Symbol, Integer or an array thereof instead of #{keys.inspect}", caller
+      end
+
+      if keys.length == 1
+        return transform_to_hash(keys[0] => pick(keys[0]) & caster)
+      end
+
+      with(keys[0], must_be(Enumerable) & with(keys[1..-1], caster))
+    end
+
     # Strict types
 
     def decimal(digits = 8, error_key = nil)
@@ -290,7 +330,7 @@ module Datacaster
       hash_value(error_key) & transform { |x| x.symbolize_keys }
     end
 
-    def included_in(*values, error_key: nil)
+    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(', '))

data/lib/datacaster/result.rb

@@ -9,6 +9,22 @@ module Datacaster
       @valid = !!valid
     end
 
+    def value_or(*values, &block)
+      if values.length > 1 || (values.length == 1 && block_given?)
+        raise RuntimeError, "provide either value or block: #or(value), #or { block }", caller
+      end
+
+      if valid?
+        value
+      else
+        if values.length == 1
+          values[0]
+        else
+          block.(errors)
+        end
+      end
+    end
+
     def valid?
       @valid
     end

data/lib/datacaster/runner.rb

@@ -0,0 +1,18 @@
+module Datacaster
+  class Runner < Base
+    def initialize(&block)
+      raise "Expected block" unless block_given?
+
+      @run = block
+    end
+
+    def cast(object, runtime:)
+      Runtimes::Base.(runtime, @run, object)
+      Datacaster.ValidResult(object)
+    end
+
+    def inspect
+      "#<Datacaster::Runner>"
+    end
+  end
+end

data/lib/datacaster/runtimes/base.rb

@@ -1,8 +1,15 @@
+require 'set'
+
 module Datacaster
   module Runtimes
     class Base
+      attr_reader :reserved_instance_variables
+
       def self.call(r, proc, *args)
-        r.instance_exec(*args, &proc)
+        r.before_call!(r)
+        result = r.instance_exec(*args, &proc)
+        r.after_call!(r)
+        result
       end
 
       def self.send_to_parent(r, m, *args, &block)
@@ -17,6 +24,10 @@ module Datacaster
 
       def initialize(parent = nil)
         @parent = parent
+
+        # We won't be setting any instance variables outside this
+        # constructor, so we can proxy all the rest to the @object
+        @reserved_instance_variables = Set.new(instance_variables + [:@reserved_instance_variables])
       end
 
       def method_missing(m, *args, &block)
@@ -27,6 +38,14 @@ module Datacaster
         !@parent.nil? && @parent.respond_to?(m, include_private)
       end
 
+      def after_call!(sender)
+        @parent.after_call!(sender) if @parent
+      end
+
+      def before_call!(sender)
+        @parent.before_call!(sender) if @parent
+      end
+
       def inspect
         "#<#{self.class.name} parent: #{@parent.inspect}>"
       end

data/lib/datacaster/runtimes/i18n.rb

@@ -6,6 +6,8 @@ module Datacaster
       def initialize(*)
         super
         @args = {}
+
+        @reserved_instance_variables += instance_variables
       end
 
       def i18n_var!(name, value)

data/lib/datacaster/runtimes/object_context.rb

@@ -0,0 +1,41 @@
+require 'set'
+
+module Datacaster
+  module Runtimes
+    class ObjectContext < Base
+      def initialize(parent, object)
+        super(parent)
+        @object = object
+
+        @reserved_instance_variables += instance_variables
+      end
+
+      def method_missing(m, *args, &block)
+        if @object.respond_to?(m)
+          @object.public_send(m, *args, &block)
+        else
+          super
+        end
+      end
+
+      def respond_to_missing?(m, include_private = false)
+        @object.respond_to?(m, include_private) || super
+      end
+
+      def after_call!(sender)
+        (sender.instance_variables.to_set - sender.reserved_instance_variables).each do |k|
+          @object.instance_variable_set(k, sender.instance_variable_get(k))
+          sender.remove_instance_variable(k)
+        end
+        super
+      end
+
+      def before_call!(sender)
+        super
+        (@object.instance_variables.to_set - sender.reserved_instance_variables).each do |k|
+          sender.instance_variable_set(k, @object.instance_variable_get(k))
+        end
+      end
+    end
+  end
+end

data/lib/datacaster/runtimes/structure_cleaner.rb

@@ -1,13 +1,16 @@
 module Datacaster
   module Runtimes
     class StructureCleaner < Base
-      attr_reader :checked_schema
+      attr_accessor :checked_schema
 
       def initialize(*)
         super
+        @ignore = false
         @checked_schema = {}
         @should_check_stack = [false]
         @pointer_stack = [@checked_schema]
+
+        @reserved_instance_variables += instance_variables
       end
 
       # Array checked schema are the same as hash one, where

data/lib/datacaster/runtimes/user_context.rb

@@ -29,6 +29,8 @@ module Datacaster
       def initialize(parent, user_context)
         super(parent)
         @context_struct = ContextStruct.new(user_context, self)
+
+        @reserved_instance_variables += instance_variables
       end
 
       def context

data/lib/datacaster/switch_node.rb

@@ -4,11 +4,11 @@ module Datacaster
       @base = base
 
       if Datacaster::Utils.pickable?(@base)
-        @base = Datacaster::Predefined.pick(@base)
+        @base = Datacaster::Predefined.run { checked_key!(base) } &
+          Datacaster::Predefined.pick(base)
       end
 
       if !@base.nil? && !Datacaster.instance?(@base)
-        puts @base.inspect
         raise RuntimeError, "provide a Datacaster::Base instance, a hash key, or an array of keys to switch(...) caster", caller
       end
 

data/lib/datacaster/transaction.rb

@@ -0,0 +1,115 @@
+module Datacaster
+  module Transaction
+    class StepErrorResult < RuntimeError
+      attr_accessor :result
+
+      def initialize(result)
+        super(result.inspect)
+        @result = result
+      end
+    end
+
+    module ClassMethods
+      def _caster
+        if @_block
+          @_caster = ContextNodes::StructureCleaner.new(@_block.(), @_strategy)
+          @_block = nil
+          @_strategy = nil
+        end
+        @_caster
+      end
+
+      def _perform(caster, strategy, &block)
+        if [caster, block].count(nil) != 1
+          raise RuntimeError, "provide either a caster as single argument, or just a block to `perform(...)` or `perform_*(...)` call", caller
+        end
+
+        if block
+          @_block = block
+          @_strategy = strategy
+          @_caster = nil
+        else
+          @_block = nil
+          @_strategy = nil
+          @_caster = ContextNodes::StructureCleaner.new(caster, strategy)
+        end
+      end
+
+      def perform(caster = nil, &block)
+        _perform(caster, :fail, &block)
+      end
+
+      def perform_partial(caster = nil, &block)
+        _perform(caster, :pass, &block)
+      end
+
+      def perform_choosy(caster = nil, &block)
+        _perform(caster, :remove, &block)
+      end
+
+      def define_steps(&block)
+        instance_eval(&block)
+      end
+
+      def method_missing(m, *args, **kwargs)
+        return super unless args.empty? && kwargs.empty?
+        return super unless method_defined?(m)
+        method = instance_method(m)
+        return super unless method.arity == 1
+
+        # convert immediate class method call to lazy instance method call
+        ->(*args, **kwargs) { send(m, *args, **kwargs) }
+      end
+
+      def call(*args, **kwargs)
+        new.call(*args, **kwargs)
+      end
+    end
+
+    def self.included(base)
+      base.extend Datacaster::Predefined
+      base.extend ClassMethods
+      base.include Datacaster::Mixin
+    end
+
+    def cast(object, runtime:)
+      if respond_to?(:perform)
+        @runtime = runtime
+        begin
+          result = perform(object)
+        rescue StepErrorResult => e
+          return e.result
+        end
+        @runtime = nil
+        return result
+      end
+
+      caster = self.class._caster
+      unless caster
+        raise RuntimeError, "define #perform (#perform_partial, #perform_choosy) method " \
+          "or call .perform(caster) or .perform { caster } beforehand", caller
+      end
+      caster.
+        with_object_context(self).
+        with_runtime(runtime).
+        (object)
+    end
+
+    def step(arg = nil, &block)
+      result = Datacaster::Predefined.cast(&block).
+        with_object_context(self).
+        with_runtime(@runtime).
+        (arg)
+    end
+
+    def step!(arg = nil, &block)
+      result = step(arg, &block)
+
+      if result.valid?
+        result.value
+      else
+        raise StepErrorResult.new(result)
+      end
+    end
+  end
+end

data/lib/datacaster/version.rb

@@ -1,3 +1,3 @@
 module Datacaster
-  VERSION = "3.1.5"
+  VERSION = "3.2.1"
 end

data/transaction.md

@@ -0,0 +1,123 @@
+# Datacaster transaction
+
+As an experimental feature a "transaction" is available: datacaster defined as a class.
+
+## Example
+
+```ruby
+require 'datacaster'
+
+class UserRegistration
+  include Datacaster::Transaction
+
+  perform do
+    steps(
+      transform(&prepare),
+      typecast,
+      with(:email, transform(&send_email))
+    )
+  end
+
+  define_steps do
+    def typecast = hash_schema(name: string, email: string)
+  end
+
+  def initialize(user_id = 123)
+    @user_id = user_id
+  end
+
+  def prepare(x)
+    @user_id ||= 123
+    x.to_h
+  end
+
+  def send_email(email)
+    {address: email, sent: true, id: @user_id}
+  end
+end
+
+UserRegistration.(name: 'John', email: 'john@example.org')
+# => Datacaster::ValidResult({:name=>"John", :email=>{:address=>"john@example.org", :result=>true, :id=>123}})
+```
+
+## Structure
+
+Transaction is just a class which includes `Datacaster::Transaction`. Upon inclusion, all datacaster predefined methods are added as class methods.
+
+Call `.perform(a_caster)` or `.perform { a_caster }` (where `caster` is a Datacaster instance) to define transaction steps.
+
+Block form `perform { a_caster }` is used to defer definition of class methods (otherwise, they should've been written above `perform` in the code file). Block is eventually executed in a context of the class.
+
+Transaction instance will behave as a normal datacaster (i.e. `a_caster` itself) with the following enhancements:
+
+1\. Transaction class has `.call` method which will initialize instance (available only if `#initialize` doesn't have required arguments) and pass arguments to the instance's `#call`.
+
+2\. Runtime-context for casters used in a transaction is the transaction instance itself. You can call transaction instance methods and get/set transaction instance variables inside blocks of `check { ... }`, `cast { ... }` and all the other predefined datacaster methods. That's why `@user_id` works in the example above.
+
+3\. Convenience method `define_steps` is added, which is just a better looking `class << self`.
+
+4\. If class method is not found, it is automatically converted (with class `method_missing`) to deferred instance method call. In the example above, `.prepare` class method is not defined. However, `perform` block executes in a class context and tries to look that method up. Instead, proc `->(value) { self.perfrom(value) }` is returned – a deferred instance method call (which is passed as block to standard `transform` datacaster).
+
+Note that `steps` is a predefined Datacaster method (which works as `&`), and so is `transform` and `with`. They are not Transaction-specific enhancements.
+
+## Around steps with `cast_around`
+
+An experimental addition to Datacaster convenient for the use in Transaction is `cast_around` – a way to wrap a number of steps inside some kind of setup/rollback block, e.g. a database transaction.
+
+```ruby
+class UserRegistration
+  include Datacaster::Transaction
+
+  perform do
+    steps(
+      run { prepare },
+      inside_transaction.around(
+        run { register },
+        run { create_account }
+      ),
+      run { log }
+    )
+  end
+
+  define_steps do
+    def inside_transaction = cast_around do |value, inner|
+      puts "DB transaction started"
+      result = inner.(value)
+      puts "DB transaction ended"
+
+      result
+    end
+  end
+
+  def prepare
+    puts "Preparing"
+  end
+
+  def register
+    puts "User is registered"
+  end
+
+  def create_account
+    puts "Account has been created"
+  end
+
+  def log
+    puts "Creating log entry"
+  end
+end
+
+UserRegistration.('a user object')
+# Preparing
+# DB transaction started
+# User is registered
+# Account has been created
+# DB transaction ended
+# Creating log entry
+# => #<Datacaster::ValidResult("a user object")>
+```
+
+As shown in the example, `cast_around { |value, inner| ...}.around(*casters)` works in the following manner: it yields incoming value as the first argument (`value`) and casters specified in `.around(...)` part as the second argument (`inner`) to the block given. Casters are automatically joined with `steps` if there are more than one.
+
+Block may call `steps.(value)` to execute casters in a regular manner. Block must return a kind of `Datacaster::Result`. `steps.(...)` will always return `Datacaster::Result`, so that result could be passed as a `cast_around` result, as shown in the example.
+
+Note that `run` is a predefined Datacaster method, not specific to Transaction.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: datacaster
 version: !ruby/object:Gem::Version
-  version: 3.1.5
+  version: 3.2.1
 platform: ruby
 authors:
 - Eugene Zolotarev
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-10-07 00:00:00.000000000 Z
+date: 2023-10-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -130,6 +130,8 @@ files:
 - lib/datacaster/absent.rb
 - lib/datacaster/and_node.rb
 - lib/datacaster/and_with_error_aggregation_node.rb
+- lib/datacaster/around_node.rb
+- lib/datacaster/around_nodes/caster.rb
 - lib/datacaster/array_schema.rb
 - lib/datacaster/base.rb
 - lib/datacaster/caster.rb
@@ -140,6 +142,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/object_context.rb
 - lib/datacaster/context_nodes/pass_if.rb
 - lib/datacaster/context_nodes/structure_cleaner.rb
 - lib/datacaster/context_nodes/user_context.rb
@@ -154,18 +157,22 @@ files:
 - lib/datacaster/or_node.rb
 - lib/datacaster/predefined.rb
 - lib/datacaster/result.rb
+- lib/datacaster/runner.rb
 - lib/datacaster/runtimes/base.rb
 - lib/datacaster/runtimes/i18n.rb
+- lib/datacaster/runtimes/object_context.rb
 - 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/transaction.rb
 - lib/datacaster/transformer.rb
 - lib/datacaster/trier.rb
 - lib/datacaster/utils.rb
 - lib/datacaster/validator.rb
 - lib/datacaster/version.rb
+- transaction.md
 homepage: https://github.com/EugZol/datacaster
 licenses:
 - MIT