bcdd-result 0.11.0 → 0.13.0

data/README.md

@@ -1,9 +1,11 @@
 <p align="center">
   <h1 align="center" id="-bcddresult">🔀 BCDD::Result</h1>
-  <p align="center"><i>Empower Ruby apps with pragmatic use of Result pattern (monad), Railway Oriented Programming, and B/CDD.</i></p>
+  <p align="center"><i>Unleash a pragmatic and observable use of Result Pattern and Railway-Oriented Programming in Ruby.</i></p>
   <p align="center">
     <img src="https://img.shields.io/badge/ruby->%3D%202.7.0-ruby.svg?colorA=99004d&colorB=cc0066" alt="Ruby">
     <a href="https://rubygems.org/gems/bcdd-result"><img src="https://badge.fury.io/rb/bcdd-result.svg" alt="bcdd-result gem version" height="18"></a>
+    <a href="https://codeclimate.com/github/B-CDD/result/maintainability"><img src="https://api.codeclimate.com/v1/badges/aa8360f8f012d7dedd62/maintainability" /></a>
+    <a href="https://codeclimate.com/github/B-CDD/result/test_coverage"><img src="https://api.codeclimate.com/v1/badges/aa8360f8f012d7dedd62/test_coverage" /></a>
   </p>
 </p>
 
