bcdd-result 0.6.0 → 0.8.0

data/README.md

@@ -1,6 +1,6 @@
 <p align="center">
   <h1 align="center" id="-bcddresult">🔀 BCDD::Result</h1>
-  <p align="center"><i>Empower Ruby apps with a pragmatic use of Railway Oriented Programming.</i></p>
+  <p align="center"><i>Empower Ruby apps with pragmatic use of Result monad, Railway Oriented Programming, and B/CDD.</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>
@@ -23,7 +23,7 @@ Use it to enable the [Railway Oriented Programming](https://fsharpforfunandprofi
     - [`BCDD::Result` *versus* `Result`](#bcddresult-versus-result)
 - [Reference](#reference)
   - [Result Attributes](#result-attributes)
-    - [Receiving types in `result.success?` or `result.failure?`](#receiving-types-in-resultsuccess-or-resultfailure)
+    - [Checking types with `result.success?` or `result.failure?`](#checking-types-with-resultsuccess-or-resultfailure)
   - [Result Hooks](#result-hooks)
     - [`result.on`](#resulton)
     - [`result.on_type`](#resulton_type)
@@ -35,6 +35,9 @@ Use it to enable the [Railway Oriented Programming](https://fsharpforfunandprofi
     - [`result.value_or`](#resultvalue_or)
   - [Result Data](#result-data)
     - [`result.data`](#resultdata)
+  - [Pattern Matching](#pattern-matching)
+    - [`Array`/`Find` patterns](#arrayfind-patterns)
+    - [`Hash` patterns](#hash-patterns)
   - [Railway Oriented Programming](#railway-oriented-programming)
     - [`result.and_then`](#resultand_then)
     - [`BCDD::Result.mixin`](#bcddresultmixin)
@@ -42,12 +45,8 @@ Use it to enable the [Railway Oriented Programming](https://fsharpforfunandprofi
       - [Module example (Singleton Methods)](#module-example-singleton-methods)
       - [Important Requirement](#important-requirement)
       - [Dependency Injection](#dependency-injection)
-      - [Addons](#addons)
-  - [Pattern Matching](#pattern-matching)
-    - [`Array`/`Find` patterns](#arrayfind-patterns)
-    - [`Hash` patterns](#hash-patterns)
-    - [BCDD::Result::Expectations](#bcddresultexpectations)
-  - [`BCDD::Result::Expectations`](#bcddresultexpectations-1)
+      - [Add-ons](#add-ons)
+  - [`BCDD::Result::Expectations`](#bcddresultexpectations)
     - [Standalone *versus* Mixin mode](#standalone-versus-mixin-mode)
     - [Type checking - Result Hooks](#type-checking---result-hooks)
       - [`#success?` and `#failure?`](#success-and-failure)
@@ -60,7 +59,22 @@ Use it to enable the [Railway Oriented Programming](https://fsharpforfunandprofi
     - [Value checking - Result Creation](#value-checking---result-creation)
       - [Success()](#success)
       - [Failure()](#failure)
-    - [`BCDD::Result::Expectations.mixin` Addons](#bcddresultexpectationsmixin-addons)
+      - [Pattern Matching Support](#pattern-matching-support)
+    - [`BCDD::Result::Expectations.mixin` add-ons](#bcddresultexpectationsmixin-add-ons)
+  - [`BCDD::Result::Context`](#bcddresultcontext)
+    - [Defining successes and failures](#defining-successes-and-failures)
+    - [`BCDD::Result::Context.mixin`](#bcddresultcontextmixin)
+      - [Class example (Instance Methods)](#class-example-instance-methods-1)
+      - [`and_expose`](#and_expose)
+      - [Module example (Singleton Methods)](#module-example-singleton-methods-1)
+    - [`BCDD::Result::Context::Expectations`](#bcddresultcontextexpectations)
+    - [Mixin add-ons](#mixin-add-ons)
+  - [`BCDD::Result.configuration`](#bcddresultconfiguration)
+    - [`config.addon.enable!(:continue)`](#configaddonenablecontinue)
+    - [`config.constant_alias.enable!('Result')`](#configconstant_aliasenableresult)
+    - [`config.pattern_matching.disable!(:nil_as_valid_value_checking)`](#configpattern_matchingdisablenil_as_valid_value_checking)
+    - [`config.feature.disable!(:expectations)`](#configfeaturedisableexpectations)
+  - [`BCDD::Result.config`](#bcddresultconfig)
 - [About](#about)
 - [Development](#development)
 - [Contributing](#contributing)
@@ -76,7 +90,7 @@ Use it to enable the [Railway Oriented Programming](https://fsharpforfunandprofi
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'bcdd-result', require: 'bcdd/result'
+gem 'bcdd-result'
 ```
 
 And then execute:
@@ -87,6 +101,10 @@ If bundler is not being used to manage dependencies, install the gem by executin
 
     $ gem install bcdd-result
 
+And require it in your code:
+
+    require 'bcdd/result'
+
 <p align="right"><a href="#-bcddresult">⬆️ &nbsp;back to top</a></p>
 
 ## Usage
@@ -111,17 +129,27 @@ BCDD::Result::Failure(:err) #
 
 #### `BCDD::Result` *versus* `Result`
 
-The `BCDD::Result` is the main module of this gem. It contains all the features, constants, and methods you will use to create and manipulate results.
+This gem provides a way to create constant aliases for `BCDD::Result` and other classes/modules.
 
-The `Result` is an alias of `BCDD::Result`. It was created to facilitate the use of this gem in the code. So, instead of requiring `BCDD::Result` everywhere, you can require `Result` and use it as an alias.
+To enable it, you must call the `BCDD::Result.configuration` method and pass a block to it. You can turn the aliases you want on/off in this block.
 
 ```ruby
-require 'result'
+BCDD::Result.configuration do |config|
+  config.constant_alias.enable!('Result')
+end
+```
 
+So, instead of using `BCDD::Result` everywhere, you can use `Result` as an alias/shortcut.
+
+```ruby
 Result::Success(:ok) # <BCDD::Result::Success type=:ok value=nil>
+
+Result::Failure(:err) # <BCDD::Result::Failure type=:err value=nil>
 ```
 
-All the examples in this README that use `BCDD::Result` can also be used with `Result`.
+If you have enabled constant aliasing, all examples in this README that use `BCDD::Result` can be implemented using `Result`.
+
+There are other aliases and configurations available. Check the [BCDD::Result.configuration]() section for more information.
 
 <p align="right"><a href="#-bcddresult">⬆️ &nbsp;back to top</a></p>
 
@@ -161,12 +189,12 @@ result.value    # nil
 ################
 # With a value #
 ################
-result = BCDD::Result::Failure(:err, my: 'value')
+result = BCDD::Result::Failure(:err, 'my_value')
 
 result.success? # false
 result.failure? # true
 result.type     # :err
-result.value    # {:my => "value"}
+result.value    # "my_value"
 
 ###################
 # Without a value #
@@ -179,9 +207,11 @@ result.type     # :no
 result.value    # nil
 ```
 
+In both cases, the `type` must be a symbol, and the `value` can be any kind of object.
+
 <p align="right"><a href="#-bcddresult">⬆️ &nbsp;back to top</a></p>
 
-#### Receiving types in `result.success?` or `result.failure?`
+#### Checking types with `result.success?` or `result.failure?`
 
 `BCDD::Result#success?` and `BCDD::Result#failure?` are methods that allow you to check if the result is a success or a failure.
 
@@ -190,9 +220,11 @@ You can also check the result type by passing an argument to it. For example, `r
 ```ruby
 result = BCDD::Result::Success(:ok)
 
-result.success?        # true
-result.success?(:ok)   # true
-result.success?(:okay) # false
+result.success?(:ok)
+
+# This is the same as:
+
+result.success? && result.type == :ok
 ```
 
 The same is valid for `BCDD::Result#failure?`.
@@ -200,18 +232,19 @@ The same is valid for `BCDD::Result#failure?`.
 ```ruby
 result = BCDD::Result::Failure(:err)
 
-result.failure?         # true
-result.failure?(:err)   # true
-result.failure?(:error) # false
+result.failure?(:err)
+
+# This is the same as:
+
+result.failure? && result.type == :err
 ```
 
 <p align="right"><a href="#-bcddresult">⬆️ &nbsp;back to top</a></p>
 
 ### Result Hooks
 
-Result hooks are methods that allow you to perform a block of code depending on the result type.
-
-To exemplify the them, I will implement a method that knows how to divide two numbers.
+Result hooks are methods that allow you to execute a block of code based on the type of result obtained.
+To demonstrate their use, I will implement a method that can divide two numbers.
 
 ```ruby
 def divide(arg1, arg2)
@@ -228,14 +261,15 @@ end
 
 #### `result.on`
 
-`BCDD::Result#on` will perform the block when the type matches the result type.
+When you use `BCDD::Result#on`, the block will be executed only when the type matches the result type.
 
-Regardless of the block being executed, the return of the method will always be the result itself.
+However, even if the block is executed, the method will always return the result itself.
 
-The result value will be exposed as the first argument of the block.
+The value of the result will be available as the first argument of the block.
 
 ```ruby
 result = divide(nil, 2)
+#<BCDD::Result::Failure type=:invalid_arg data='arg1 must be numeric'>
 
 output =
   result
@@ -268,24 +302,44 @@ result.object_id == output.object_id # true
 
 `BCDD::Result#on_type` is an alias of `BCDD::Result#on`.
 
+```ruby
+result = divide(nil, 2)
+#<BCDD::Result::Failure type=:invalid_arg data='arg1 must be numeric'>
+
+output =
+  result
+    .on_type(:invalid_arg, :division_by_zero) { |msg| puts msg }
+    .on_type(:division_completed) { |number| puts number }
+
+# The code above will print 'arg1 must be numeric' and return the result itself.
+
+result.object_id == output.object_id # true
+```
+
+*PS: The `divide()` implementation is [here](#result-hooks).*
+
+<p align="right"><a href="#-bcddresult">⬆️ &nbsp;back to top</a></p>
+
 #### `result.on_success`
 
-`BCDD::Result#on_success` is very similar to the `BCDD::Result#on` hook. The main differences are:
+The `BCDD::Result#on_success` method is quite similar to the `BCDD::Result#on` hook, but with a few key differences:
 
-1. Only perform the block when the result is a success.
-2. If the type is missing it will perform the block for any success.
+1. It will only execute the block of code if the result is a success.
+2. If the type declaration is not included, the method will execute the block for any successful result, regardless of its type.
 
 ```ruby
-# It performs the block and return itself.
+# In both examples, it executes the block and returns the result itself.
 
 divide(4, 2).on_success { |number| puts number }
 
 divide(4, 2).on_success(:division_completed) { |number| puts number }
 
-# It doesn't perform the block, but return itself.
+# It doesn't execute the block as the type is different.
 
 divide(4, 4).on_success(:ok) { |value| puts value }
 
+# It doesn't execute the block, as the result is a success, but the hook expects a failure.
+
 divide(4, 4).on_failure { |error| puts error }
 ```
 
@@ -295,20 +349,25 @@ divide(4, 4).on_failure { |error| puts error }
 
 #### `result.on_failure`
 
-Is the opposite of `Result#on_success`.
+It is the opposite of `Result#on_success`:
+
+1. It will only execute the block of code if the result is a failure.
+2. If the type declaration is not included, the method will execute the block for any failed result, regardless of its type.
 
 ```ruby
-# It performs the block and return itself.
+# In both examples, it executes the block and returns the result itself.
 
 divide(nil, 2).on_failure { |error| puts error }
 
-divide(4, 0).on_failure(:invalid_arg, :division_by_zero) { |error| puts error }
+divide(4, 0).on_failure(:division_by_zero) { |error| puts error }
 
-# It doesn't perform the block, but return itself.
-
-divide(4, 0).on_success { |number| puts number }
+# It doesn't execute the block as the type is different.
 
 divide(4, 0).on_failure(:invalid_arg) { |error| puts error }
+
+# It doesn't execute the block, as the result is a failure, but the hook expects a success.
+
+divide(4, 0).on_success { |number| puts number }
 ```
 
 *PS: The `divide()` implementation is [here](#result-hooks).*
@@ -317,11 +376,11 @@ divide(4, 0).on_failure(:invalid_arg) { |error| puts error }
 
 #### `result.on_unknown`
 
-`BCDD::Result#on_unknown` will perform the block when no other hook (`#on`, `#on_type`, `#on_failure`, `#on_success`) has been executed.
+`BCDD::Result#on_unknown` will execute the block when no other hook (`#on`, `#on_type`, `#on_failure`, `#on_success`) has been executed.
 
-Regardless of the block being executed, the return of the method will always be the result itself.
+Regardless of the block being executed, the method will always return the result itself.
 
-The result value will be exposed as the first argument of the block.
+The value of the result will be available as the first argument of the block.
 
 ```ruby
 divide(4, 2)
@@ -338,7 +397,7 @@ divide(4, 2)
 
 #### `result.handle`
 
-This method will allow you to define blocks for each hook (type, failure, success), but instead of returning itself, it will return the output of the first match/block execution.
+This method lets you define blocks for each hook (type, failure, or success), but instead of returning itself, it will return the output of the first match/block execution.
 
 ```ruby
 divide(4, 2).handle do |result|
@@ -379,8 +438,8 @@ end
 
 **Notes:**
 * You can define multiple types to be handled by the same hook/block
-* If the type is missing, it will perform the block for any success or failure handler.
-* The `#type` and `#[]` handlers will require at least one type/argument.
+* If the type is missing, it will execute the block for any success or failure handler.
+* The `#type` and `#[]` handlers require at least one type/argument.
 
 *PS: The `divide()` implementation is [here](#result-hooks).*
 
@@ -388,13 +447,13 @@ end
 
 ### Result Value
 
-The most simple way to get the result value is by calling `BCDD::Result#value`.
+To access the result value, you can simply call `BCDD::Result#value`.
 
-But sometimes you need to get the value of a successful result or a default value if it is a failure. In this case, you can use `BCDD::Result#value_or`.
+However, there may be instances where you need to retrieve the value of a successful result or a default value if the result is a failure. In such cases, you can make use of `BCDD::Result#value_or`.
 
 #### `result.value_or`
 
-`BCCD::Result#value_or` returns the value when the result is a success, but if is a failure the block will be performed, and its outcome will be the output.
+`BCCD::Result#value_or` returns the value when the result is a success. However, if it is a failure, the given block will be executed, and its outcome will be returned.
 
 ```ruby
 def divide(arg1, arg2)
@@ -462,16 +521,75 @@ print_to_hash(**success_data) # [:success, :ok, 1]
 
 <p align="right"><a href="#-bcddresult">⬆️ &nbsp;back to top</a></p>
 
-### Railway Oriented Programming
+### Pattern Matching
+
+The `BCDD::Result` also provides support to pattern matching.
+
+In the further examples, I will use the `Divide` lambda to exemplify its usage.
+
+```ruby
+Divide = lambda do |arg1, arg2|
+  arg1.is_a?(::Numeric) or return BCDD::Result::Failure(:invalid_arg, 'arg1 must be numeric')
+  arg2.is_a?(::Numeric) or return BCDD::Result::Failure(:invalid_arg, 'arg2 must be numeric')
+
+  return BCDD::Result::Failure(:division_by_zero, 'arg2 must not be zero') if arg2.zero?
+
+  BCDD::Result::Success(:division_completed, arg1 / arg2)
+end
+```
+
+#### `Array`/`Find` patterns
 
-This feature/pattern is also known as ["Railway Oriented Programming"](https://fsharpforfunandprofit.com/rop/).
+```ruby
+case Divide.call(4, 2)
+in BCDD::Result::Failure[:invalid_arg, msg] then puts msg
+in BCDD::Result::Failure[:division_by_zero, msg] then puts msg
+in BCDD::Result::Success[:division_completed, value] then puts value
+end
+
+# The code above will print: 2
+
+case Divide.call(4, 0)
+in BCDD::Result::Failure[:invalid_arg, msg] then puts msg
+in BCDD::Result::Failure[:division_by_zero, msg] then puts msg
+in BCDD::Result::Success[:division_completed, value] then puts value
+end
+
+# The code above will print: arg2 must not be zero
+```
+
+<p align="right"><a href="#-bcddresult">⬆️ &nbsp;back to top</a></p>
+
+#### `Hash` patterns
+
+```ruby
+case Divide.call(10, 2)
+in { failure: { invalid_arg: msg } } then puts msg
+in { failure: { division_by_zero: msg } } then puts msg
+in { success: { division_completed: value } } then puts value
+end
+
+# The code above will print: 5
+
+case Divide.call('10', 2)
+in { failure: { invalid_arg: msg } } then puts msg
+in { failure: { division_by_zero: msg } } then puts msg
+in { success: { division_completed: value } } then puts value
+end
+
+# The code above will print: arg1 must be numeric
+```
+
+<p align="right"><a href="#-bcddresult">⬆️ &nbsp;back to top</a></p>
+
+### Railway Oriented Programming
 
-The idea is to chain blocks and creates a pipeline of operations that can be interrupted by a failure.
+["Railway Oriented Programming (ROP)"](https://fsharpforfunandprofit.com/rop/)  is a programming technique that involves linking blocks together to form a sequence of operations, also known as a pipeline.
+If a failure occurs in any of the blocks, the pipeline is interrupted and subsequent blocks are skipped.
 
-In other words, the block will be executed only if the result is a success.
-So, if some block returns a failure, the following blocks will be skipped.
+The ROP technique allows you to structure your code in a way that expresses your logic as a series of operations, with the added benefit of stopping the process at the first detection of failure.
 
-Due to this characteristic, you can use this feature to express some logic as a sequence of operations. And have the guarantee that the process will stop by the first failure detection, and if everything is ok, the final result will be a success.
+If all blocks successfully execute, the final result of the pipeline will be a success.
 
 #### `result.and_then`
 
@@ -481,7 +599,7 @@ module Divide
 
   def call(arg1, arg2)
     validate_numbers(arg1, arg2)
-      .and_then { |numbers| validate_non_zero(numbers) }
+      .and_then { |numbers| validate_nonzero(numbers) }
       .and_then { |numbers| divide(numbers) }
   end
 
@@ -494,8 +612,8 @@ module Divide
     BCDD::Result::Success(:ok, [arg1, arg2])
   end
 
-  def validate_non_zero(numbers)
-    return BCDD::Result::Success(:ok, numbers) unless numbers.last.zero?
+  def validate_nonzero(numbers)
+    return BCDD::Result::Success(:ok, numbers) if numbers.last.nonzero?
 
     BCDD::Result::Failure(:division_by_zero, 'arg2 must not be zero')
   end
@@ -526,9 +644,11 @@ Divide.call(2, 2)
 
 #### `BCDD::Result.mixin`
 
-This method produces a module that can be included/extended by any object. 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 first ones will use the target object (who received the include/extend) as the result's subject.
+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.
 
-And because of this, you can use the `#and_then` method to call methods from the result's subject.
+Because the result has a subject, the `#and_then` method can call methods from it.
 
 ##### Class example (Instance Methods)
 
@@ -545,7 +665,7 @@ class Divide
 
   def call
     validate_numbers
-      .and_then(:validate_non_zero)
+      .and_then(:validate_nonzero)
       .and_then(:divide)
   end
 
@@ -560,7 +680,7 @@ class Divide
     Success(:ok, [arg1, arg2])
   end
 
-  def validate_non_zero(numbers)
+  def validate_nonzero(numbers)
     return Success(:ok, numbers) unless numbers.last.zero?
 
     Failure(:division_by_zero, 'arg2 must not be zero')
@@ -586,7 +706,7 @@ module Divide
 
   def call(arg1, arg2)
     validate_numbers(arg1, arg2)
-      .and_then(:validate_non_zero)
+      .and_then(:validate_nonzero)
       .and_then(:divide)
   end
 
@@ -599,7 +719,7 @@ module Divide
     Success(:ok, [arg1, arg2])
   end
 
-  def validate_non_zero(numbers)
+  def validate_nonzero(numbers)
     return Success(:ok, numbers) unless numbers.last.zero?
 
     Failure(:division_by_zero, 'arg2 must not be zero')
@@ -621,17 +741,122 @@ Divide.call(4, '2') #<BCDD::Result::Failure type=:invalid_arg value="arg2 must b
 
 ##### Important Requirement
 
-The unique condition for using the `#and_then` to call methods is that they must use the `Success()` and `Failure()` to produce their results.
+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.
+
+**Note:** You can still use the block syntax, but all the results must be produced by the subject's `Success()` and `Failure()` methods.
+
+```ruby
+module ValidateNonzero
+  extend self, BCDD::Result.mixin
+
+  def call(numbers)
+    return Success(:ok, numbers) unless numbers.last.zero?
+
+    Failure(:division_by_zero, 'arg2 must not be zero')
+  end
+end
+
+module Divide
+  extend self, BCDD::Result.mixin
+
+  def call(arg1, arg2)
+    validate_numbers(arg1, arg2)
+      .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')
+
+    Success(:ok, [arg1, arg2])
+  end
+
+  def validate_nonzero(numbers)
+    ValidateNonzero.call(numbers) # This will raise an error
+  end
+
+  def divide((number1, number2))
+    Success(:division_completed, number1 / number2)
+  end
+end
+```
+
+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
+# 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.
+
+```ruby
+module ValidateNonzero
+  extend self, BCDD::Result.mixin
+
+  def call(numbers)
+    return Success(:ok, numbers) unless numbers.last.zero?
+
+    Failure(:division_by_zero, 'arg2 must not be zero')
+  end
+end
 
-If you use `BCDD::Result::Subject()`/`BCDD::Result::Failure()`, or use result from another `BCDD::Result::Mixin` instance, the `#and_then` will raise an error because the subjects will be different.
+module Divide
+  extend self, BCDD::Result.mixin
+
+  def call(arg1, arg2)
+    validate_numbers(arg1, arg2)
+      .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')
+
+    Success(:ok, [arg1, arg2])
+  end
 
-> **Note**: You still can use the block syntax, but all the results must be produced by the subject's `Success()` and `Failure()` methods.
+  def validate_nonzero(numbers)
+    # In this case we are handling the other subject result and returning our own
+    ValidateNonzero.call(numbers).handle do |on|
+      on.success { |numbers| Success(:ok, numbers) }
+
+      on.failure { |err| Failure(:division_by_zero, err) }
+    end
+  end
+
+  def divide((number1, number2))
+    Success(:division_completed, number1 / number2)
+  end
+end
+```
+
+Look at the output of the code above:
+
+```ruby
+Divide.call(2, 0)
+
+#<BCDD::Result::Failure type=:division_by_zero value="arg2 must not be zero">
+```
 
 <p align="right"><a href="#-bcddresult">⬆️ &nbsp;back to top</a></p>
 
 ##### 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 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.
 
 ```ruby
 require 'logger'
@@ -641,7 +866,7 @@ module Divide
 
   def call(arg1, arg2, logger: ::Logger.new(STDOUT))
     validate_numbers(arg1, arg2)
-      .and_then(:validate_non_zero, logger)
+      .and_then(:validate_nonzero, logger)
       .and_then(:divide, logger)
   end
 
@@ -654,7 +879,7 @@ module Divide
     Success(:ok, [arg1, arg2])
   end
 
-  def validate_non_zero(numbers, logger)
+  def validate_nonzero(numbers, logger)
     if numbers.last.zero?
       logger.error('arg2 must not be zero')
 
@@ -686,21 +911,21 @@ Divide.call(4, 2, logger: Logger.new(IO::NULL))
 
 <p align="right"><a href="#-bcddresult">⬆️ &nbsp;back to top</a></p>
 
-##### Addons
+##### Add-ons
 
-The `BCDD::Result.mixin` also accepts the `with:` argument. It is a hash that will be used to define the methods that will be added to the target object.
+The `BCDD::Result.mixin` also accepts the `config:` argument. It is a hash that will be used to define custom behaviors for the mixin.
 
-**Continue**
+**continue**
 
 This addon will create the `Continue(value)` method, which will know how to produce a `Success(:continued, value)`. It is useful when you want to perform a sequence of operations but want to avoid returning a specific result for each step.
 
 ```ruby
 module Divide
-  extend self, BCDD::Result.mixin(with: :Continue)
+  extend self, BCDD::Result.mixin(config: { addon: { continue: true } })
 
   def call(arg1, arg2)
     validate_numbers(arg1, arg2)
-      .and_then(:validate_non_zero)
+      .and_then(:validate_nonzero)
       .and_then(:divide)
   end
 
@@ -713,7 +938,7 @@ module Divide
     Continue([arg1, arg2])
   end
 
-  def validate_non_zero(numbers)
+  def validate_nonzero(numbers)
     return Continue(numbers) unless numbers.last.zero?
 
     Failure(:division_by_zero, 'arg2 must not be zero')
@@ -727,139 +952,49 @@ end
 
 <p align="right"><a href="#-bcddresult">⬆️ &nbsp;back to top</a></p>
 
-### Pattern Matching
-
-The `BCDD::Result` also provides support to pattern matching.
-
-In the further examples, I will use the `Divide` lambda to exemplify its usage.
+### `BCDD::Result::Expectations`
 
-```ruby
-Divide = lambda do |arg1, arg2|
-  arg1.is_a?(::Numeric) or return BCDD::Result::Failure(:invalid_arg, 'arg1 must be numeric')
-  arg2.is_a?(::Numeric) or return BCDD::Result::Failure(:invalid_arg, 'arg2 must be numeric')
+This feature lets you define contracts for your results' types and values. There are two ways to use it: the standalone (`BCDD::Result::Expectations.new`) and the mixin (`BCDD::Result::Expectations.mixin`) mode.
 
-  return BCDD::Result::Failure(:division_by_zero, 'arg2 must not be zero') if arg2.zero?
+It was designed to ensure all the aspects of the result's type and value. So, an error will be raised if you try to create or handle a result with an unexpected type or value.
 
-  BCDD::Result::Success(:division_completed, arg1 / arg2)
-end
-```
+#### Standalone *versus* Mixin mode
 
-#### `Array`/`Find` patterns
+The _**standalone mode**_ creates an object that knows how to produce and validate results based on the defined expectations. Look at the example below:
 
 ```ruby
-case Divide.call(4, 2)
-in BCDD::Result::Failure[:invalid_arg, msg] then puts msg
-in BCDD::Result::Failure[:division_by_zero, msg] then puts msg
-in BCDD::Result::Success[:division_completed, value] then puts value
-end
+module Divide
+  Result = BCDD::Result::Expectations.new(
+    success: %i[numbers division_completed],
+    failure: %i[invalid_arg division_by_zero]
+  )
 
-# The code above will print: 2
+  def self.call(arg1, arg2)
+    arg1.is_a?(Numeric) or return Result::Failure(:invalid_arg, 'arg1 must be numeric')
+    arg2.is_a?(Numeric) or return Result::Failure(:invalid_arg, 'arg2 must be numeric')
 
-case Divide.call(4, 0)
-in BCDD::Result::Failure[:invalid_arg, msg] then puts msg
-in BCDD::Result::Failure[:division_by_zero, msg] then puts msg
-in BCDD::Result::Success[:division_completed, value] then puts value
-end
+    arg2.zero? and return Result::Failure(:division_by_zero, 'arg2 must not be zero')
 
-# The code above will print: arg2 must not be zero
+    Result::Success(:division_completed, arg1 / arg2)
+  end
+end
 ```
 
-<p align="right"><a href="#-bcddresult">⬆️ &nbsp;back to top</a></p>
+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.
 
-#### `Hash` patterns
+Look what happens if you try to create a result without one of the expected types.
 
 ```ruby
-case Divide.call(10, 2)
-in { failure: { invalid_arg: msg } } then puts msg
-in { failure: { division_by_zero: msg } } then puts msg
-in { success: { division_completed: value } } then puts value
-end
-
-# The code above will print: 5
-
-case Divide.call('10', 2)
-in { failure: { invalid_arg: msg } } then puts msg
-in { failure: { division_by_zero: msg } } then puts msg
-in { success: { division_completed: value } } then puts value
-end
+Divide::Result::Success(:ok)
+# type :ok is not allowed. Allowed types: :numbers, :division_completed
+# (BCDD::Result::Contract::Error::UnexpectedType)
 
-# The code above will print: arg1 must be numeric
+Divide::Result::Failure(:err)
+# type :err is not allowed. Allowed types: :invalid_arg, :division_by_zero
+# (BCDD::Result::Contract::Error::UnexpectedType)
 ```
 
-<p align="right"><a href="#-bcddresult">⬆️ &nbsp;back to top</a></p>
-
-#### BCDD::Result::Expectations
-
-I'd like you to please read the following section to understand how to use this feature.
-
-But if you are using Ruby >= 3.0, you can use the `in` operator to use the pattern matching to validate the result's value.
-
-```ruby
-module Divide
-  extend BCDD::Result::Expectations.mixin(
-    success: {
-      numbers:            ->(value) { value in [Numeric, Numeric] },
-      division_completed: ->(value) { value in (Integer | Float) }
-    },
-    failure: { invalid_arg: String, division_by_zero: String }
-  )
-
-  def self.call(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')
-
-    arg2.zero? and return Failure(:division_by_zero, 'arg2 must not be zero')
-
-    Success(:division_completed, arg1 / arg2)
-  end
-end
-```
-
-<p align="right"><a href="#-bcddresult">⬆️ &nbsp;back to top</a></p>
-
-### `BCDD::Result::Expectations`
-
-This feature lets you define contracts for your results' types and values. There are two ways to use it: the standalone (`BCDD::Result::Expectations.new`) and the mixin (`BCDD::Result::Expectations.mixin`) mode.
-
-It was designed to ensure all the aspects of the result's type and value. So, an error will be raised if you try to create or handle a result with an unexpected type or value.
-
-#### Standalone *versus* Mixin mode
-
-The _**standalone mode**_ creates an object that knows how to produce and validate results based on the defined expectations. Look at the example below:
-
-```ruby
-module Divide
-  Expected = BCDD::Result::Expectations.new(
-    success: %i[numbers division_completed],
-    failure: %i[invalid_arg division_by_zero]
-  )
-
-  def self.call(arg1, arg2)
-    arg1.is_a?(Numeric) or return Expected::Failure(:invalid_arg, 'arg1 must be numeric')
-    arg2.is_a?(Numeric) or return Expected::Failure(:invalid_arg, 'arg2 must be numeric')
-
-    arg2.zero? and return Expected::Failure(:division_by_zero, 'arg2 must not be zero')
-
-    Expected::Success(:division_completed, arg1 / arg2)
-  end
-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.
-
-Look what happens if you try to create a result without one of the expected types.
-
-```ruby
-Divide::Expected::Success(:ok)
-# type :ok is not allowed. Allowed types: :numbers, :division_completed
-# (BCDD::Result::Expectations::Error::UnexpectedType)
-
-Divide::Expected::Failure(:err)
-# type :err is not allowed. Allowed types: :invalid_arg, :division_by_zero
-# (BCDD::Result::Expectations::Error::UnexpectedType)
-```
-
-The _**mixin mode**_ is similar to `BCDD::Result::Mixin`, but it also defines the expectations for the result's types and values.
+The _**mixin mode**_ is similar to `BCDD::Result::Mixin`, but it also defines the expectations for the result's types and values.
 
 ```ruby
 class Divide
@@ -870,7 +1005,7 @@ class Divide
 
   def call(arg1, arg2)
     validate_numbers(arg1, arg2)
-      .and_then(:validate_non_zero)
+      .and_then(:validate_nonzero)
       .and_then(:divide)
   end
 
@@ -883,7 +1018,7 @@ class Divide
     Success(:numbers, [arg1, arg2])
   end
 
-  def validate_non_zero(numbers)
+  def validate_nonzero(numbers)
     return Success(:numbers, numbers) unless numbers.last.zero?
 
     Failure(:division_by_zero, 'arg2 must not be zero')
@@ -895,10 +1030,10 @@ class Divide
 end
 ```
 
-This mode also defines an `Expected` constant to be used inside and outside the module.
+This mode also defines an `Result` constant to be used inside and outside the module.
 
 > **PROTIP:**
-> You can use the `Expected` constant to mock the result's type and value in your tests. As they will have the exact expectations, your tests will check if the result clients are handling the result correctly.
+> You can use the `Result` constant to mock the result's type and value in your tests. As they will have the exact expectations, your tests will check if the result clients are handling the result correctly.
 
 Now that you know the two modes, let's understand how expectations can be beneficial and powerful for defining contracts.
 
@@ -906,11 +1041,11 @@ Now that you know the two modes, let's understand how expectations can be benefi
 
 #### Type checking - Result Hooks
 
-The `BCDD::Result::Expectations` will check if the result's type is valid. This checking will be performed in all the methods that rely on the result's type, like `#success?`, `#failure?`, `#on`, `#on_type`, `#on_success`, `#on_failure`, `#handle`.
+The `BCDD::Result::Expectations` will check if the type of the result is valid. This checking will be performed in all methods that depend on the result’s type, such as `#success?`, `#failure?`, `#on`, `#on_type`, `#on_success`, `#on_failure`, and `#handle`.
 
 ##### `#success?` and `#failure?`
 
-When you check whether a result is a success or failure, `BCDD::Result::Expectations` will check whether the result type is valid/expected. Otherwise, an error will be raised.
+When checking whether a result is a success or failure, `BCDD::Result::Expectations` will also verify if the result type is valid/expected. In case of an invalid type, an error will be raised.
 
 **Success example:**
 
@@ -923,7 +1058,7 @@ result.success?(:division_completed) # true
 
 result.success?(:ok)
 # type :ok is not allowed. Allowed types: :numbers, :division_completed
-# (BCDD::Result::Expectations::Error::UnexpectedType)
+# (BCDD::Result::Contract::Error::UnexpectedType)
 ```
 
 **Failure example:**
@@ -937,7 +1072,7 @@ result.failure?(:division_by_zero) # false
 
 result.failure?(:err)
 # type :err is not allowed. Allowed types: :invalid_arg, :division_by_zero
-# (BCDD::Result::Expectations::Error::UnexpectedType)
+# (BCDD::Result::Contract::Error::UnexpectedType)
 ```
 
 *PS: The `Divide` implementation is [here](#standalone-versus-mixin-mode).*
@@ -946,7 +1081,7 @@ result.failure?(:err)
 
 ##### `#on` and `#on_type`
 
-If you use `#on` or `#on_type` to perform a block, `BCDD::Result::Expectations` will check whether the result type is valid/expected. Otherwise, an error will be raised.
+If you use `#on` or `#on_type` to execute a block, `BCDD::Result::Expectations` will check whether the result type is valid/expected. Otherwise, an error will be raised.
 
 ```ruby
 result = Divide.new.call(10, 2)
@@ -959,7 +1094,7 @@ result
 
 result.on(:number) { |_| :this_type_does_not_exist }
 # type :number is not allowed. Allowed types: :numbers, :division_completed, :invalid_arg, :division_by_zero
-# (BCDD::Result::Expectations::Error::UnexpectedType)
+# (BCDD::Result::Contract::Error::UnexpectedType)
 ```
 
 *PS: The `Divide` implementation is [here](#standalone-versus-mixin-mode).*
@@ -968,7 +1103,7 @@ result.on(:number) { |_| :this_type_does_not_exist }
 
 ##### `#on_success` and `#on_failure`
 
-If you use `#on_success` or `#on_failure` to perform a block, `BCDD::Result::Expectations` will check whether the result type is valid/expected. Otherwise, an error will be raised.
+If you use `#on_success` or `#on_failure` to execute a block, `BCDD::Result::Expectations` will check whether the result type is valid/expected. Otherwise, an error will be raised.
 
 ```ruby
 result = Divide.new.call(10, '2')
@@ -985,11 +1120,11 @@ result
 
 result.on_success(:ok) { |_| :this_type_does_not_exist }
 # type :ok is not allowed. Allowed types: :numbers, :division_completed
-# (BCDD::Result::Expectations::Error::UnexpectedType)
+# (BCDD::Result::Contract::Error::UnexpectedType)
 
 result.on_failure(:err) { |_| :this_type_does_not_exist }
 # type :err is not allowed. Allowed types: :invalid_arg, :division_by_zero
-# (BCDD::Result::Expectations::Error::UnexpectedType)
+# (BCDD::Result::Contract::Error::UnexpectedType)
 ```
 
 *PS: The `Divide` implementation is [here](#standalone-versus-mixin-mode).*
@@ -1006,17 +1141,17 @@ result = Divide.call(10, 2)
 result.handle do |on|
   on.type(:ok) { |_| :this_type_does_not_exist }
 end
-# type :ok is not allowed. Allowed types: :numbers, :division_completed, :invalid_arg, :division_by_zero (BCDD::Result::Expectations::Error::UnexpectedType)
+# type :ok is not allowed. Allowed types: :numbers, :division_completed, :invalid_arg, :division_by_zero (BCDD::Result::Contract::Error::UnexpectedType)
 
 result.handle do |on|
   on.success(:ok) { |_| :this_type_does_not_exist }
 end
-# type :ok is not allowed. Allowed types: :numbers, :division_completed (BCDD::Result::Expectations::Error::UnexpectedType)
+# type :ok is not allowed. Allowed types: :numbers, :division_completed (BCDD::Result::Contract::Error::UnexpectedType)
 
 result.handle do |on|
   on.failure(:err) { |_| :this_type_does_not_exist }
 end
-# type :err is not allowed. Allowed types: :numbers, :division_completed (BCDD::Result::Expectations::Error::UnexpectedType)
+# type :err is not allowed. Allowed types: :invalid_arg, :division_by_zero (BCDD::Result::Contract::Error::UnexpectedType)
 ```
 
 *PS: The `Divide` implementation is [here](#standalone-versus-mixin-mode).*
@@ -1047,11 +1182,11 @@ end
 
 Divide.call('4', 2)
 # type :invalid_arg is not allowed. Allowed types: :err
-# (BCDD::Result::Expectations::Error::UnexpectedType)
+# (BCDD::Result::Contract::Error::UnexpectedType)
 
 Divide.call(4, 2)
 # type :division_completed is not allowed. Allowed types: :ok
-# (BCDD::Result::Expectations::Error::UnexpectedType)
+# (BCDD::Result::Contract::Error::UnexpectedType)
 ```
 
 <p align="right"><a href="#-bcddresult">⬆️ &nbsp;back to top</a></p>
@@ -1060,25 +1195,25 @@ Divide.call(4, 2)
 
 ```ruby
 module Divide
-  Expected = BCDD::Result::Expectations.new(success: :ok, failure: :err)
+  Result = BCDD::Result::Expectations.new(success: :ok, failure: :err)
 
   def self.call(arg1, arg2)
-    arg1.is_a?(Numeric) or return Expected::Failure(:invalid_arg, 'arg1 must be numeric')
-    arg2.is_a?(Numeric) or return Expected::Failure(:invalid_arg, 'arg2 must be numeric')
+    arg1.is_a?(Numeric) or return Result::Failure(:invalid_arg, 'arg1 must be numeric')
+    arg2.is_a?(Numeric) or return Result::Failure(:invalid_arg, 'arg2 must be numeric')
 
-    arg2.zero? and return Expected::Failure(:division_by_zero, 'arg2 must not be zero')
+    arg2.zero? and return Result::Failure(:division_by_zero, 'arg2 must not be zero')
 
-    Expected::Success(:division_completed, arg1 / arg2)
+    Result::Success(:division_completed, arg1 / arg2)
   end
 end
 
 Divide.call('4', 2)
 # type :invalid_arg is not allowed. Allowed types: :err
-# (BCDD::Result::Expectations::Error::UnexpectedType)
+# (BCDD::Result::Contract::Error::UnexpectedType)
 
 Divide.call(4, 2)
 # type :division_completed is not allowed. Allowed types: :ok
-# (BCDD::Result::Expectations::Error::UnexpectedType)
+# (BCDD::Result::Contract::Error::UnexpectedType)
 ```
 
 <p align="right"><a href="#-bcddresult">⬆️ &nbsp;back to top</a></p>
@@ -1119,7 +1254,7 @@ end
 
 ```ruby
 module Divide
-  Expected = BCDD::Result::Expectations.new(
+  Result = BCDD::Result::Expectations.new(
     success: {
       numbers: ->(value) { value.is_a?(Array) && value.size == 2 && value.all?(Numeric) },
       division_completed: Numeric
@@ -1131,12 +1266,12 @@ module Divide
   )
 
   def self.call(arg1, arg2)
-    arg1.is_a?(Numeric) or return Expected::Failure(:invalid_arg, 'arg1 must be numeric')
-    arg2.is_a?(Numeric) or return Expected::Failure(:invalid_arg, 'arg2 must be numeric')
+    arg1.is_a?(Numeric) or return Result::Failure(:invalid_arg, 'arg1 must be numeric')
+    arg2.is_a?(Numeric) or return Result::Failure(:invalid_arg, 'arg2 must be numeric')
 
-    arg2.zero? and return Expected::Failure(:division_by_zero, 'arg2 must not be zero')
+    arg2.zero? and return Result::Failure(:division_by_zero, 'arg2 must not be zero')
 
-    Expected::Success(:division_completed, arg1 / arg2)
+    Result::Success(:division_completed, arg1 / arg2)
   end
 end
 ```
@@ -1148,50 +1283,86 @@ The value validation will only be performed through the methods `Success()` and
 ##### Success()
 
 ```ruby
-Divide::Expected::Success(:ok)
-# type :ok is not allowed. Allowed types: :numbers, :division_completed (BCDD::Result::Expectations::Error::UnexpectedType)
+Divide::Result::Success(:ok)
+# type :ok is not allowed. Allowed types: :numbers, :division_completed (BCDD::Result::Contract::Error::UnexpectedType)
 
-Divide::Expected::Success(:numbers, [1])
-# value [1] is not allowed for :numbers type (BCDD::Result::Expectations::Error::UnexpectedValue)
+Divide::Result::Success(:numbers, [1])
+# value [1] is not allowed for :numbers type (BCDD::Result::Contract::Error::UnexpectedValue)
 
-Divide::Expected::Success(:division_completed, '2')
-# value "2" is not allowed for :division_completed type (BCDD::Result::Expectations::Error::UnexpectedValue)
+Divide::Result::Success(:division_completed, '2')
+# value "2" is not allowed for :division_completed type (BCDD::Result::Contract::Error::UnexpectedValue)
 ```
 
 ##### Failure()
 
 ```ruby
-Divide::Expected::Failure(:err)
-# type :err is not allowed. Allowed types: :invalid_arg, :division_by_zero (BCDD::Result::Expectations::Error::UnexpectedType)
+Divide::Result::Failure(:err)
+# type :err is not allowed. Allowed types: :invalid_arg, :division_by_zero (BCDD::Result::Contract::Error::UnexpectedType)
+
+Divide::Result::Failure(:invalid_arg, :arg1_must_be_numeric)
+# value :arg1_must_be_numeric is not allowed for :invalid_arg type (BCDD::Result::Contract::Error::UnexpectedValue)
+
+Divide::Result::Failure(:division_by_zero, msg: 'arg2 must not be zero')
+# value {:msg=>"arg2 must not be zero"} is not allowed for :division_by_zero type (BCDD::Result::Contract::Error::UnexpectedValue)
+```
+
+<p align="right"><a href="#-bcddresult">⬆️ &nbsp;back to top</a></p>
+
+##### Pattern Matching Support
+
+The value checking has support for handling pattern-matching errors, and the cleanest way to do it is using the one-line pattern matching operators (`=>` since Ruby 3.0) and (`in` Ruby 2.7).
+
+How does this operator work? They raise an error when the pattern does not match but returns nil when it matches.
+
+Because of this, you will need to enable `nil` as a valid value checking. You can do it through the `BCDD::Result.configuration` or by allowing it directly on the mixin config.
+
+```ruby
+module Divide
+  extend BCDD::Result::Expectations.mixin(
+    config: {
+      pattern_matching: { nil_as_valid_value_checking: true }
+    },
+    success: {
+      division_completed: ->(value) { value => (Integer | Float) }
+    },
+    failure: { invalid_arg: String, division_by_zero: String }
+  )
+
+  def self.call(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')
+
+    arg2.zero? and return Failure(:division_by_zero, 'arg2 must not be zero')
 
-Divide::Expected::Failure(:invalid_arg, :arg1_must_be_numeric)
-# value :arg1_must_be_numeric is not allowed for :invalid_arg type (BCDD::Result::Expectations::Error::UnexpectedValue)
+    Success(:division_completed, String(arg1 / arg2))
+  end
+end
 
-Divide::Expected::Failure(:division_by_zero, msg: 'arg2 must not be zero')
-# value {:msg=>"arg2 must not be zero"} is not allowed for :division_by_zero type (BCDD::Result::Expectations::Error::UnexpectedValue)
+Divide.call(10, 5)
+# value "2" is not allowed for :division_completed type ("2": Float === "2" does not return true) (BCDD::Result::Contract::Error::UnexpectedValue)
 ```
 
 <p align="right"><a href="#-bcddresult">⬆️ &nbsp;back to top</a></p>
 
-#### `BCDD::Result::Expectations.mixin` Addons
+#### `BCDD::Result::Expectations.mixin` add-ons
 
-The `BCDD::Result::Expectations.mixin` also accepts the `with:` argument. It is a hash that will be used to define the methods that will be added to the target object.
+The `BCDD::Result::Expectations.mixin` also accepts the `config:` argument. It is a hash that can be used to define custom behaviors for the mixin.
 
 **Continue**
 
-It is similar to `BCDD::Result.mixin(with: :Continue)`, the key difference is that the `Continue(value)` will be ignored by the expectations. This is extremely useful when you want to use `Continue(value)` to chain operations, but you don't want to declare N success types in the expectations.
+It is similar to `BCDD::Result.mixin(config: { addon: { continue: true } })`, the key difference is that the `Continue(value)` will be ignored by the expectations. This is extremely useful when you want to use `Continue(value)` to chain operations, but you don't want to declare N success types in the expectations.
 
 ```ruby
 class Divide
   include BCDD::Result::Expectations.mixin(
-    with: :Continue,
+    config: { addon: { continue: true } },
     success: :division_completed,
     failure: %i[invalid_arg division_by_zero]
   )
 
   def call(arg1, arg2)
     validate_numbers(arg1, arg2)
-      .and_then(:validate_non_zero)
+      .and_then(:validate_nonzero)
       .and_then(:divide)
   end
 
@@ -1204,7 +1375,7 @@ class Divide
     Continue([arg1, arg2])
   end
 
-  def validate_non_zero(numbers)
+  def validate_nonzero(numbers)
     return Continue(numbers) unless numbers.last.zero?
 
     Failure(:division_by_zero, 'arg2 must not be zero')
@@ -1215,7 +1386,7 @@ class Divide
   end
 end
 
-result = Divide.new.call(4,2)
+result = Divide.new.call(4, 2)
 # => #<BCDD::Result::Success type=:division_completed value=2>
 
 # The example below shows an error because the :ok type is not allowed.
@@ -1223,11 +1394,447 @@ result = Divide.new.call(4,2)
 # This is because the :continued type is ignored by the expectations.
 #
 result.success?(:ok)
-# type :ok is not allowed. Allowed types: :division_completed (BCDD::Result::Expectations::Error::UnexpectedType)
+# type :ok is not allowed. Allowed types: :division_completed (BCDD::Result::Contract::Error::UnexpectedType)
+```
+
+<p align="right"><a href="#-bcddresult">⬆️ &nbsp;back to top</a></p>
+
+### `BCDD::Result::Context`
+
+The `BCDD::Result::Context` is a `BCDD::Result`, meaning it has all the features of the `BCDD::Result`. The main difference is that it only accepts keyword arguments as a value, which applies to the `and_then`: The called methods must receive keyword arguments, and the dependency injection will be performed through keyword arguments.
+
+As the input/output are hashes, the results of each `and_then` call will automatically accumulate. This is useful in operations chaining, as the result of the previous operations will be automatically available for the next one. Because of this behavior, the `BCDD::Result::Context` has the `#and_expose` method to expose only the desired keys from the accumulated result.
+
+#### Defining successes and failures
+
+As the `BCDD::Result`, you can declare success and failures directly from `BCDD::Result::Context`.
+
+```ruby
+BCDD::Result::Context::Success(:ok, a: 1, b: 2)
+#<BCDD::Result::Context::Success type=:ok value={:a=>1, :b=>2}>
+
+BCDD::Result::Context::Failure(:err, message: 'something went wrong')
+#<BCDD::Result::Context::Failure type=:err value={:message=>"something went wrong"}>
+```
+
+But different from `BCDD::Result` that accepts any value, the `BCDD::Result::Context` only takes keyword arguments.
+
+```ruby
+BCDD::Result::Context::Success(:ok, [1, 2])
+# wrong number of arguments (given 2, expected 1) (ArgumentError)
+
+BCDD::Result::Context::Failure(:err, { message: 'something went wrong' })
+# wrong number of arguments (given 2, expected 1) (ArgumentError)
+
+#
+# Use ** to convert a hash to keyword arguments
+#
+BCDD::Result::Context::Success(:ok, **{ message: 'hashes can be converted to keyword arguments' })
+#<BCDD::Result::Context::Success type=:ok value={:message=>"hashes can be converted to keyword arguments"}>
+```
+
+<p align="right"><a href="#-bcddresult">⬆️ &nbsp;back to top</a></p>
+
+#### `BCDD::Result::Context.mixin`
+
+As in the `BCDD::Result`, you can use the `BCDD::Result::Context.mixin` to add the `Success()` and `Failure()` methods to your classes/modules.
+
+Let's see this feature and the data accumulation in action:
+
+##### Class example (Instance Methods)
+
+```ruby
+require 'logger'
+
+class Divide
+  include BCDD::Result::Context.mixin
+
+  def call(arg1, arg2, logger: ::Logger.new(STDOUT))
+    validate_numbers(arg1, arg2)
+      .and_then(:validate_nonzero)
+      .and_then(:divide, logger: logger)
+  end
+
+  private
+
+  def validate_numbers(arg1, arg2)
+    arg1.is_a?(::Numeric) or return Failure(:err, message: 'arg1 must be numeric')
+    arg2.is_a?(::Numeric) or return Failure(:err, message: 'arg2 must be numeric')
+
+    Success(:ok, number1: arg1, number2: arg2)
+  end
+
+  def validate_nonzero(number2:, **)
+    return Success(:ok) if number2.nonzero?
+
+    Failure(:err, message: 'arg2 must not be zero')
+  end
+
+  #
+  # The logger was injected via #and_then and keyword arguments
+  #
+  def divide(number1:, number2:, logger:)
+    result = number1 / number2
+
+    logger.info("The division result is #{result}")
+
+    Success(:ok, number: result)
+  end
+end
+
+Divide.new.call(10, 5)
+# I, [2023-10-27T01:51:46.905004 #76915]  INFO -- : The division result is 2
+#<BCDD::Result::Context::Success type=:ok value={:number=>2}>
+
+Divide.new.call('10', 5)
+#<BCDD::Result::Context::Failure type=:err value={:message=>"arg1 must be numeric"}>
+
+Divide.new.call(10, '5')
+#<BCDD::Result::Context::Failure type=:err value={:message=>"arg2 must be numeric"}>
+
+Divide.new.call(10, 0)
+#<BCDD::Result::Context::Failure type=:err value={:message=>"arg2 must not be zero"}>
+```
+
+<p align="right"><a href="#-bcddresult">⬆️ &nbsp;back to top</a></p>
+
+##### `and_expose`
+
+This allows you to expose only the desired keys from the accumulated result. It can be used with any `BCDD::Result::Context` object.
+
+Let's add it to the previous example:
+
+```ruby
+class Divide
+  include BCDD::Result::Context.mixin
+
+  def call(arg1, arg2)
+    validate_numbers(arg1, arg2)
+      .and_then(:validate_nonzero)
+      .and_then(:divide)
+      .and_expose(:division_completed, [:number])
+  end
+
+  private
+
+  def validate_numbers(arg1, arg2)
+    arg1.is_a?(::Numeric) or return Failure(:err, message: 'arg1 must be numeric')
+    arg2.is_a?(::Numeric) or return Failure(:err, message: 'arg2 must be numeric')
+
+    Success(:ok, number1: arg1, number2: arg2)
+  end
+
+  def validate_nonzero(number2:, **)
+    return Success(:ok) if number2.nonzero?
+
+    Failure(:err, message: 'arg2 must not be zero')
+  end
+
+  def divide(**input)
+    Success(:ok, number: input.values.reduce(:/), **input)
+  end
+end
+
+Divide.new.call(10, 5)
+#<BCDD::Result::Context::Success type=:division_completed value={:number=>2}>
+```
+
+As you can see, even with `divide` success exposing the division number with all the accumulated data (`**input`), the `#and_expose` could generate a new success with a new type and only with the desired keys.
+
+Remove the `#and_expose` call to see the difference. This will be the outcome:
+
+```ruby
+Divide.new.call(10, 5)
+#<BCDD::Result::Context::Success type=:ok value={:number=>2, :number1=>10, :number2=>5}>
+```
+
+<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).
+
+```ruby
+module Divide
+  extend self, BCDD::Result::Context.mixin
+
+  def call(arg1, arg2)
+    validate_numbers(arg1, arg2)
+      .and_then(:validate_nonzero)
+      .and_then(:divide)
+      .and_expose(:division_completed, [:number])
+  end
+
+  private
+
+  def validate_numbers(arg1, arg2)
+    arg1.is_a?(::Numeric) or return Failure(:err, message: 'arg1 must be numeric')
+    arg2.is_a?(::Numeric) or return Failure(:err, message: 'arg2 must be numeric')
+
+    Success(:ok, number1: arg1, number2: arg2)
+  end
+
+  def validate_nonzero(number2:, **)
+    return Success(:ok) if number2.nonzero?
+
+    Failure(:err, message: 'arg2 must not be zero')
+  end
+
+  def divide(number1:, number2:)
+    Success(:ok, number: number1 / number2)
+  end
+end
+
+Divide.call(10, 5)
+#<BCDD::Result::Context::Success type=:division_completed value={:number=>2}>
+
+Divide.call('10', 5)
+#<BCDD::Result::Context::Failure type=:err value={:message=>"arg1 must be numeric"}>
+
+Divide.call(10, '5')
+#<BCDD::Result::Context::Failure type=:err value={:message=>"arg2 must be numeric"}>
+
+Divide.call(10, 0)
+#<BCDD::Result::Context::Failure type=:err value={:message=>"arg2 must not be zero"}>
+```
+
+<p align="right"><a href="#-bcddresult">⬆️ &nbsp;back to top</a></p>
+
+#### `BCDD::Result::Context::Expectations`
+
+The `BCDD::Result::Context::Expectations` is a `BCDD::Result::Expectations` with the `BCDD::Result::Context` features.
+
+This is an example using the mixin mode, but the standalone mode is also supported.
+
+```ruby
+class Divide
+  include BCDD::Result::Context::Expectations.mixin(
+    config: {
+      pattern_matching: { nil_as_valid_value_checking: true }
+    },
+    success: {
+      division_completed: ->(value) { value => { number: Numeric } }
+    },
+    failure: {
+      invalid_arg:      ->(value) { value => { message: String } },
+      division_by_zero: ->(value) { value => { message: String } }
+    }
+  )
+
+  def call(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')
+
+    arg2.zero? and return Failure(:division_by_zero, message: 'arg2 must not be zero')
+
+    Success(:division_completed, number: (arg1 / arg2))
+  end
+end
+
+Divide.new.call(10, 5)
+#<BCDD::Result::Context::Success type=:division_completed value={:number=>2}>
+```
+
+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:
+
+```ruby
+Divide::Result::Success(:division_completed, number: 2)
+#<BCDD::Result::Context::Success type=:division_completed value={:number=>2}>
+
+Divide::Result::Success(:division_completed, number: '2')
+# value {:number=>"2"} is not allowed for :division_completed type ({:number=>"2"}: Numeric === "2" does not return true) (BCDD::Result::Contract::Error::UnexpectedValue)
+```
+
+<p align="right"><a href="#-bcddresult">⬆️ &nbsp;back to top</a></p>
+
+#### Mixin add-ons
+
+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**
+
+The `BCDD::Result::Context.mixin(config: { addon: { continue: true } })` or `BCDD::Result::Context::Expectations.mixin(config: { addon: { continue: true } })` adds a `Continue(**input)` that will be ignored by the expectations. This is extremely useful when you want to use `Continue()` to chain operations, but you don't want to declare N success types in the expectations.
+
+Let's use a mix of `BCDD::Result::Context` features to see in action with this add-on:
+
+```ruby
+module Divide
+  require 'logger'
+
+  extend self, BCDD::Result::Context::Expectations.mixin(
+    config: {
+      addon:            { continue: true },
+      pattern_matching: { nil_as_valid_value_checking: true }
+    },
+    success: {
+      division_completed: ->(value) { value => { number: Numeric } }
+    },
+    failure: {
+      invalid_arg:      ->(value) { value => { message: String } },
+      division_by_zero: ->(value) { value => { message: String } }
+    }
+  )
+
+  def call(arg1, arg2, logger: ::Logger.new(STDOUT))
+    validate_numbers(arg1, arg2)
+      .and_then(:validate_nonzero)
+      .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')
+
+    Continue(number1: arg1, number2: arg2)
+  end
+
+  def validate_nonzero(number2:, **)
+    return Continue() if number2.nonzero?
+
+    Failure(:division_by_zero, message: 'arg2 must not be zero')
+  end
+
+  def divide(number1:, number2:, logger:)
+    result = number1 / number2
+
+    logger.info("The division result is #{result}")
+
+    Continue(number: result)
+  end
+end
+
+Divide.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)
+#<BCDD::Result::Context::Failure type=:invalid_arg value={:message=>"arg1 must be numeric"}>
+
+Divide.call(14, '2')
+#<BCDD::Result::Context::Failure type=:invalid_arg value={:message=>"arg2 must be numeric"}>
+
+Divide.call(14, 0)
+#<BCDD::Result::Context::Failure type=:division_by_zero value={:message=>"arg2 must not be zero"}>
 ```
 
+### `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.
+
+```ruby
+BCDD::Result.configuration do |config|
+  config.addon.enable!(:continue)
+
+  config.constant_alias.enable!('Result')
+
+  config.pattern_matching.disable!(:nil_as_valid_value_checking)
+
+  config.feature.disable!(:expectations) if ::Rails.env.production?
+end
+```
+
+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)`
+
+This configuration enables the `Continue()` method for `BCDD::Result` and `BCDD::Result::Context`. Link to documentations: [(1)](#add-ons) [(2)](#mixin-add-ons).
+
+#### `config.constant_alias.enable!('Result')`
+
+This configuration make `Result` a constant alias for `BCDD::Result`. Link to [documentation](#bcddresult-versus-result).
+
+#### `config.pattern_matching.disable!(:nil_as_valid_value_checking)`
+
+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)`
+
+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.
+
+### `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.
+
+**BCDD::Result.config.addon**
+
+```ruby
+BCDD::Result.config.addon.enabled?(:continue)
+
+BCDD::Result.config.addon.options
+# {
+#   :continue=>{
+#     :enabled=>false,
+#     :affects=>[
+#       "BCDD::Result",
+#       "BCDD::Result::Context",
+#       "BCDD::Result::Expectations",
+#       "BCDD::Result::Context::Expectations"
+#     ]
+#   }
+# }
+```
+
+**BCDD::Result.config.constant_alias**
+
+```ruby
+BCDD::Result.config.constant_alias.enabled?('Result')
+
+BCDD::Result.config.constant_alias.options
+# {
+#   "Result"=>{
+#     :enabled=>false,
+#     :affects=>[
+#       "Object"
+#     ]
+#   }
+# }
+```
+
+**BCDD::Result.config.pattern_matching**
+
+```ruby
+BCDD::Result.config.pattern_matching.enabled?(:nil_as_valid_value_checking)
+
+BCDD::Result.config.pattern_matching.options
+# {
+#   :nil_as_valid_value_checking=>{
+#     :enabled=>false,
+#     :affects=>[
+#       "BCDD::Result::Expectations,
+#       "BCDD::Result::Context::Expectations"
+#     ]
+#   }
+# }
+```
+
+**BCDD::Result.config.feature**
+
+```ruby
+BCDD::Result.config.feature.enabled?(:expectations)
+
+BCDD::Result.config.feature.options
+# {
+#   :expectations=>{
+#     :enabled=>true,
+#     :affects=>[
+#       "BCDD::Result::Expectations,
+#       "BCDD::Result::Context::Expectations"
+#     ]
+#   }
+# }
+```
+
 ## 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.