bcdd-result 0.11.0 → 0.12.0

data/lib/bcdd/result/context.rb

@@ -6,6 +6,9 @@ class BCDD::Result
     require_relative 'context/success'
     require_relative 'context/mixin'
     require_relative 'context/expectations'
+    require_relative 'context/callable_and_then'
+
+    EXPECTED_OUTCOME = 'BCDD::Result::Context::Success or BCDD::Result::Context::Failure'
 
     def self.Success(type, **value)
       Success.new(type: type, value: value)
@@ -15,7 +18,7 @@ class BCDD::Result
       Failure.new(type: type, value: value)
     end
 
-    def initialize(type:, value:, subject: nil, expectations: nil, terminal: nil)
+    def initialize(type:, value:, source: nil, expectations: nil, terminal: nil)
       value.is_a?(::Hash) or raise ::ArgumentError, 'value must be a Hash'
 
       @acc = {}
@@ -23,8 +26,16 @@ class BCDD::Result
       super
     end
 
-    def and_then(method_name = nil, **context_data, &block)
-      super(method_name, context_data, &block)
+    def and_then(method_name = nil, **injected_value, &block)
+      super(method_name, injected_value, &block)
+    end
+
+    def and_then!(source, **injected_value)
+      _call = injected_value.delete(:_call)
+
+      acc.merge!(injected_value)
+
+      super(source, injected_value, _call: _call)
     end
 
     protected
@@ -33,20 +44,23 @@ class BCDD::Result
 
     private
 
-    SubjectMethodArity = ->(method) do
+    SourceMethodArity = ->(method) do
       return 0 if method.arity.zero?
-      return 1 if method.parameters.map(&:first).all?(/\Akey/)
+
+      parameters = method.parameters.map(&:first)
+
+      return 1 if !parameters.empty? && parameters.all?(/\Akey/)
 
       -1
     end
 
-    def call_and_then_subject_method!(method, context_data)
-      acc.merge!(value.merge(context_data))
+    def call_and_then_source_method!(method, injected_value)
+      acc.merge!(value.merge(injected_value))
 
-      case SubjectMethodArity[method]
-      when 0 then subject.send(method.name)
-      when 1 then subject.send(method.name, **acc)
-      else raise Error::InvalidSubjectMethodArity.build(subject: subject, method: method, max_arity: 1)
+      case SourceMethodArity[method]
+      when 0 then source.send(method.name)
+      when 1 then source.send(method.name, **acc)
+      else raise Error::InvalidSourceMethodArity.build(source: source, method: method, max_arity: 1)
       end
     end
 
@@ -56,20 +70,24 @@ class BCDD::Result
       block.call(acc)
     end
 
+    def call_and_then_callable!(source, value:, injected_value:, method_name:)
+      acc.merge!(value.merge(injected_value))
+
+      CallableAndThen::Caller.call(source, value: acc, injected_value: injected_value, method_name: method_name)
+    end
+
     def ensure_result_object(result, origin:)
       raise_unexpected_outcome_error(result, origin) unless result.is_a?(Context)
 
-      return result.tap { _1.acc.merge!(acc) } if result.subject.equal?(subject)
+      return result.tap { _1.acc.merge!(acc) } if result.source.equal?(source)
 
-      raise Error::InvalidResultSubject.build(given_result: result, expected_subject: subject)
+      raise Error::InvalidResultSource.build(given_result: result, expected_source: source)
     end
 
-    EXPECTED_OUTCOME = 'BCDD::Result::Context::Success or BCDD::Result::Context::Failure'
-
     def raise_unexpected_outcome_error(result, origin)
       raise Error::UnexpectedOutcome.build(outcome: result, origin: origin, expected: EXPECTED_OUTCOME)
     end
 
-    private_constant :SubjectMethodArity, :EXPECTED_OUTCOME
+    private_constant :SourceMethodArity
   end
 end

data/lib/bcdd/result/error.rb

@@ -9,7 +9,7 @@ class BCDD::Result::Error < StandardError
   end
 
   class MissingTypeArgument < self
-    def initialize(_arg = nil)
+    def initialize(_message = nil)
       super('A type (argument) is required to invoke the #on/#on_type method')
     end
   end