@@ -70,14 +72,21 @@ 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!(:given, :continue)`](#configaddonenablegiven-continue)
-    - [`config.constant_alias.enable!('Result', 'BCDD::Context')`](#configconstant_aliasenableresult-bcddcontext)
-    - [`config.pattern_matching.disable!(:nil_as_valid_value_checking)`](#configpattern_matchingdisablenil_as_valid_value_checking)
-    - [`config.feature.disable!(:expectations)`](#configfeaturedisableexpectations)
+- [`BCDD::Result.transitions`](#bcddresulttransitions)
+  - [`ids_tree` *versus* `ids_matrix`](#ids_tree-versus-ids_matrix)
+  - [Configuration](#configuration)
+    - [Turning on/off](#turning-onoff)
+    - [Setting a `trace_id` fetcher](#setting-a-trace_id-fetcher)
+    - [Setting a `listener`](#setting-a-listener)
+    - [Setting multiple `listeners`](#setting-multiple-listeners)
+- [`BCDD::Result.configuration`](#bcddresultconfiguration)
   - [`BCDD::Result.config`](#bcddresultconfig)
+- [`BCDD::Result#and_then!`](#bcddresultand_then)
+    - [Dependency Injection](#dependency-injection-1)
+    - [Configuration](#configuration-1)
+    - [Analysis: Why is `and_then!` an Anti-pattern?](#analysis-why-is-and_then-an-anti-pattern)
+    - [`#and_then` versus `#and_then!`](#and_then-versus-and_then)
+    - [Analysis: Why is `#and_then` the antidote/standard?](#analysis-why-is-and_then-the-antidotestandard)
 - [About](#about)
 - [Development](#development)
 - [Contributing](#contributing)
@@ -649,9 +658,9 @@ Divide.call(2, 2)
 
 This method generates a module that any object can include or extend. It adds two methods to the target object: `Success()` and `Failure()`.
 
-The main difference between these methods and `BCDD::Result::Success()`/`BCDD::Result::Failure()` is that the former will utilize the target object (which has received the include/extend) as the result's subject.
+The main difference between these methods and `BCDD::Result::Success()`/`BCDD::Result::Failure()` is that the former will utilize the target object (which has received the include/extend) as the result's source.
 
-Because the result has a subject, the `#and_then` method can call methods from it.
+Because the result has a source, the `#and_then` method can call methods from it.
 
 ##### Class example (Instance Methods)
 
@@ -746,9 +755,9 @@ Divide.call(4, '2') #<BCDD::Result::Failure type=:invalid_arg value="arg2 must b
 
 To use the `#and_then` method to call methods, they must use `Success()` and `Failure()` to produce the results.
 
-If you try to use `BCDD::Result::Subject()`/`BCDD::Result::Failure()`, or results from another `BCDD::Result.mixin` instance with `#and_then`, it will raise an error because the subjects will be different.
+If you try to use `BCDD::Result::Success()`/`BCDD::Result::Failure()`, or results from another `BCDD::Result.mixin` instance with `#and_then`, it will raise an error because the sources are different.
 
-**Note:** You can still use the block syntax, but all the results must be produced by the subject's `Success()` and `Failure()` methods.
+**Note:** You can still use the block syntax, but all the results must be produced by the source's `Success()` and `Failure()` methods.
 
 ```ruby
 module ValidateNonzero
@@ -794,13 +803,13 @@ Look at the error produced by the code above:
 ```ruby
 Divide.call(2, 0)
 
-# You cannot call #and_then and return a result that does not belong to the subject! (BCDD::Result::Error::InvalidResultSubject)
-# Expected subject: Divide
-# Given subject: ValidateNonzero
+# You cannot call #and_then and return a result that does not belong to the same source! (BCDD::Result::Error::InvalidResultSource)
+# Expected source: Divide
+# Given source: ValidateNonzero
 # Given result: #<BCDD::Result::Failure type=:division_by_zero value="arg2 must not be zero">
 ```
 
-In order to fix this, you must handle the result produced by `ValidateNonzero.call()` and return a result that belongs to the subject.
+In order to fix this, you must handle the result produced by `ValidateNonzero.call()` and return a result that belongs to the same source.
 
 ```ruby
 module ValidateNonzero
@@ -832,7 +841,8 @@ module Divide
   end
 
   def validate_nonzero(numbers)
-    # In this case we are handling the other subject result and returning our own
+    # In this case we are handling the result from other source
+    # and returning our own
     ValidateNonzero.call(numbers).handle do |on|
       on.success { |numbers| Success(:ok, numbers) }
 
@@ -858,8 +868,8 @@ Divide.call(2, 0)
 
 ##### Dependency Injection
 
-The `BCDD::Result#and_then` accepts a second argument that will be used to share a value with the subject's method.
-To receive this argument, the subject's method must have an arity of two, where the first argument will be the result value and the second will be the shared value.
+The `BCDD::Result#and_then` accepts a second argument that will be used to share a value with the source's method.
+To receive this argument, the source's method must have an arity of two, where the first argument will be the result value and the second will be the injected value.
 
 ```ruby
 require 'logger'
@@ -1411,7 +1421,7 @@ result = Divide.new.call(4, 2)
 
 # The example below shows an error because the :ok type is not allowed.
 # But look at the allowed types have only one type (:division_completed).
-# This is because the :continued type is ignored by the expectations.
+# This is because the :_continue_ type is ignored by the expectations.
 #
 result.success?(:ok)
 # type :ok is not allowed. Allowed types: :division_completed (BCDD::Result::Contract::Error::UnexpectedType)
@@ -1776,7 +1786,9 @@ Division.call(14, 0)
 #<BCDD::Result::Context::Failure type=:division_by_zero value={:message=>"arg2 must not be zero"}>
 ```
 
-### `BCDD::Result.transitions`
+<p align="right"><a href="#-bcddresult">⬆️ &nbsp;back to top</a></p>
+
+## `BCDD::Result.transitions`
 
 Use `BCDD::Result.transitions(&block)` to track all transitions in the same or between different operations (it works with `BCDD::Result` and `BCDD::Result::Context`). 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.
 
@@ -1797,7 +1809,7 @@ class Division
 
   private
 
-  ValidNumber = ->(arg) { arg.is_a?(Numeric) && arg != Float::NAN && arg != Float::INFINITY }
+  ValidNumber = ->(arg) { arg.is_a?(Numeric) && (!arg.respond_to?(:finite?) || arg.finite?) }
 
   def require_numbers((arg1, arg2))
     ValidNumber[arg1] or return Failure(:invalid_arg, 'arg1 must be a valid number')
@@ -1844,83 +1856,85 @@ result = SumDivisionsByTwo.call(20, 10)
 
 result.transitions
 {
-  :version =>1,
+  :version => 1,
   :metadata => {
-    :duration => 0,                       # milliseconds
-    :tree_map => [0, [[1, []], [2, []]]], # represents the tree of transitions using the id of each transition block
+    :duration => 0,   # milliseconds
+    :trace_id => nil, # can be set through configuration
+    :ids_tree => [0, [[1, []], [2, []]]],
+    :ids_matrix => {0 => [0, 0], 1 => [1, 1], 2 => [2, 1]}
   },
-  :records => [
+  :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=>:given, :value=>[20, 2]},
-      :and_then=>{},
-      :time=>2024-01-02 03:35:11.248418 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=>:_given_, :value=>[20, 2], :source=><Division:0x0000000102fd7ed0>},
+      :and_then => {},
+      :time => 2024-01-26 02:53:11.310346 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:0x0000000106099028>, :method_name=>:require_numbers},
-      :time=>2024-01-02 03:35:11.248558 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=>:_continue_, :value=>[20, 2], :source=><Division:0x0000000102fd7ed0>},
+      :and_then => {:type=>:method, :arg=>nil, :method_name=>:require_numbers},
+      :time => 2024-01-26 02:53:11.310392 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:0x0000000106099028>, :method_name=>:check_for_zeros},
-      :time=>2024-01-02 03:35:11.248587 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=>:_continue_, :value=>[20, 2], :source=><Division:0x0000000102fd7ed0>},
+      :and_then => {:type=>:method, :arg=>nil, :method_name=>:check_for_zeros},
+      :time=>2024-01-26 02:53:11.310403 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:0x0000000106099028>, :method_name=>:divide},
-      :time=>2024-01-02 03:35:11.248607 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, :source=><Division:0x0000000102fd7ed0>},
+      :and_then => {:type=>:method, :arg=>nil, :method_name=>:divide},
+      :time => 2024-01-26 02:53:11.310409 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=>:given, :value=>[10, 2]},
-      :and_then=>{},
-      :time=>2024-01-02 03:35:11.24865 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=>:_given_, :value=>[10, 2], :source=><Division:0x0000000102fd6378>},
+      :and_then => {},
+      :time => 2024-01-26 02:53:11.310424 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:0x0000000106097ed0>, :method_name=>:require_numbers},
-      :time=>2024-01-02 03:35:11.248661 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=>:_continue_, :value=>[10, 2], :source=><Division:0x0000000102fd6378>},
+      :and_then => {:type=>:method, :arg=>nil, :method_name=>:require_numbers},
+      :time => 2024-01-26 02:53:11.310428 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:0x0000000106097ed0>, :method_name=>:check_for_zeros},
-      :time=>2024-01-02 03:35:11.248672 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=>:_continue_, :value=>[10, 2], :source=><Division:0x0000000102fd6378>},
+      :and_then => {:type=>:method, :arg=>nil, :method_name=>:check_for_zeros},
+      :time => 2024-01-26 02:53:11.310431 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:0x0000000106097ed0>, :method_name=>:divide},
-      :time=>2024-01-02 03:35:11.248682 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, :source=><Division:0x0000000102fd6378>},
+      :and_then => {:type=>:method, :arg=>nil, :method_name=>:divide},
+      :time => 2024-01-26 02:53:11.310434 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=>2024-01-02 03:35:11.248721 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, :source=>SumDivisionsByTwo},
+      :and_then => {},
+      :time => 2024-01-26 02:53:11.310444 UTC
     }
   ]
 }
