bcdd-result 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e4fa0b7a751971ae5fd7987906342e6436535b9bb8729252c7651a5c533302c
-  data.tar.gz: c2f2359525d2c24e28da5d400ef3e7284ccb2c13b8955da84cddb8da7b229cb3
+  metadata.gz: 7bf2a03ac7efd3e75e03b2f5617518cb07f40e03cc970c612f3d4dfcdad153ad
+  data.tar.gz: 2717e6e600101401f420164aed020689e9c07dd7f7296c78ec5290562620ca3c
 SHA512:
-  metadata.gz: 1fba0932c35635a248eeef6c88b8c386ce2f8a55f235784ea6c144299a0a17f8501efa16f5a171babd2a883b90a8d06726bd47bfcb2261196d726068b8d6e097
-  data.tar.gz: 66722933fdb17f8317c0989ee103a38479b49ffb151ac23199ad91669a48a693af9ccce2b863dda913c54bc3b9d446ce802b0b4221352dffd68a08de4c647a23
+  metadata.gz: c1761571f7d0c0a6fd4601a9f8a4c8c18688085226cd061057f95c93737da80ac58e0a99a3803a0e0f93aa5040530975d9b16a7b54df79487ca625fd67d405d6
+  data.tar.gz: 4b22f37d2282de4c0a6e3781e86c9c63457efa83a7d5dc07db4288b9fe19c5b3868cd13a34a1cfc515776cf466e2095bde9d10503f87b8f546ceab9408ef9617

data/.rubocop.yml

@@ -9,6 +9,10 @@ AllCops:
   NewCops: enable
   TargetRubyVersion: 2.7
 
+Lint/RescueException:
+  Exclude:
+    - lib/bcdd/result/transitions.rb
+
 Layout/LineLength:
   Max: 120
 
@@ -70,6 +74,10 @@ Minitest/AssertEmptyLiteral:
 Minitest/AssertOperator:
   Enabled: false
 
+Minitest/AssertWithExpectedArgument:
+  Exclude:
+    - test/test_helper.rb
+
 Naming/FileName:
   Exclude:
     - lib/bcdd-result.rb

data/CHANGELOG.md