@@ -22,29 +22,38 @@ class BCDD::Result::Error < StandardError
     end
   end
 
-  class InvalidResultSubject < self
-    def self.build(given_result:, expected_subject:)
+  class InvalidResultSource < self
+    def self.build(given_result:, expected_source:)
       message =
-        "You cannot call #and_then and return a result that does not belong to the subject!\n" \
-        "Expected subject: #{expected_subject.inspect}\n" \
-        "Given subject: #{given_result.send(:subject).inspect}\n" \
+        "You cannot call #and_then and return a result that does not belong to the same source!\n" \
+        "Expected source: #{expected_source.inspect}\n" \
+        "Given source: #{given_result.send(:source).inspect}\n" \
         "Given result: #{given_result.inspect}"
 
       new(message)
     end
   end
 
-  class InvalidSubjectMethodArity < self
-    def self.build(subject:, method:, max_arity:)
-      new("#{subject.class}##{method.name} has unsupported arity (#{method.arity}). Expected 0..#{max_arity}")
+  class InvalidSourceMethodArity < self
+    def self.build(source:, method:, max_arity:)
+      new("#{source.class}##{method.name} has unsupported arity (#{method.arity}). Expected 0..#{max_arity}")
     end
   end
 
   class UnhandledTypes < self
     def self.build(types:)
-      subject = types.size == 1 ? 'This was' : 'These were'
+      source = types.size == 1 ? 'This was' : 'These were'
 
-      new("You must handle all cases. #{subject} not handled: #{types.map(&:inspect).join(', ')}")
+      new("You must handle all cases. #{source} not handled: #{types.map(&:inspect).join(', ')}")
+    end
+  end
+
+  class CallableAndThenDisabled < self
+    def initialize(_message = nil)
+      super(
+        'You cannot use #and_then! as the feature is disabled. ' \
+        'Please use BCDD::Result.config.feature.enable!(:and_then!) to enable it.'
+      )
     end
   end
 end

data/lib/bcdd/result/expectations/mixin.rb

@@ -24,7 +24,7 @@ class BCDD::Result
 
       FACTORY = <<~RUBY
         private def _Result
-          @_Result ||= Result.with(subject: self, terminal: %<terminal>s)
+          @_Result ||= Result.with(source: self, terminal: %<terminal>s)
         end
       RUBY
 
@@ -38,13 +38,13 @@ class BCDD::Result
     module Addons
       module Continue
         private def Continue(value)
-          Success.new(type: :continued, value: value, subject: self)
+          Success.new(type: :continued, value: value, source: self)
         end
       end
 
       module Given
         private def Given(value)
-          Success.new(type: :given, value: value, subject: self)
+          Success.new(type: :given, value: value, source: self)
         end
       end
 

data/lib/bcdd/result/expectations.rb

@@ -38,10 +38,10 @@ class BCDD::Result
 
     private_class_method :mixin!, :mixin_module, :result_factory_without_expectations
 
-    def initialize(subject: nil, contract: nil, terminal: nil, **options)
+    def initialize(source: nil, contract: nil, terminal: nil, **options)
       @terminal = terminal
 
-      @subject = subject
+      @source = source
 
       @contract = contract if contract.is_a?(Contract::Evaluator)
 
@@ -60,16 +60,16 @@ class BCDD::Result
       _ResultAs(Failure, type, value)
     end
 
-    def with(subject:, terminal: nil)
-      self.class.new(subject: subject, terminal: terminal, contract: contract)
+    def with(source:, terminal: nil)
+      self.class.new(source: source, terminal: terminal, contract: contract)
     end
 
     private
 
     def _ResultAs(kind_class, type, value)
-      kind_class.new(type: type, value: value, subject: subject, expectations: contract, terminal: terminal)
+      kind_class.new(type: type, value: value, source: source, expectations: contract, terminal: terminal)
     end
 
-    attr_reader :subject, :terminal, :contract
+    attr_reader :source, :terminal, :contract
   end
 end

data/lib/bcdd/result/mixin.rb

@@ -21,7 +21,7 @@ class BCDD::Result
       end
 
       private def _ResultAs(kind_class, type, value, terminal: nil)