@@ -1928,7 +1942,46 @@ result.transitions
 
 <p align="right"><a href="#-bcddresult">⬆️ &nbsp;back to top</a></p>
 
-#### Configuration
+### `ids_tree` *versus* `ids_matrix`
+
+The `:ids_matrix`. It is a simplification of the `:ids_tree` property (a graph/tree representation of the transitions ids).
+
+The matrix rows are the direct transitions from the root transition block, and the columns are the transitions nested from the direct transitions.
+
+Use these data structures to build your own visualization of the transitions.
+
+> Check out [Transitions Listener example](examples/single_listener/lib/single_transitions_listener.rb) to see how a listener can be used to build a visualization of the transitions, using these properties.
+
+```ruby
+# ids_tree         #
+0                  # [0, [
+|- 1               #   [1, [[2, []]]],
+|  |- 2            #   [3, []],
+|- 3               #   [4, [
+|- 4               #     [5, []],
+|  |- 5            #     [6, [[7, []]]]
+|  |- 6            #   ]],
+|     |- 7         #   [8, []]
+|- 8               # ]]
+
+# ids_matrix       # {
+0 | 1 | 2 | 3 | 4  #   0 => [0, 0],
+- | - | - | - | -  #   1 => [1, 1],
+0 |   |   |   |    #   2 => [1, 2],
+1 | 1 | 2 |   |    #   3 => [2, 1],
+2 | 3 |   |   |    #   4 => [3, 1],
+3 | 4 | 5 | 6 | 7  #   5 => [3, 2],
+4 | 8 |   |   |    #   6 => [3, 3],
+                   #   7 => [3, 4],
+                   #   8 => [4, 1]
+                   # }
+```
+
+<p align="right"><a href="#-bcddresult">⬆️ &nbsp;back to top</a></p>
+
+### Configuration
+
+#### Turning on/off
 
 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.
 
