bcdd-result 0.10.0 → 0.12.0

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.10.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, :halted
+  attr_reader :source, :data, :type_checker, :terminal
 
-  protected :subject
+  protected :source
 
   private :unknown, :unknown=, :type_checker, :transitions=
 
@@ -32,12 +35,12 @@ class BCDD::Result
     config.freeze
   end
 
-  def initialize(type:, value:, subject: nil, expectations: nil, halted: 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
-    @halted = halted || kind == :failure
+    @source = source
+    @terminal = terminal || kind == :failure
     @data = data
 
     self.unknown = true
@@ -46,8 +49,8 @@ class BCDD::Result
     Transitions.tracking.record(self)
   end
 
-  def halted?
-    halted
+  def terminal?
+    terminal
   end
 
   def type
@@ -88,12 +91,20 @@ class BCDD::Result
     tap { yield(value, type) if unknown }
   end
 
-  def and_then(method_name = nil, context = nil, &block)
-    return self if halted?
+  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]]
@@ -73,6 +75,7 @@ class BCDD::Result::Config::Switcher
 end
 
 module BCDD::Result::Config::Addons
+  AFFECTS: Array[String]
   OPTIONS: Hash[String, Hash[Symbol, untyped]]
 
   def self.switcher: -> BCDD::Result::Config::Switcher

data/sig/bcdd/result/context.rbs

@@ -1,23 +1,28 @@
 class BCDD::Result::Context < BCDD::Result
   EXPECTED_OUTCOME: String
 
-  SubjectMethodArity: ^(Method) -> Integer
+  SourceMethodArity: ^(Method) -> Integer
 
   attr_reader acc: Hash[Symbol, untyped]
 
   def initialize: (
     type: Symbol,
     value: untyped,
-    ?subject: untyped,
+    ?source: untyped,
     ?expectations: BCDD::Result::Contract::Evaluator,
-    ?halted: bool
+    ?terminal: bool
   ) -> void
 
-  def and_then: (?Symbol, **untyped) ?{ (Hash[Symbol, untyped]) -> untyped } -> BCDD::Result::Context
+  def and_then: (?Symbol, **untyped) ?{ (Hash[Symbol, untyped]) -> untyped } -> untyped
+
+  def and_then!: (untyped, **untyped) -> untyped
 
   private
 
-  def call_and_then_subject_method: (Symbol, Hash[Symbol, untyped]) -> BCDD::Result::Context
+  def call_and_then_source_method: (Symbol, Hash[Symbol, untyped]) -> BCDD::Result::Context
+
+  def call_and_then_callable!: (untyped, value: untyped, injected_value: untyped, method_name: (Symbol | nil)) -> BCDD::Result::Context
+
   def ensure_result_object: (untyped, origin: Symbol) -> BCDD::Result::Context
 
   def raise_unexpected_outcome_error: (BCDD::Result::Context | untyped, Symbol) -> void
@@ -27,12 +32,59 @@ class BCDD::Result::Context
   class Success < BCDD::Result::Context
     include BCDD::Result::Success::Methods
 
-    def and_expose: (Symbol, Array[Symbol], halted: bool) -> BCDD::Result::Context::Success
+    def and_expose: (Symbol, Array[Symbol], terminal: bool) -> BCDD::Result::Context::Success
   end
 
   def self.Success: (Symbol, **untyped) -> BCDD::Result::Context::Success
 end
 
+module BCDD::Result::Context::CallableAndThen
+  class Caller < BCDD::Result::CallableAndThen::Caller
+    module KeyArgs
+      def self.parameters?: (untyped) -> bool
+
+      def self.invalid_arity: (untyped, Symbol) -> BCDD::Result::CallableAndThen::Error::InvalidArity
+    end
+
+    def self.call: (
+      untyped source,
+      value: untyped,
+      injected_value: untyped,
+      method_name: (Symbol | nil),
+    ) -> BCDD::Result::Context
+
+    private
+
+    def self.call_proc!: (
+      untyped source,
+      Hash[Symbol, untyped] value,
+      nil injected_value
+    ) -> BCDD::Result::Context
+
+    def self.call_method!: (
+      untyped source,
+      Method method,
+      Hash[Symbol, untyped] value,
+      nil injected_value
+    ) -> BCDD::Result::Context
+
+    def self.callable_method: (
+      untyped source,
+      (Symbol | nil) method_name
+    ) -> ::Method
+
+    def self.ensure_result_object: (
+      untyped source,
+      untyped value,
+      BCDD::Result::Context result
+    ) -> BCDD::Result::Context
+
+    def self.expected_result_object: () -> singleton(BCDD::Result::Context)
+
+    def self.expected_outcome: () -> String
+  end
+end
+
 class BCDD::Result::Context
   class Failure < BCDD::Result::Context
     include BCDD::Result::Failure::Methods