-        kind_class.new(type: type, value: value, subject: self, terminal: terminal)
+        kind_class.new(type: type, value: value, source: self, terminal: terminal)
       end
     end
 

data/lib/bcdd/result/transitions/tracking/disabled.rb

@@ -2,16 +2,26 @@
 
 module BCDD::Result::Transitions
   module Tracking::Disabled
-    def self.start(name:, desc:); end
-
-    def self.finish(result:); end
+    def self.exec(_name, _desc)
+      EnsureResult[yield]
+    end
 
     def self.reset!; end
 
     def self.record(result); end
 
-    def self.record_and_then(_type, _data, _subject)
+    def self.record_and_then(_type, _data, _source)
       yield
     end
+
+    def self.reset_and_then!; end
+
+    class << self
+      private
+
+      def start(name, desc); end
+
+      def finish(result); end
+    end
   end
 end

data/lib/bcdd/result/transitions/tracking/enabled.rb

@@ -6,26 +6,18 @@ module BCDD::Result::Transitions
 
     private :tree, :tree=, :records, :records=, :root_started_at, :root_started_at=
 
-    def start(name:, desc:)
-      name_and_desc = [name, desc]
-
-      tree.frozen? ? root_start(name_and_desc) : tree.insert!(name_and_desc)
-    end
-
-    def finish(result:)
-      node = tree.current
+    def exec(name, desc)
+      start(name, desc)
 
-      tree.move_up!
+      transition_node = tree.current
 
-      return unless node.root?
+      result = EnsureResult[yield]
 
-      duration = (now_in_milliseconds - root_started_at)
+      tree.move_to_root! if transition_node.root?
 
-      metadata = { duration: duration, tree_map: tree.nested_ids }
+      finish(result)
 
-      result.send(:transitions=, version: Tracking::VERSION, records: records, metadata: metadata)
-
-      reset!
+      result
     end
 
     def reset!
@@ -38,11 +30,11 @@ module BCDD::Result::Transitions
       track(result, time: ::Time.now.getutc)
     end
 
-    def record_and_then(type_arg, arg, subject)
+    def record_and_then(type_arg, arg, source)
       type = type_arg.instance_of?(::Method) ? :method : type_arg
 
       unless tree.frozen?
-        current_and_then = { type: type, arg: arg, subject: subject }
+        current_and_then = { type: type, arg: arg, source: source }
         current_and_then[:method_name] = type_arg.name if type == :method
 
         tree.current.value[1] = current_and_then
@@ -51,8 +43,36 @@ module BCDD::Result::Transitions
       yield
     end
 
+    def reset_and_then!
+      return if tree.frozen?
+
+      tree.current.value[1] = Tracking::EMPTY_HASH
+    end
+
     private
 
+    def start(name, desc)
+      name_and_desc = [name, desc]
+
+      tree.frozen? ? root_start(name_and_desc) : tree.insert!(name_and_desc)
+    end
+
+    def finish(result)
+      node = tree.current
+
+      tree.move_up!
+
+      return unless node.root?
+
+      duration = (now_in_milliseconds - root_started_at)
+
+      metadata = { duration: duration, tree_map: tree.nested_ids }
+
+      result.send(:transitions=, version: Tracking::VERSION, records: records, metadata: metadata)
+
+      reset!
+    end
+
     TreeNodeValueNormalizer = ->(id, (nam, des)) { [{ id: id, name: nam, desc: des }, Tracking::EMPTY_HASH] }
 
     def root_start(name_and_desc)
@@ -74,7 +94,7 @@ module BCDD::Result::Transitions
     end
 
     def now_in_milliseconds
-      Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond)
+      ::Process.clock_gettime(::Process::CLOCK_MONOTONIC, :millisecond)
     end
   end
 end

data/lib/bcdd/result/transitions/tree.rb

@@ -46,9 +46,9 @@ class BCDD::Result
       def initialize(value, normalizer: ->(_id, val) { val })
         @size = 0
 
-        @root = Node.new(value, parent: nil, id: @size, normalizer: normalizer)
+        @root = Node.new(value, parent: nil, id: size, normalizer: normalizer)
 
-        @current = @root
+        @current = root
       end
 
       def root_value