@@ -1942,15 +1995,179 @@ result = SumDivisionsByTwo.call(20, 10)
 
 result.transitions
 
-{:version=>1, :records=>[], :metadata=>{:duration=>0, :tree_map=>[]}}
+{:version=>1, :records=>[], :metadata=>{:duration=>0, :ids_tree=>[]}}
+```
+
+<p align="right"><a href="#-bcddresult">⬆️ &nbsp;back to top</a></p>
+
+#### Setting a `trace_id` fetcher
+
+You can define a lambda (arity 0) to fetch the trace_id. This lambda will be called before the first transition and will be used to set the `:trace_id` in the `:metadata` property.
+
+Use to correlate different or the same operation (executed multiple times).
+
+```ruby
+BCDD::Result.config.transitions.trace_id = -> { Thread.current[:bcdd_result_transitions_trace_id] }
+```
+
+<p align="right"><a href="#-bcddresult">⬆️ &nbsp;back to top</a></p>
+
+#### Setting a `listener`
+
+You can define a listener to be called during the result transitions tracking (check out [this example](examples/single_listener/lib/single_transitions_listener.rb)). It must be a class that includes `BCDD::Result::Transitions::Listener`.
+
+Use it to build your additional logic on top of the transitions tracking. Examples:
+  - Log the transitions.
+  - Perform a trace of the transitions.
+  - Instrument the transitions (measure/report).
+  - Build a visualization of the transitions (Diagrams, using the `records` + `:ids_tree` and `:ids_matrix` properties).
+
+After implementing your listener, you can set it to the `BCDD::Result.config.transitions.listener=`:
+
+```ruby
+BCDD::Result.config.transitions.listener = MyTransitionsListener
+```
+
+See the example below to understand how to implement one:
+
+```ruby
+class MyTransitionsListener
+  include BCDD::Result::Transitions::Listener
+
+  # A listener will be initialized before the first transition, and it is discarded after the last one.
+  def initialize
+  end
+
+  # This method will be called before each transition block.
+  # The parent transition block will be called first in the case of nested transition blocks.
+  #
+  # @param scope: {:id=>1, :name=>"SomeOperation", :desc=>"Optional description"}
+  def on_start(scope:)
+  end
+
+  # This method will wrap all the transitions in the same block.
+  # It can be used to perform an instrumentation (measure/report) of the transitions.
+  #
+  # @param scope: {:id=>1, :name=>"SomeOperation", :desc=>"Optional description"}
+  def around_transitions(scope:)
+    yield
+  end
+
+  # This method will wrap each and_then call.
+  # It can be used to perform an instrumentation (measure/report) of the and_then calls.
+  #
+  # @param scope: {:id=>1, :name=>"SomeOperation", :desc=>"Optional description"}
+  # @param and_then:
+  #  {:type=>:block, :arg=>:some_injected_value}
+  #  {:type=>:method, :arg=>:some_injected_value, :method_name=>:some_method_name}
+  def around_and_then(scope:, and_then:)
+    yield
+  end
+
+  # This method will be called after each result recording/tracking.
+  #
+  # @param record:
+  # {
+  #   :root => {:id=>0, :name=>"RootOperation", :desc=>nil},
+  #   :parent => {:id=>0, :name=>"RootOperation", :desc=>nil},
+  #   :current => {:id=>1, :name=>"SomeOperation", :desc=>nil},
+  #   :result => {:kind=>:success, :type=>:_continue_, :value=>{some: :thing}, :source=><MyProcess:0x0000000102fd6378>},
+  #   :and_then => {:type=>:method, :arg=>nil, :method_name=>:some_method},
+  #   :time => 2024-01-26 02:53:11.310431 UTC
+  # }
+  def on_record(record:)
+  end
+
+  # This method will be called at the end of the transitions tracking.
+  #
+  # @param transitions:
+  # {
+  #   :version => 1,
+  #   :metadata => {
+  #     :duration => 0,
+  #     :trace_id => nil,
+  #     :ids_tree => [0, [[1, []], [2, []]]],
+  #     :ids_matrix => {0 => [0, 0], 1 => [1, 1], 2 => [2, 1]}
+  #   },
+  #   :records => [
+  #     # ...
+  #   ]
+  # }
+  def on_finish(transitions:)
+  end
+
+  # This method will be called when an exception is raised during the transitions tracking.
+  #
+  # @param exception: Exception
+  # @param transitions: Hash
+  def before_interruption(exception:, transitions:)
+  end
+end
+```
+
+<p align="right"><a href="#-bcddresult">⬆️ &nbsp;back to top</a></p>
+
+#### Setting multiple `listeners`
+
+You can use `BCDD::Result::Transitions::Listeners[]` to creates a listener of listeners (check out [this example](examples/multiple_listeners/Rakefile)), which will be called in the order they were added.
+
+**Attention:** It only allows one listener to handle `around_and_then` and another `around_transitions` events.
+
+> The example below defines different listeners to handle `around_and_then` and `around_transitions,` but it is also possible to define a listener to handle both.
+
+```ruby
+class AroundAndThenListener
+  include BCDD::Result::Transitions::Listener
+
+  # It must be a static/singleton method.
+  def self.around_and_then?
+    true
+  end
+
+  def around_and_then(scope:, and_then:)
+    #...
+  end
+end
+
+class AroundTransitionsListener
+  include BCDD::Result::Transitions::Listener
+
+  # It must be a static/singleton method.
+  def self.around_transitions?
+    true
+  end
+
+  def around_transitions(scope:)
+    #...
+  end
+end
+
+class MyTransitionsListener
+  include BCDD::Result::Transitions::Listener
+end
+```
+
+How to use it:
+
+```ruby
+# The listeners will be called in the order they were added.
+BCDD::Result.config.transitions.listener = BCDD::Result::Transitions::Listeners[
+  MyTransitionsListener,
+  AroundAndThenListener,
+  AroundTransitionsListener
+]
 ```
 
+> Check out [this example](examples/multiple_listeners) to see a listener to print the transitions and another to store them in the database.
+
 <p align="right"><a href="#-bcddresult">⬆️ &nbsp;back to top</a></p>
 
-### `BCDD::Result.configuration`
+## `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.
 