@@ -1,33 +1,56 @@
 - [\[Unreleased\]](#unreleased)
-- [\[0.9.0\] - 2023-12-12](#090---2023-12-12)
+- [\[0.10.0\] - 2023-12-31](#0100---2023-12-31)
   - [Added](#added)
+- [\[0.9.1\] - 2023-12-12](#091---2023-12-12)
   - [Changed](#changed)
-- [\[0.8.0\] - 2023-12-11](#080---2023-12-11)
+  - [Fixed](#fixed)
+- [\[0.9.0\] - 2023-12-12](#090---2023-12-12)
   - [Added](#added-1)
   - [Changed](#changed-1)
-  - [Removed](#removed)
-- [\[0.7.0\] - 2023-10-27](#070---2023-10-27)
+- [\[0.8.0\] - 2023-12-11](#080---2023-12-11)
   - [Added](#added-2)
   - [Changed](#changed-2)
-- [\[0.6.0\] - 2023-10-11](#060---2023-10-11)
+  - [Removed](#removed)
+- [\[0.7.0\] - 2023-10-27](#070---2023-10-27)
   - [Added](#added-3)
   - [Changed](#changed-3)
-- [\[0.5.0\] - 2023-10-09](#050---2023-10-09)
+- [\[0.6.0\] - 2023-10-11](#060---2023-10-11)
   - [Added](#added-4)
-- [\[0.4.0\] - 2023-09-28](#040---2023-09-28)
-  - [Added](#added-5)
   - [Changed](#changed-4)
+- [\[0.5.0\] - 2023-10-09](#050---2023-10-09)
+  - [Added](#added-5)
+- [\[0.4.0\] - 2023-09-28](#040---2023-09-28)
+  - [Added](#added-6)
+  - [Changed](#changed-5)
   - [Removed](#removed-1)
 - [\[0.3.0\] - 2023-09-26](#030---2023-09-26)
-  - [Added](#added-6)
-- [\[0.2.0\] - 2023-09-26](#020---2023-09-26)
   - [Added](#added-7)
+- [\[0.2.0\] - 2023-09-26](#020---2023-09-26)
+  - [Added](#added-8)
   - [Removed](#removed-2)
 - [\[0.1.0\] - 2023-09-25](#010---2023-09-25)
-  - [Added](#added-8)
+  - [Added](#added-9)
 
 ## [Unreleased]
 
+## [0.10.0] - 2023-12-31
+
+### Added
+
+- Add `BCDD::Result.transitions(&block)` to track all transitions in the same or between different operations. When there is a nesting of transition blocks, this mechanism will be able to correlate parent and child blocks and present the duration of all operations in milliseconds.
+
+- Add `BCDD::Result.config.feature.disable!(:transitions)` and `BCDD::Result.config.feature.enable!(:transitions)` to turn on/off the `BCDD::Result.transitions` feature.
+
+## [0.9.1] - 2023-12-12
+
+### Changed
+
+- **(BREAKING)** Make `BCDD::Result::Context::Success#and_expose()` to produce a halted success by default. You can turn this off by passing `halted: false`.
+
+### Fixed
+
+- Make `BCDD::Result::Context#and_then(&block)` accumulate the result value.
+
 ## [0.9.0] - 2023-12-12
 
 ### Added

data/README.md

@@ -70,6 +70,8 @@ Use it to enable the [Railway Oriented Programming](https://fsharpforfunandprofi
       - [Module example (Singleton Methods)](#module-example-singleton-methods-1)
     - [`BCDD::Result::Context::Expectations`](#bcddresultcontextexpectations)
     - [Mixin add-ons](#mixin-add-ons)
+  - [`BCDD::Result.transitions`](#bcddresulttransitions)
+    - [Configuration](#configuration)
   - [`BCDD::Result.configuration`](#bcddresultconfiguration)
     - [`config.addon.enable!(:continue)`](#configaddonenablecontinue)
     - [`config.constant_alias.enable!('Result', 'BCDD::Context')`](#configconstant_aliasenableresult-bcddcontext)
@@ -983,7 +985,7 @@ module Divide
 end
 ```
 
-In the code above, we define a constant `Divide::Expected`. And because of this (it is a constant), we can use it inside and outside the module.
+In the code above, we define a constant `Divide::Result`. And because of this (it is a constant), we can use it inside and outside the module.
 
 Look what happens if you try to create a result without one of the expected types.
 
@@ -1223,7 +1225,7 @@ Divide.call(4, 2)
 
 #### Value checking - Result Creation
 
-The `Result::Expectations` supports types of validations. The first is the type checking only, and the second is the type and value checking.
+The `Result::Expectations` supports two types of validations. The first is the type checking only, and the second is the type and value checking.
 
 To define expectations for your result's values, you must declare a Hash with the type as the key and the value as the value. A value validator is any object that responds to `#===` (case equality operator).
 
@@ -1569,11 +1571,13 @@ Divide.new.call(10, 5)
 #<BCDD::Result::Context::Success type=:ok value={:number=>2, :number1=>10, :number2=>5}>
 ```
 
+> PS: The `#and_expose` produces a halted success by default. This means the next step will not be executed even if you call `#and_then` after `#and_expose`. To change this behavior, you can pass `halted: false` to `#and_expose`.
+
 <p align="right"><a href="#-bcddresult">⬆️ &nbsp;back to top</a></p>
 
 ##### Module example (Singleton Methods)
 
-Yes, the `BCDD::Result::Context.mixin` can produce singleton methods. Look for an example using a module (but it could be a class, too).
+`BCDD::Result::Context.mixin` can also produce singleton methods. Below is an example using a module (but it could be a class, too).
 
 ```ruby
 module Divide
@@ -1658,7 +1662,7 @@ Divide.new.call(10, 5)
 
 As in the `BCDD::Result::Expectations.mixin`, the `BCDD::Result::Context::Expectations.mixin` will add a Result constant in the target class. It can generate success/failure results, which ensure the mixin expectations.
 
-Let's see this using previous example:
+Let's see this using the previous example:
 
 ```ruby
 Divide::Result::Success(:division_completed, number: 2)
@@ -1745,6 +1749,160 @@ Divide.call(14, 0)
 #<BCDD::Result::Context::Failure type=:division_by_zero value={:message=>"arg2 must not be zero"}>
 ```
 
+### `BCDD::Result.transitions`
+
+Use `BCDD::Result.transitions(&block)` to track all transitions in the same or between different operations. When there is a nesting of transition blocks, this mechanism will be able to correlate parent and child blocks and present the duration of all operations in milliseconds.
+
+When you wrap the creation of the result with `BCDD::Result.transitions`, the final result will expose all the transition records through the `BCDD::Result#transitions` method.
+
+```ruby
+class Division
+  include BCDD::Result.mixin(config: { addon: { continue: true } })
+
+  def call(arg1, arg2)
+    BCDD::Result.transitions(name: 'Division', desc: 'divide two numbers') do
+      require_numbers(arg1, arg2)
+        .and_then(:check_for_zeros)
+        .and_then(:divide)
+    end
+  end
+
+  private
+
+  ValidNumber = ->(arg) { arg.is_a?(Numeric) && arg != Float::NAN && arg != Float::INFINITY }
+
+  def require_numbers(arg1, arg2)
+    ValidNumber[arg1] or return Failure(:invalid_arg, 'arg1 must be a valid number')
+    ValidNumber[arg2] or return Failure(:invalid_arg, 'arg2 must be a valid number')
+
+    Continue([arg1, arg2])
+  end
+
+  def check_for_zeros(numbers)
+    num1, num2 = numbers
+
+    return Failure(:division_by_zero, 'num2 cannot be zero') if num2.zero?
+
+    num1.zero? ? Success(:division_completed, 0) : Continue(numbers)
+  end
+
+  def divide((num1, num2))
+    Success(:division_completed, num1 / num2)
+  end
+end
+
+module SumDivisionsByTwo
+  extend self, BCDD::Result.mixin
+
+  def call(*numbers)
+    BCDD::Result.transitions(name: 'SumDivisionsByTwo') do
+      divisions = numbers.map { |number| Division.new.call(number, 2) }
+
+      if divisions.any?(&:failure?)
+        Failure(:errors, divisions.select(&:failure?).map(&:value))
+      else
+        Success(:sum, divisions.sum(&:value))
+      end
+    end
+  end
+end
+```
+
+Let's see the result of the `SumDivisionsByTwo` call:
+
+```ruby
+result = SumDivisionsByTwo.call(20, 10)
+# => #<BCDD::Result::Success type=:sum value=15>
+
+result.transitions
+{
+  :version =>1,
+  :metadata => {
+    :duration => 0,                       # milliseconds
+    :tree_map => [0, [[1, []], [2, []]]], # represents the tree of transitions using the id of each transition block
+  },
+  :records => [
+    {
+      :root => {:id=>0, :name=>"SumDivisionsByTwo", :desc=>nil},
+      :parent => {:id=>0, :name=>"SumDivisionsByTwo", :desc=>nil},
+      :current => {:id=>1, :name=>"Division", :desc=>"divide two numbers"},
+      :result => {:kind=>:success, :type=>:continued, :value=>[20, 2]},
+      :and_then => {},
+      :time => 2023-12-31 22:19:33.281619 UTC
+    },
+    {
+      :root=>{:id=>0, :name=>"SumDivisionsByTwo", :desc=>nil},
+      :parent=>{:id=>0, :name=>"SumDivisionsByTwo", :desc=>nil},
+      :current=>{:id=>1, :name=>"Division", :desc=>"divide two numbers"},
+      :result=>{:kind=>:success, :type=>:continued, :value=>[20, 2]},
+      :and_then=>{:type=>:method, :arg=>nil, :subject=>#<Division:0x0000000103e5f7c8>, :method_name=>:check_for_zeros},
+      :time=>2023-12-31 22:19:33.281693 UTC
+    },
+    {
+      :root=>{:id=>0, :name=>"SumDivisionsByTwo", :desc=>nil},
+      :parent=>{:id=>0, :name=>"SumDivisionsByTwo", :desc=>nil},
+      :current=>{:id=>1, :name=>"Division", :desc=>"divide two numbers"},
+      :result=>{:kind=>:success, :type=>:division_completed, :value=>10},
+      :and_then=>{:type=>:method, :arg=>nil, :subject=>#<Division:0x0000000103e5f7c8>, :method_name=>:divide},
+      :time=>2023-12-31 22:19:33.281715 UTC
+    },
+    {
+      :root=>{:id=>0, :name=>"SumDivisionsByTwo", :desc=>nil},
+      :parent=>{:id=>0, :name=>"SumDivisionsByTwo", :desc=>nil},
+      :current=>{:id=>2, :name=>"Division", :desc=>"divide two numbers"},
+      :result=>{:kind=>:success, :type=>:continued, :value=>[10, 2]},
+      :and_then=>{},
+      :time=>2023-12-31 22:19:33.281747 UTC
+    },
+    {
+      :root=>{:id=>0, :name=>"SumDivisionsByTwo", :desc=>nil},
+      :parent=>{:id=>0, :name=>"SumDivisionsByTwo", :desc=>nil},
+      :current=>{:id=>2, :name=>"Division", :desc=>"divide two numbers"},
+      :result=>{:kind=>:success, :type=>:continued, :value=>[10, 2]},
+      :and_then=>{:type=>:method, :arg=>nil, :subject=>#<Division:0x0000000103e5f1b0>, :method_name=>:check_for_zeros},
+      :time=>2023-12-31 22:19:33.281755 UTC
+    },
+    {
+      :root=>{:id=>0, :name=>"SumDivisionsByTwo", :desc=>nil},
+      :parent=>{:id=>0, :name=>"SumDivisionsByTwo", :desc=>nil},
+      :current=>{:id=>2, :name=>"Division", :desc=>"divide two numbers"},
+      :result=>{:kind=>:success, :type=>:division_completed, :value=>5},
+      :and_then=>{:type=>:method, :arg=>nil, :subject=>#<Division:0x0000000103e5f1b0>, :method_name=>:divide},
+      :time=>2023-12-31 22:19:33.281763 UTC
+    },
+    {
+      :root=>{:id=>0, :name=>"SumDivisionsByTwo", :desc=>nil},
+      :parent=>{:id=>0, :name=>"SumDivisionsByTwo", :desc=>nil},
+      :current=>{:id=>0, :name=>"SumDivisionsByTwo", :desc=>nil},
+      :result=>{:kind=>:success, :type=>:sum, :value=>15},
+      :and_then=>{},
+      :time=>2023-12-31 22:19:33.281784 UTC
+    }
+  ]
+}
+```
+
+<p align="right"><a href="#-bcddresult">⬆️ &nbsp;back to top</a></p>
+
+#### Configuration
+
+You can use `BCDD::Result.config.feature.disable!(:transitions)` and `BCDD::Result.config.feature.enable!(:transitions)` to turn on/off the `BCDD::Result.transitions` feature.
+
+```ruby
+BCDD::Result.configuration do |config|
+  config.feature.disable!(:transitions)
+end
+
+result = SumDivisionsByTwo.call(20, 10)
+# => #<BCDD::Result::Success type=:sum value=15>
+
+result.transitions
+
+{:version=>1, :records=>[], :metadata=>{:duration=>0, :tree_map=>[]}}
+```
+
+<p align="right"><a href="#-bcddresult">⬆️ &nbsp;back to top</a></p>
+
 ### `BCDD::Result.configuration`
 
 The `BCDD::Result.configuration` allows you to configure default behaviors for `BCDD::Result` and `BCDD::Result::Context` through a configuration block. After using it, the configuration is frozen, ensuring the expected behaviors for your application.
@@ -1791,7 +1949,7 @@ PS: I'm using `::Rails.env.production?` to check the environment, but you can us
 
 ### `BCDD::Result.config`
 
-The `BCDD::Result.config` allows you to access the current configuration. It is useful when you want to check the current configuration.
+The `BCDD::Result.config` allows you to access the current configuration.
 
 **BCDD::Result.config.addon**
 
@@ -1857,6 +2015,13 @@ BCDD::Result.config.feature.options
 #       "BCDD::Result::Expectations,
 #       "BCDD::Result::Context::Expectations"
 #     ]
+#   },
+#   :transitions=>{
+#     :enabled=>true,
+#     :affects=>[
+#       "BCDD::Result",
+#       "BCDD::Result::Context"
+#     ]
 #   }
 # }
 ```

data/Steepfile

@@ -10,8 +10,8 @@ target :lib do
   # check 'app/models/**/*.rb'        # Glob
   # ignore 'lib/templates/*.rb'
 
-  library 'singleton'               # Standard libraries
-  # library 'strong_json'           # Gems
+  library 'singleton', 'securerandom' # Standard libraries
+  # library 'strong_json'             # Gems
 
   # configure_code_diagnostics(D::Ruby.default)      # `default` diagnostics setting (applies by default)
   # configure_code_diagnostics(D::Ruby.strict)       # `strict` diagnostics setting

data/lib/bcdd/result/config/switchers/addons.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+class BCDD::Result
+  class Config
+    module Addons
+      OPTIONS = {
+        continue: {
+          default: false,
+          affects: %w[BCDD::Result BCDD::Result::Context BCDD::Result::Expectations BCDD::Result::Context::Expectations]
+        }
+      }.transform_values!(&:freeze).freeze
+
+      def self.switcher
+        Switcher.new(options: OPTIONS)
+      end
+    end
+
+    private_constant :Addons
+  end
+end

data/lib/bcdd/result/config/{constant_alias.rb → switchers/constant_aliases.rb}

@@ -2,7 +2,7 @@
 
 class BCDD::Result
   class Config
-    module ConstantAlias
+    module ConstantAliases
       MAPPING = {
         'Result' => { target: ::Object, name: :Result, value: ::BCDD::Result },
         'Context' => { target: ::Object, name: :Context, value: ::BCDD::Result::Context },
@@ -15,14 +15,14 @@ class BCDD::Result
         [option_name, { default: false, affects: [affects].freeze }]
       end.freeze
 
-      Listener = ->(option_name, boolean) do
+      Listener = ->(option_name, bool) do
         mapping = MAPPING.fetch(option_name)
 
         target, name, value = mapping.fetch_values(:target, :name, :value)
 
         defined = target.const_defined?(name, false)
 
-        boolean ? defined || target.const_set(name, value) : defined && target.send(:remove_const, name)
+        bool ? defined || target.const_set(name, value) : defined && target.send(:remove_const, name)
       end
 
       def self.switcher
@@ -30,6 +30,6 @@ class BCDD::Result
       end
     end
 
-    private_constant :ConstantAlias
+    private_constant :ConstantAliases
   end
 end

data/lib/bcdd/result/config/switchers/features.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+class BCDD::Result
+  class Config
+    module Features
+      OPTIONS = {
+        expectations: {
+          default: true,
+          affects: %w[BCDD::Result::Expectations BCDD::Result::Context::Expectations]
+        },
+        transitions: {
+          default: true,
+          affects: %w[BCDD::Result BCDD::Result::Context]
+        }
+      }.transform_values!(&:freeze).freeze
+
+      Listener = ->(option_name, _bool) do
+        Thread.current[Transitions::THREAD_VAR_NAME] = nil if option_name == :transitions
+      end
+
+      def self.switcher
+        Switcher.new(options: OPTIONS, listener: Listener)
+      end
+    end
+
+    private_constant :Features
+  end
+end

data/lib/bcdd/result/config/switchers/pattern_matching.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+class BCDD::Result
+  class Config
+    module PatternMatching
+      OPTIONS = {
+        nil_as_valid_value_checking: {
+          default: false,
+          affects: %w[BCDD::Result::Expectations BCDD::Result::Context::Expectations]
+        }
+      }.transform_values!(&:freeze).freeze
+
+      def self.switcher
+        Switcher.new(options: OPTIONS)
+      end
+    end
+
+    private_constant :PatternMatching
+  end
+end

data/lib/bcdd/result/config.rb

@@ -4,40 +4,22 @@ require 'singleton'
 
 require_relative 'config/options'
 require_relative 'config/switcher'
-require_relative 'config/constant_alias'
+require_relative 'config/switchers/addons'
+require_relative 'config/switchers/constant_aliases'
+require_relative 'config/switchers/features'
+require_relative 'config/switchers/pattern_matching'
 
 class BCDD::Result
   class Config
     include Singleton
 
-    ADDON = {
-      continue: {
-        default: false,
-        affects: %w[BCDD::Result BCDD::Result::Context BCDD::Result::Expectations BCDD::Result::Context::Expectations]
-      }
-    }.transform_values!(&:freeze).freeze
-
-    FEATURE = {
-      expectations: {
-        default: true,
-        affects: %w[BCDD::Result::Expectations BCDD::Result::Context::Expectations]
-      }
-    }.transform_values!(&:freeze).freeze
-
-    PATTERN_MATCHING = {
-      nil_as_valid_value_checking: {
-        default: false,
-        affects: %w[BCDD::Result::Expectations BCDD::Result::Context::Expectations]
-      }
-    }.transform_values!(&:freeze).freeze
-
     attr_reader :addon, :feature, :constant_alias, :pattern_matching
 
     def initialize
-      @addon = Switcher.new(options: ADDON)
-      @feature = Switcher.new(options: FEATURE)
-      @constant_alias = ConstantAlias.switcher
-      @pattern_matching = Switcher.new(options: PATTERN_MATCHING)
+      @addon = Addons.switcher
+      @feature = Features.switcher
+      @constant_alias = ConstantAliases.switcher
+      @pattern_matching = PatternMatching.switcher
     end
 
     def freeze
@@ -65,7 +47,5 @@ class BCDD::Result
     def inspect
       "#<#{self.class.name} options=#{options.keys.sort.inspect}>"
     end
-
-    private_constant :ADDON, :FEATURE, :PATTERN_MATCHING
   end
 end

data/lib/bcdd/result/context/failure.rb

@@ -3,7 +3,7 @@
 class BCDD::Result::Context::Failure < BCDD::Result::Context
   include BCDD::Result::Failure::Methods
 
-  def and_expose(_type, _keys)
+  def and_expose(_type, _keys, **_options)
     self
   end
 end

data/lib/bcdd/result/context/success.rb

@@ -3,13 +3,13 @@
 class BCDD::Result::Context::Success < BCDD::Result::Context
   include ::BCDD::Result::Success::Methods
 
-  def and_expose(type, keys)
+  def and_expose(type, keys, halted: true)
     unless keys.is_a?(::Array) && !keys.empty? && keys.all?(::Symbol)
       raise ::ArgumentError, 'keys must be an Array of Symbols'
     end
 
     exposed_value = acc.merge(value).slice(*keys)
 
-    self.class.new(type: type, value: exposed_value, subject: subject)
+    self.class.new(type: type, value: exposed_value, subject: subject, halted: halted)
   end
 end

data/lib/bcdd/result/context.rb

@@ -40,19 +40,20 @@ class BCDD::Result
       -1
     end
 
-    def call_subject_method(method_name, context)
-      method = subject.method(method_name)
-
-      acc.merge!(value.merge(context))
+    def call_and_then_subject_method!(method, context_data)
+      acc.merge!(value.merge(context_data))
+
+      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)
+      end
+    end
 
-      result =
-        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)
-        end
+    def call_and_then_block!(block)
+      acc.merge!(value)
 
-      ensure_result_object(result, origin: :method)
+      block.call(acc)
     end
 
     def ensure_result_object(result, origin:)

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

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module BCDD::Result::Transitions
+  module Tracking::Disabled
+    def self.start(name:, desc:); end
+
+    def self.finish(result:); end
+
+    def self.reset!; end
+
+    def self.record(result); end
+
+    def self.record_and_then(_type, _data, _subject)
+      yield
+    end
+  end
+end

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

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module BCDD::Result::Transitions
+  class Tracking::Enabled
+    attr_accessor :tree, :records, :root_started_at
+
+    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
+
+      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
+
+    def reset!
+      self.tree = Tracking::EMPTY_TREE
+    end
+
+    def record(result)
+      return if tree.frozen?
+
+      track(result, time: ::Time.now.getutc)
+    end
+
+    def record_and_then(type_arg, arg, subject)
+      type = type_arg.instance_of?(::Method) ? :method : type_arg
+
+      unless tree.frozen?
+        current_and_then = { type: type, arg: arg, subject: subject }
+        current_and_then[:method_name] = type_arg.name if type == :method
+
+        tree.current.value[1] = current_and_then
+      end
+
+      yield
+    end
+
+    private
+
+    TreeNodeValueNormalizer = ->(id, (nam, des)) { [{ id: id, name: nam, desc: des }, Tracking::EMPTY_HASH] }
+
+    def root_start(name_and_desc)
+      self.root_started_at = now_in_milliseconds
+
+      self.records = []
+
+      self.tree = Tree.new(name_and_desc, normalizer: TreeNodeValueNormalizer)
+    end
+
+    def track(result, time:)
+      result = result.data.to_h
+
+      root, = tree.root_value
+      parent, = tree.parent_value
+      current, and_then = tree.current_value
+
+      records << { root: root, parent: parent, current: current, result: result, and_then: and_then, time: time }
+    end
+
+    def now_in_milliseconds
+      Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond)
+    end
+  end
+end