@@ -70,19 +70,23 @@ class BCDD::Result
       end
 
       def insert!(value)
-        @current = insert(value)
+        move_to! insert(value)
+      end
+
+      def move_to!(node)
+        tap { @current = node }
       end
 
       def move_up!(level = 1)
-        tap { level.times { @current = current.parent || root } }
+        tap { level.times { move_to!(current.parent || root) } }
       end
 
       def move_down!(level = 1, index: -1)
-        tap { level.times { current.children[index].then { |child| @current = child if child } } }
+        tap { level.times { current.children[index].then { |child| move_to!(child) if child } } }
       end
 
       def move_to_root!
-        tap { @current = root }
+        move_to!(root)
       end
 
       NestedIds = ->(node) { [node.id, node.children.map(&NestedIds)] }

data/lib/bcdd/result/transitions.rb

@@ -7,21 +7,19 @@ class BCDD::Result
 
     THREAD_VAR_NAME = :bcdd_result_transitions_tracking
 
+    EnsureResult = ->(result) do
+      return result if result.is_a?(::BCDD::Result)
+
+      raise Error::UnexpectedOutcome.build(outcome: result, origin: :transitions)
+    end
+
     def self.tracking
       Thread.current[THREAD_VAR_NAME] ||= Tracking.instance
     end
   end
 
-  def self.transitions(name: nil, desc: nil)
-    Transitions.tracking.start(name: name, desc: desc)
-
-    result = yield
-
-    result.is_a?(::BCDD::Result) or raise Error::UnexpectedOutcome.build(outcome: result, origin: :transitions)
-
-    Transitions.tracking.finish(result: result)
-
-    result
+  def self.transitions(name: nil, desc: nil, &block)
+    Transitions.tracking.exec(name, desc, &block)
   rescue ::Exception => e
     Transitions.tracking.reset!
 

data/lib/bcdd/result/version.rb

@@ -2,6 +2,6 @@
 
 module BCDD
   class Result
-    VERSION = '0.11.0'
+    VERSION = '0.12.0'
   end
 end

data/lib/bcdd/result.rb

@@ -1,8 +1,11 @@
 # frozen_string_literal: true
 
+require 'singleton'
+
 require_relative 'result/version'
-require_relative 'result/transitions'
 require_relative 'result/error'
+require_relative 'result/transitions'
+require_relative 'result/callable_and_then'
 require_relative 'result/data'
 require_relative 'result/handler'
 require_relative 'result/failure'
@@ -16,9 +19,9 @@ require_relative 'result/config'
 class BCDD::Result
   attr_accessor :unknown, :transitions
 
-  attr_reader :subject, :data, :type_checker, :terminal
+  attr_reader :source, :data, :type_checker, :terminal
 
-  protected :subject
+  protected :source
 
   private :unknown, :unknown=, :type_checker, :transitions=
 
@@ -32,11 +35,11 @@ class BCDD::Result
     config.freeze
   end
 
-  def initialize(type:, value:, subject: nil, expectations: nil, terminal: nil)
+  def initialize(type:, value:, source: nil, expectations: nil, terminal: nil)
     data = Data.new(kind, type, value)
 
     @type_checker = Contract.evaluate(data, expectations)
-    @subject = subject
+    @source = source
     @terminal = terminal || kind == :failure
     @data = data
 
@@ -88,12 +91,20 @@ class BCDD::Result
     tap { yield(value, type) if unknown }
   end
 
-  def and_then(method_name = nil, context = nil, &block)
+  def and_then(method_name = nil, injected_value = nil, &block)
     return self if terminal?
 
     method_name && block and raise ::ArgumentError, 'method_name and block are mutually exclusive'
 
-    method_name ? call_and_then_subject_method(method_name, context) : call_and_then_block(block)
+    method_name ? call_and_then_source_method(method_name, injected_value) : call_and_then_block(block)
+  end
+
+  def and_then!(source, injected_value = nil, _call: nil)
+    raise Error::CallableAndThenDisabled unless Config.instance.feature.enabled?(:and_then!)
+
+    return self if terminal?
+
+    call_and_then_callable!(source, value: value, injected_value: injected_value, method_name: _call)
   end
 
   def handle