+> Note: You can use `BCDD::Result.configuration(freeze: false) {}` to avoid the freezing. This can be useful in tests. Please be sure to use it with caution.
+
 ```ruby
 BCDD::Result.configuration do |config|
   config.addon.enable!(:given, :continue)
@@ -1967,13 +2184,13 @@ Use `disable!` to disable a feature and `enable!` to enable it.
 
 Let's see what each configuration in the example above does:
 
-#### `config.addon.enable!(:given, :continue)`
+### `config.addon.enable!(:given, :continue)` <!-- omit in toc -->
 
 This configuration enables the `Continue()` method for `BCDD::Result.mixin`, `BCDD::Result::Context.mixin`, `BCDD::Result::Expectation.mixin`, and `BCDD::Result::Context::Expectation.mixin`. Link to documentations: [(1)](#add-ons) [(2)](#mixin-add-ons).
 
 It is also enabling the `Given()` which is already enabled by default. Link to documentation: [(1)](#add-ons) [(2)](#mixin-add-ons).
 
-#### `config.constant_alias.enable!('Result', 'BCDD::Context')`
+### `config.constant_alias.enable!('Result', 'BCDD::Context')` <!-- omit in toc -->
 
 This configuration make `Result` a constant alias for `BCDD::Result`, and `BCDD::Context` a constant alias for `BCDD::Result::Context`.
 
@@ -1981,23 +2198,23 @@ Link to documentations:
 - [Result alias](#bcddresult-versus-result)
 - [Context aliases](#constant-aliases)
 
-#### `config.pattern_matching.disable!(:nil_as_valid_value_checking)`
+### `config.pattern_matching.disable!(:nil_as_valid_value_checking)` <!-- omit in toc -->
 
 This configuration disables the `nil_as_valid_value_checking` for `BCDD::Result` and `BCDD::Result::Context`. Link to [documentation](#pattern-matching-support).
 
-<p align="right"><a href="#-bcddresult">⬆️ &nbsp;back to top</a></p>
-
-#### `config.feature.disable!(:expectations)`
+### `config.feature.disable!(:expectations)` <!-- omit in toc -->
 
 This configuration turns off the expectations for `BCDD::Result` and `BCDD::Result::Context`. The expectations are helpful in development and test environments, but they can be disabled in production environments for performance gain.
 
 PS: I'm using `::Rails.env.production?` to check the environment, but you can use any logic you want.
 
+<p align="right"><a href="#-bcddresult">⬆️ &nbsp;back to top</a></p>
+
 ### `BCDD::Result.config`
 
 The `BCDD::Result.config` allows you to access the current configuration.
 
-**BCDD::Result.config.addon**
+#### **BCDD::Result.config.addon** <!-- omit in toc -->
 
 ```ruby
 BCDD::Result.config.addon.enabled?(:continue)