@@ -54,11 +106,11 @@ class BCDD::Result::Context
 
       private
 
-      def _ResultAs: (singleton(BCDD::Result::Context), Symbol, untyped, ?halted: bool) -> untyped
+      def _ResultAs: (singleton(BCDD::Result::Context), Symbol, untyped, ?terminal: bool) -> untyped
     end
 
     module Addons
-      module Continuable
+      module Continue
         include BCDD::Result::Context::Mixin::Methods
 
         private
@@ -66,6 +118,14 @@ class BCDD::Result::Context
         def Continue: (**untyped) -> BCDD::Result::Context::Success
       end
 
+      module Given
+        include BCDD::Result::Context::Mixin::Methods
+
+        private
+
+        def Given: (*untyped) -> BCDD::Result::Context::Success
+      end
+
       OPTIONS: Hash[Symbol, Module]
 
       def self.options: (Hash[Symbol, Hash[Symbol, bool]]) -> Hash[Symbol, Module]
@@ -91,10 +151,14 @@ module BCDD::Result::Context::Expectations::Mixin
   Factory: singleton(BCDD::Result::Expectations::Mixin::Factory)
 
   module Addons
-    module Continuable
+    module Continue
       private def Continue: (**untyped) -> BCDD::Result::Context::Success
     end
 
+    module Given
+      private def Given: (*untyped) -> BCDD::Result::Context::Success
+    end
+
     OPTIONS: Hash[Symbol, Module]
 
     def self.options: (Hash[Symbol, Hash[Symbol, bool]]) -> Hash[Symbol, Module]

data/sig/bcdd/result/error.rbs

@@ -13,19 +13,22 @@ class BCDD::Result
           -> BCDD::Result::Error::UnexpectedOutcome
     end
 
-    class InvalidResultSubject < BCDD::Result::Error
-      def self.build: (given_result: BCDD::Result, expected_subject: untyped)
-          -> BCDD::Result::Error::InvalidResultSubject
+    class InvalidResultSource < BCDD::Result::Error
+      def self.build: (given_result: BCDD::Result, expected_source: untyped)
+          -> BCDD::Result::Error::InvalidResultSource
     end
 
-    class InvalidSubjectMethodArity < BCDD::Result::Error
-      def self.build: (subject: untyped, method: Method, max_arity: Integer)
-        -> BCDD::Result::Error::InvalidSubjectMethodArity
+    class InvalidSourceMethodArity < BCDD::Result::Error
+      def self.build: (source: untyped, method: Method, max_arity: Integer)
+        -> BCDD::Result::Error::InvalidSourceMethodArity
     end
 
     class UnhandledTypes < BCDD::Result::Error
       def self.build: (types: Set[Symbol])
         -> BCDD::Result::Error::UnhandledTypes
     end
+
+    class CallableAndThenDisabled < BCDD::Result::Error
+    end
   end
 end

data/sig/bcdd/result/expectations.rbs

@@ -16,31 +16,31 @@ class BCDD::Result::Expectations
   def self.result_factory_without_expectations: -> singleton(BCDD::Result)
 
   def self.new: (
-    ?subject: untyped,
+    ?source: untyped,
     ?contract: BCDD::Result::Contract::Evaluator,
-    ?halted: bool,
+    ?terminal: bool,
     **untyped
   ) -> (BCDD::Result::Expectations | untyped)
 
   def initialize: (
-    ?subject: untyped,
+    ?source: untyped,
     ?contract: BCDD::Result::Contract::Evaluator,
-    ?halted: bool,
+    ?terminal: bool,
     **untyped
   ) -> void
 
   def Success: (Symbol, ?untyped) -> BCDD::Result::Success
   def Failure: (Symbol, ?untyped) -> BCDD::Result::Failure
 