@@ -139,27 +150,27 @@ class BCDD::Result
     block.call(value, type)
   end
 
-  def call_and_then_subject_method(method_name, context_data)
-    method = subject.method(method_name)
+  def call_and_then_source_method(method_name, injected_value)
+    method = source.method(method_name)
 
-    Transitions.tracking.record_and_then(method, context_data, subject) do
-      result = call_and_then_subject_method!(method, context_data)
+    Transitions.tracking.record_and_then(method, injected_value, source) do
+      result = call_and_then_source_method!(method, injected_value)
 
       ensure_result_object(result, origin: :method)
     end
   end
 
-  def call_and_then_subject_method!(method, context_data)
+  def call_and_then_source_method!(method, injected_value)
     case method.arity
-    when 0 then subject.send(method.name)
-    when 1 then subject.send(method.name, value)
-    when 2 then subject.send(method.name, value, context_data)
-    else raise Error::InvalidSubjectMethodArity.build(subject: subject, method: method, max_arity: 2)
+    when 0 then source.send(method.name)
+    when 1 then source.send(method.name, value)
+    when 2 then source.send(method.name, value, injected_value)
+    else raise Error::InvalidSourceMethodArity.build(source: source, method: method, max_arity: 2)
     end
   end
 
   def call_and_then_block(block)
-    Transitions.tracking.record_and_then(:block, nil, subject) do
+    Transitions.tracking.record_and_then(:block, nil, source) do
       result = call_and_then_block!(block)
 
       ensure_result_object(result, origin: :block)
@@ -170,11 +181,15 @@ class BCDD::Result
     block.call(value)
   end
 
+  def call_and_then_callable!(source, value:, injected_value:, method_name:)
+    CallableAndThen::Caller.call(source, value: value, injected_value: injected_value, method_name: method_name)
+  end
+
   def ensure_result_object(result, origin:)
     raise Error::UnexpectedOutcome.build(outcome: result, origin: origin) unless result.is_a?(::BCDD::Result)
 
-    return result if result.subject.equal?(subject)
+    return result if result.source.equal?(source)
 
-    raise Error::InvalidResultSubject.build(given_result: result, expected_subject: subject)
+    raise Error::InvalidResultSource.build(given_result: result, expected_source: source)
   end
 end

data/sig/bcdd/result/callable_and_then.rbs

@@ -0,0 +1,60 @@
+module BCDD::Result::CallableAndThen
+  class Config
+    attr_accessor default_method_name_to_call: Symbol
+
+    def initialize: -> void
+
+    def options: () -> Hash[Symbol, untyped]
+  end
+
+  class Error < BCDD::Result::Error
+  end
+
+  class Error::InvalidArity < Error
+    def self.build: (
+      source: untyped,
+      method: Symbol,
+      arity: String
+    ) -> Error::InvalidArity
+  end
+
+  class Caller
+    def self.call: (
+      untyped source,
+      value: untyped,
+      injected_value: untyped,
+      method_name: (Symbol | nil)
+    ) -> BCDD::Result
+
+    private
+
+    def self.call_proc!: (
+      untyped source,
+      untyped value,
+      untyped injected_value
+    ) -> BCDD::Result
+
+    def self.call_method!: (
+      untyped source,
+      Method method,
+      untyped value,
+      untyped injected_value
+    ) -> BCDD::Result
+
+    def self.callable_method: (
+      untyped source,
+      (Symbol | nil) method_name
+    ) -> ::Method
+
+    def self.ensure_result_object: (
+      untyped source,
+      untyped value,
+      BCDD::Result result
+    ) -> BCDD::Result
+
+    def self.expected_result_object: () -> singleton(BCDD::Result)
+
+    def self.expected_outcome: () -> String
+  end
+end
+

data/sig/bcdd/result/config.rbs

@@ -14,6 +14,8 @@ class BCDD::Result::Config
 
   def initialize: -> void
 
+  def and_then!: () -> BCDD::Result::CallableAndThen::Config
+
   def freeze: -> BCDD::Result::Config
   def options: -> Hash[Symbol, BCDD::Result::Config::Switcher]
   def to_h: -> Hash[Symbol, Hash[Symbol | String, bool]]