@@ -2026,7 +2243,7 @@ BCDD::Result.config.addon.options
 # }
 ```
 
-**BCDD::Result.config.constant_alias**
+#### **BCDD::Result.config.constant_alias** <!-- omit in toc -->
 
 ```ruby
 BCDD::Result.config.constant_alias.enabled?('Result')
@@ -2041,7 +2258,7 @@ BCDD::Result.config.constant_alias.options
 # }
 ```
 
-**BCDD::Result.config.pattern_matching**
+#### **BCDD::Result.config.pattern_matching** <!-- omit in toc -->
 
 ```ruby
 BCDD::Result.config.pattern_matching.enabled?(:nil_as_valid_value_checking)
@@ -2058,7 +2275,7 @@ BCDD::Result.config.pattern_matching.options
 # }
 ```
 
-**BCDD::Result.config.feature**
+#### **BCDD::Result.config.feature** <!-- omit in toc -->
 
 ```ruby
 BCDD::Result.config.feature.enabled?(:expectations)
@@ -2078,13 +2295,209 @@ BCDD::Result.config.feature.options
 #       "BCDD::Result",
 #       "BCDD::Result::Context"
 #     ]
-#   }
+#   },
+#   :and_then!=>{
+#     :enabled=>false,
+#     :affects=>[
+#       "BCDD::Result",
+#       "BCDD::Result::Context"
+#     ]
+#   },
 # }
 ```
 
+<p align="right"><a href="#-bcddresult">⬆️ &nbsp;back to top</a></p>
+
+## `BCDD::Result#and_then!`
+
+In the Ruby ecosystem, several gems facilitate operation composition using classes and modules. Two notable examples are the `interactor` gem and the `u-case` gem.
+
+**`interactor` gem example**
+
+```ruby
+class PlaceOrder
+  include Interactor::Organizer
+
+  organize CreateOrder,
+           PayOrder,
+           SendOrderConfirmation,
+           NotifyAdmins
+end
+```
+
+**`u-case` gem example**
+
+```ruby
+class PlaceOrder < Micro::Case
+  flow CreateOrder, PayOrder, SendOrderConfirmation, NotifyAdmins
+end
+
+# Alternative approach
+class PlaceOrder < Micro::Case
+  def call!
+    call(CreateOrder)
+      .then(PayOrder)
+      .then(SendOrderConfirmation)
+      .then(NotifyAdmins)
+  end
+end
+```
+
+To facilitate migration for users accustomed to the above approaches, `bcdd-result` includes the `BCDD::Result#and_then!`/`BCDD::Result::Context#and_then!` methods, which will invoke the method `call` of the given operation and expect it to return a `BCDD::Result`/`BCDD::Result::Context` object.
+
+```ruby
+BCDD::Result.configure do |config|
+  config.feature.enable!(:and_then!)
+end
+
+class PlaceOrder
+  include BCDD::Result::Context.mixin
+
+  def call(**input)
+    Given(input)
+      .and_then!(CreateOrder.new)
+      .and_then!(PayOrder.new)
+      .and_then!(SendOrderConfirmation.new)
+      .and_then!(NotifyAdmins.new)
+  end
+end
+```
+
+<p align="right"><a href="#-bcddresult">⬆️ &nbsp;back to top</a></p>
+
+#### Dependency Injection
+
+Like `#and_then`, `#and_then!` also supports an additional argument for dependency injection.
+
+**In BCDD::Result**
+
+```ruby
+class PlaceOrder
+  include BCDD::Result.mixin
+
+  def call(input, logger:)
+    Given(input)
+      .and_then!(CreateOrder.new, logger)
+      # Further method chaining...
+  end
+end
+```
+
+**In BCDD::Result::Context**
+
+```ruby
+class PlaceOrder
+  include BCDD::Result::Context.mixin
+
+  def call(logger:, **input)
+    Given(input)
+      .and_then!(CreateOrder.new, logger:)
+      # Further method chaining...
+  end
+end
+```
+
+<p align="right"><a href="#-bcddresult">⬆️ &nbsp;back to top</a></p>
+
+#### Configuration
+
+```ruby
+BCDD::Result.configure do |config|
+  config.feature.enable!(:and_then!)
+
+  config.and_then!.default_method_name_to_call = :perform
+end
+```
+
+**Explanation:**
+
+- `enable!(:and_then!)`: Activates the `and_then!` feature.
+
+- `default_method_name_to_call`: Sets a default method other than `:call` for `and_then!`.
+
+<p align="right"><a href="#-bcddresult">⬆️ &nbsp;back to top</a></p>
+
+#### Analysis: Why is `and_then!` an Anti-pattern?
+
+The `and_then!` approach, despite its brevity, introduces several issues:
+
+- **Lack of Clarity:** The input/output relationship between the steps is not apparent.
+
+- **Steps Coupling:** Each operation becomes interdependent (high coupling), complicating implementation and compromising the reusability of these operations.
+
+We recommend cautious use of `#and_then!`. Due to these issues, it is turned off by default and considered an antipattern.
+
+It should be a temporary solution, primarily for assisting in migration from another to gem to `bcdd-result`.
+
+<p align="right"><a href="#-bcddresult">⬆️ &nbsp;back to top</a></p>
+
+#### `#and_then` versus `#and_then!`
+
+The main difference between the `#and_then` and `#and_then!` is that the latter does not check the result source. However, as a drawback, the result source will change.
+
+Attention: to ensure the correct behavior, do not mix `#and_then` and `#and_then!` in the same result chain.
+
+<p align="right"><a href="#-bcddresult">⬆️ &nbsp;back to top</a></p>
+
+#### Analysis: Why is `#and_then` the antidote/standard?
+
+The `BCDD::Result#and_then`/`BCDD::Result::Context#and_then` methods diverge from the above approach by requiring explicit invocation and mapping of the outcomes at each process step. This approach has the following advantages:
+
+- **Clarity:** The input/output relationship between the steps is apparent and highly understandable.
+
+- **Steps uncoupling:** Each operation becomes independent (low coupling). You can even map a failure result to a success (and vice versa).
+
+See this example to understand what your code should look like:
+
+```ruby
+class PlaceOrder
+  include BCDD::Result::Context.mixin(config: { addon: { continue: true } })
+
+  def call(**input)
+    Given(input)
+      .and_then(:create_order)
+      .and_then(:pay_order)
+      .and_then(:send_order_confirmation)
+      .and_then(:notify_admins)
+      .and_expose(:order_placed, %i[order])
+  end
+
+  private
+
+  def create_order(customer:, products:)
+    CreateOrder.new.call(customer:, products:).handle do |on|
+      on.success { |output| Continue(order: output[:order]) }
+      on.failure { |error| Failure(:order_creation_failed, error:) }
+    end
+  end
+
+  def pay_order(customer:, order:, payment_method:, **)
+    PayOrder.new.call(customer:, payment_method:, order:).handle do |on|
+      on.success { |output| Continue(payment: output[:payment]) }
+      on.failure { |error| Failure(:order_payment_failed, error:) }
+    end
+  end
+
+  def send_order_confirmation(customer:, order:, payment:, **)
+    SendOrderConfirmation.new.call(customer:, order:, payment:).handle do |on|
+      on.success { Continue() }
+      on.failure { |error| Failure(:order_confirmation_failed, error:) }
+    end
+  end
+
+  def notify_admins(customer:, order:, payment:, **)
+    NotifyAdmins.new.call(customer:, order:, payment:)
+
+    Continue()
+  end
+end
+```
+
+<p align="right"><a href="#-bcddresult">⬆️ &nbsp;back to top</a></p>
+
 ## About
 
-[Rodrigo Serradura](https://github.com/serradura) created this project. He is the B/CDD process/method creator and has already made similar gems like the [u-case](https://github.com/serradura/u-case) and [kind](https://github.com/serradura/kind/blob/main/lib/kind/result.rb). This gem is a general-purpose abstraction/monad, but it also contains key features that serve as facilitators for adopting B/CDD in the code.
+[Rodrigo Serradura](https://github.com/serradura) created this project. He is the B/CDD process/method creator and has already made similar gems like the [u-case](https://github.com/serradura/u-case) and [kind](https://github.com/serradura/kind/blob/main/lib/kind/result.rb). This gem can be used independently, but it also contains essential features that facilitate the adoption of B/CDD in code.
 
 <p align="right"><a href="#-bcddresult">⬆️ &nbsp;back to top</a></p>