bcdd-result 0.10.0 → 0.12.0

data/README.md

@@ -73,11 +73,17 @@ Use it to enable the [Railway Oriented Programming](https://fsharpforfunandprofi
   - [`BCDD::Result.transitions`](#bcddresulttransitions)
     - [Configuration](#configuration)
   - [`BCDD::Result.configuration`](#bcddresultconfiguration)
-    - [`config.addon.enable!(:continue)`](#configaddonenablecontinue)
+    - [`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.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 +655,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 +752,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 +800,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 +838,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 +865,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'
@@ -918,35 +925,48 @@ Divide.call(4, 2, logger: Logger.new(IO::NULL))
 
 The `BCDD::Result.mixin` also accepts the `config:` argument. It is a hash that will be used to define custom behaviors for the mixin.
 
+**given**
+
+This addon is enabled by default. It will create the `Given(value)` method. Use it to add a value to the result chain and invoke the next step (through `and_then`).
+
+You can turn it off by passing `given: false` to the `config:` argument or using the `BCDD::Result.configuration`.
+
 **continue**
 
-This addon will create the `Continue(value)` method and change the `Success()` behavior to halt the step chain.
+This addon will create the `Continue(value)` method and change the `Success()` behavior to terminate the step chain.
 
-So, if you want to advance to the next step, you must use `Continue(value)` instead of `Success(type, value)`. Otherwise, the step chain will be halted.
+So, if you want to advance to the next step, you must use `Continue(value)` instead of `Success(type, value)`. Otherwise, the step chain will be terminated.
+
+In this example below, the `validate_nonzero` will return a `Success(:division_completed, 0)` and terminate the chain if the first number is zero.
 
 ```ruby
 module Divide
   extend self, BCDD::Result.mixin(config: { addon: { continue: true } })
 
   def call(arg1, arg2)
-    validate_numbers(arg1, arg2)
+    Given([arg1, arg2])
+      .and_then(:validate_numbers)
       .and_then(:validate_nonzero)
       .and_then(:divide)
   end
 
   private
 
-  def validate_numbers(arg1, arg2)
-    arg1.is_a?(::Numeric) or return Failure(:invalid_arg, 'arg1 must be numeric')
-    arg2.is_a?(::Numeric) or return Failure(:invalid_arg, 'arg2 must be numeric')
+  def validate_numbers(numbers)
+    number1, number2 = numbers
 
-    Continue([arg1, arg2])
+    number1.is_a?(::Numeric) or return Failure(:invalid_arg, 'arg1 must be numeric')
+    number2.is_a?(::Numeric) or return Failure(:invalid_arg, 'arg2 must be numeric')
+
+    Continue(numbers)
   end
 
   def validate_nonzero(numbers)
-    return Continue(numbers) unless numbers.last.zero?
+    return Failure(:division_by_zero, 'arg2 must not be zero') if numbers.last.zero?
 
-    Failure(:division_by_zero, 'arg2 must not be zero')
+    return Success(:division_completed, 0) if numbers.first.zero?
+
+    Continue(numbers)
   end
 
   def divide((number1, number2))
@@ -1571,7 +1591,7 @@ 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`.
+> PS: The `#and_expose` produces a terminal 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 `terminal: false` to `#and_expose`.
 
 <p align="right"><a href="#-bcddresult">⬆️ &nbsp;back to top</a></p>
 
@@ -1678,16 +1698,24 @@ Divide::Result::Success(:division_completed, number: '2')
 
 The `BCDD::Result::Context.mixin` and `BCDD::Result::Context::Expectations.mixin` also accepts the `config:` argument. And it works the same way as the `BCDD::Result` mixins.
 
-**Continue**
+**given**
+
+This addon is enabled by default. It will create the `Given(*value)` method. Use it to add a value to the result chain and invoke the next step (through `and_then`).
 
-The `BCDD::Result::Context.mixin(config: { addon: { continue: true } })` or `BCDD::Result::Context::Expectations.mixin(config: { addon: { continue: true } })` creates the `Continue(value)` method and change the `Success()` behavior to halt the step chain.
+You can turn it off by passing `given: false` to the `config:` argument or using the `BCDD::Result.configuration`.
 
-So, if you want to advance to the next step, you must use `Continue(**value)` instead of `Success(type, **value)`. Otherwise, the step chain will be halted.
+The `Given()` addon for a BCDD::Result::Context can be called with one or more arguments. The arguments will be converted to a hash (`to_h`) and merged to define the first value of the result chain.
+
+**continue**
+
+The `BCDD::Result::Context.mixin(config: { addon: { continue: true } })` or `BCDD::Result::Context::Expectations.mixin(config: { addon: { continue: true } })` creates the `Continue(value)` method and change the `Success()` behavior to terminate the step chain.
+
+So, if you want to advance to the next step, you must use `Continue(**value)` instead of `Success(type, **value)`. Otherwise, the step chain will be terminated.
 
 Let's use a mix of `BCDD::Result::Context` features to see in action with this add-on:
 
 ```ruby
-module Divide
+module Division
   require 'logger'
 
   extend self, BCDD::Result::Context::Expectations.mixin(
@@ -1705,25 +1733,28 @@ module Divide
   )
 
   def call(arg1, arg2, logger: ::Logger.new(STDOUT))
-    validate_numbers(arg1, arg2)
-      .and_then(:validate_nonzero)
+    Given(number1: arg1, number2: arg2)
+      .and_then(:require_numbers)
+      .and_then(:check_for_zeros)
       .and_then(:divide, logger: logger)
       .and_expose(:division_completed, [:number])
   end
 
   private
 
-  def validate_numbers(arg1, arg2)
-    arg1.is_a?(::Numeric) or return Failure(:invalid_arg, message: 'arg1 must be numeric')
-    arg2.is_a?(::Numeric) or return Failure(:invalid_arg, message: 'arg2 must be numeric')
+  def require_numbers(number1:, number2:)
+    number1.is_a?(::Numeric) or return Failure(:invalid_arg, message: 'arg1 must be numeric')
+    number2.is_a?(::Numeric) or return Failure(:invalid_arg, message: 'arg2 must be numeric')
 
-    Continue(number1: arg1, number2: arg2)
+    Continue()
   end
 
-  def validate_nonzero(number2:, **)
-    return Continue() if number2.nonzero?
+  def check_for_zeros(number1:, number2:)
+    return Failure(:division_by_zero, message: 'arg2 must not be zero') if number2.zero?
+
+    return Success(:division_completed, number: 0) if number1.zero?
 
-    Failure(:division_by_zero, message: 'arg2 must not be zero')
+    Continue()
   end
 
   def divide(number1:, number2:, logger:)
@@ -1735,23 +1766,26 @@ module Divide
   end
 end
 
-Divide.call(14, 2)
+Division.call(14, 2)
 # I, [2023-10-27T02:01:05.812388 #77823]  INFO -- : The division result is 7
 #<BCDD::Result::Context::Success type=:division_completed value={:number=>7}>
 
-Divide.call('14', 2)
+Division.call(0, 2)
+##<BCDD::Result::Context::Success type=:division_completed value={:number=>0}>
+
+Division.call('14', 2)
 #<BCDD::Result::Context::Failure type=:invalid_arg value={:message=>"arg1 must be numeric"}>
 
-Divide.call(14, '2')
+Division.call(14, '2')
 #<BCDD::Result::Context::Failure type=:invalid_arg value={:message=>"arg2 must be numeric"}>
 
-Divide.call(14, 0)
+Division.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.
+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.
 
 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.
 
@@ -1761,7 +1795,8 @@ class Division
 
   def call(arg1, arg2)
     BCDD::Result.transitions(name: 'Division', desc: 'divide two numbers') do
-      require_numbers(arg1, arg2)
+      Given([arg1, arg2])
+        .and_then(:require_numbers)
         .and_then(:check_for_zeros)
         .and_then(:divide)
     end
@@ -1771,7 +1806,7 @@ class Division
 
   ValidNumber = ->(arg) { arg.is_a?(Numeric) && arg != Float::NAN && arg != Float::INFINITY }
 
-  def require_numbers(arg1, arg2)
+  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')
 
@@ -1823,52 +1858,68 @@ result.transitions
   },
   :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=>: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=>:continued, :value=>[20, 2]},
+      :and_then=>{:type=>:method, :arg=>nil, :source=><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=>: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
+      :and_then=>{:type=>:method, :arg=>nil, :source=><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=>: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
+      :and_then=>{:type=>:method, :arg=>nil, :source=><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=>2, :name=>"Division", :desc=>"divide two numbers"},
-      :result=>{:kind=>:success, :type=>:continued, :value=>[10, 2]},
+      :result=>{:kind=>:success, :type=>:given, :value=>[10, 2]},
       :and_then=>{},
-      :time=>2023-12-31 22:19:33.281747 UTC
+      :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=>:continued, :value=>[10, 2]},
+      :and_then=>{:type=>:method, :arg=>nil, :source=><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=>: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
+      :and_then=>{:type=>:method, :arg=>nil, :source=><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=>: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
+      :and_then=>{:type=>:method, :arg=>nil, :source=><Division:0x0000000106097ed0>, :method_name=>:divide},
+      :time=>2024-01-02 03:35:11.248682 UTC
     },
     {
       :root=>{:id=>0, :name=>"SumDivisionsByTwo", :desc=>nil},
@@ -1876,7 +1927,7 @@ result.transitions
       :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
+      :time=>2024-01-02 03:35:11.248721 UTC
     }
   ]
 }
@@ -1909,7 +1960,7 @@ The `BCDD::Result.configuration` allows you to configure default behaviors for `
 
 ```ruby
 BCDD::Result.configuration do |config|
-  config.addon.enable!(:continue)
+  config.addon.enable!(:given, :continue)
 
   config.constant_alias.enable!('Result', 'BCDD::Context')
 
@@ -1923,9 +1974,11 @@ 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!(:continue)`
+#### `config.addon.enable!(:given, :continue)`
 
-This configuration enables the `Continue()` method for `BCDD::Result`, `BCDD::Result::Context`, `BCDD::Result::Expectation`, and `BCDD::Result::Context::Expectation`. Link to documentations: [(1)](#add-ons) [(2)](#mixin-add-ons).
+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')`
 
@@ -1955,16 +2008,26 @@ The `BCDD::Result.config` allows you to access the current configuration.
 
 ```ruby
 BCDD::Result.config.addon.enabled?(:continue)
+BCDD::Result.config.addon.enabled?(:given)
 
 BCDD::Result.config.addon.options
 # {
 #   :continue=>{
 #     :enabled=>false,
 #     :affects=>[
-#       "BCDD::Result",
-#       "BCDD::Result::Context",
-#       "BCDD::Result::Expectations",
-#       "BCDD::Result::Context::Expectations"
+#       "BCDD::Result.mixin",
+#       "BCDD::Result::Context.mixin",
+#       "BCDD::Result::Expectations.mixin",
+#       "BCDD::Result::Context::Expectations.mixin"
+#     ]
+#   },
+#   :given=>{
+#     :enabled=>true,
+#     :affects=>[
+#       "BCDD::Result.mixin",
+#       "BCDD::Result::Context.mixin",
+#       "BCDD::Result::Expectations.mixin",
+#       "BCDD::Result::Context::Expectations.mixin"
 #     ]
 #   }
 # }
@@ -2022,10 +2085,206 @@ 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.

data/Rakefile

@@ -3,16 +3,22 @@
 require 'bundler/gem_tasks'
 require 'rake/testtask'
 
+Rake::TestTask.new(:test) do |t|
+  t.libs += %w[lib test]
+
+  t.test_files = FileList.new('test/**/*_test.rb')
+end
+
 Rake::TestTask.new(:test_configuration) do |t|
   t.libs += %w[lib test]
 
   t.test_files = FileList.new('test/**/configuration_test.rb')
 end
 
-Rake::TestTask.new(:test) do |t|
+Rake::TestTask.new(:test_transitions_duration) do |t|
   t.libs += %w[lib test]
 
-  t.test_files = FileList.new('test/**/*_test.rb')
+  t.test_files = FileList.new('test/**/duration_test.rb')
 end
 
 require 'rubocop/rake_task'