-  def with: (subject: untyped) -> BCDD::Result::Expectations
+  def with: (source: untyped) -> BCDD::Result::Expectations
 
   private
 
   def _ResultAs: (singleton(BCDD::Result), Symbol, untyped) -> untyped
 
-  attr_reader subject: untyped
+  attr_reader source: untyped
   attr_reader contract: BCDD::Result::Contract::Evaluator
-  attr_reader halted: bool
+  attr_reader terminal: bool
 end
 
 module BCDD::Result::Expectations::Mixin
@@ -56,10 +56,14 @@ module BCDD::Result::Expectations::Mixin
   end
 
   module Addons
-    module Continuable
+    module Continue
       private def Continue: (untyped) -> BCDD::Result::Success
     end
 
+    module Given
+      private def Given: (untyped) -> BCDD::Result::Success
+    end
+
     OPTIONS: Hash[Symbol, Module]
 
     def self.options: (Hash[Symbol, Hash[Symbol, bool]]) -> Hash[Symbol, Module]

data/sig/bcdd/result/mixin.rbs

@@ -11,11 +11,11 @@ class BCDD::Result
 
       private
 
-      def _ResultAs: (singleton(BCDD::Result), Symbol, untyped, ?halted: bool) -> untyped
+      def _ResultAs: (singleton(BCDD::Result), Symbol, untyped, ?terminal: bool) -> untyped
     end
 
     module Addons
-      module Continuable
+      module Continue
         include BCDD::Result::Mixin::Methods
 
         private
@@ -23,6 +23,14 @@ class BCDD::Result
         def Continue: (untyped) -> BCDD::Result::Success
       end
 
+      module Given
+        include BCDD::Result::Mixin::Methods
+
+        private
+
+        def Given: (untyped) -> BCDD::Result::Success
+      end
+
       OPTIONS: Hash[Symbol, Module]
 
       def self.options: (Hash[Symbol, Hash[Symbol, bool]]) -> Hash[Symbol, Module]

data/sig/bcdd/result/transitions.rbs

@@ -32,7 +32,8 @@ class BCDD::Result
       def parent_value: () -> untyped
       def current_value: () -> untyped
       def insert: (untyped) -> Node
-      def insert!: (untyped) -> Node
+      def insert!: (untyped) -> Tree
+      def move_to!: (Node) -> Tree
       def move_up!: (?Integer level) -> Tree
       def move_down!: (?Integer level) -> Tree
       def move_to_root!: () -> Tree
@@ -54,14 +55,17 @@ class BCDD::Result
         private attr_accessor records: Array[Hash[Symbol, untyped]]
         private attr_accessor root_started_at: Integer
 
-        def start: (name: String, desc: String) -> void
-        def finish: (result: BCDD::Result) -> void
+        def exec: (String, String) { () -> untyped } -> BCDD::Result
         def reset!: () -> void
         def record: (BCDD::Result) -> void
         def record_and_then: ((untyped), untyped, untyped) { () -> BCDD::Result } -> BCDD::Result
+        def reset_and_then!: () -> void
 
         private
 
+        def start: (String, String) -> void
+        def finish: (BCDD::Result) -> void
+
         TreeNodeValueNormalizer: ^(Integer, Array[untyped]) -> untyped
 
         def root_start: (Array[untyped]) -> void
@@ -72,11 +76,16 @@ class BCDD::Result
       end
 
       module Disabled
-        def self.start: (name: String, desc: String) -> void
-        def self.finish: (result: BCDD::Result) -> void
+        def self.exec: (String, String) { () -> untyped } -> BCDD::Result
         def self.reset!: () -> void
         def self.record: (BCDD::Result) -> void
         def self.record_and_then: ((untyped), untyped, untyped) { () -> BCDD::Result } -> BCDD::Result
+        def self.reset_and_then!: () -> void
+
+        private
+
+        def self.start: (String, String) -> void
+        def self.finish: (BCDD::Result) -> void
       end
 
       def self.instance: () -> (Enabled | singleton(Disabled))
@@ -84,6 +93,8 @@ class BCDD::Result
 
     THREAD_VAR_NAME: Symbol
 
+    EnsureResult: ^(untyped) -> BCDD::Result
+
     def self.tracking: () -> (Tracking::Enabled | singleton(Tracking::Disabled))
   end
 end