bcdd-result 0.10.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7bf2a03ac7efd3e75e03b2f5617518cb07f40e03cc970c612f3d4dfcdad153ad
-  data.tar.gz: 2717e6e600101401f420164aed020689e9c07dd7f7296c78ec5290562620ca3c
+  metadata.gz: c0043be8de0b26bac0d803f067537fbc65e4a54f3a38a2644c01bd987d87c7b5
+  data.tar.gz: f152ac78abb8847721f2b2ec3c3fd1db66016c421f5348f038a79501a86f761a
 SHA512:
-  metadata.gz: c1761571f7d0c0a6fd4601a9f8a4c8c18688085226cd061057f95c93737da80ac58e0a99a3803a0e0f93aa5040530975d9b16a7b54df79487ca625fd67d405d6
-  data.tar.gz: 4b22f37d2282de4c0a6e3781e86c9c63457efa83a7d5dc07db4288b9fe19c5b3868cd13a34a1cfc515776cf466e2095bde9d10503f87b8f546ceab9408ef9617
+  metadata.gz: 17abccc11ad3c7ccd2cedc6f9634659decee457e08ef1c8dfb13d59d2afc7390fdeb6fc1d48749362d691815c41b789197d2bf79b5f57f9e7e07ad770ddbb304
+  data.tar.gz: 2e0b67fbc99ef2a3a8187a2d42212e8cbadca22a2c2625c3be8e7bbfb5d2b92689b9a27b7592a295863e89437e912d34cb8f6e5a2e77e9c0afdbcbf7c4591bd6

data/CHANGELOG.md

@@ -1,38 +1,55 @@
 - [\[Unreleased\]](#unreleased)
-- [\[0.10.0\] - 2023-12-31](#0100---2023-12-31)
+- [\[0.11.0\] - 2024-01-02](#0110---2024-01-02)
   - [Added](#added)
-- [\[0.9.1\] - 2023-12-12](#091---2023-12-12)
   - [Changed](#changed)
-  - [Fixed](#fixed)
-- [\[0.9.0\] - 2023-12-12](#090---2023-12-12)
+- [\[0.10.0\] - 2023-12-31](#0100---2023-12-31)
   - [Added](#added-1)
+- [\[0.9.1\] - 2023-12-12](#091---2023-12-12)
   - [Changed](#changed-1)
-- [\[0.8.0\] - 2023-12-11](#080---2023-12-11)
+  - [Fixed](#fixed)
+- [\[0.9.0\] - 2023-12-12](#090---2023-12-12)
   - [Added](#added-2)
   - [Changed](#changed-2)
-  - [Removed](#removed)
-- [\[0.7.0\] - 2023-10-27](#070---2023-10-27)
+- [\[0.8.0\] - 2023-12-11](#080---2023-12-11)
   - [Added](#added-3)
   - [Changed](#changed-3)
-- [\[0.6.0\] - 2023-10-11](#060---2023-10-11)
+  - [Removed](#removed)
+- [\[0.7.0\] - 2023-10-27](#070---2023-10-27)
   - [Added](#added-4)
   - [Changed](#changed-4)
-- [\[0.5.0\] - 2023-10-09](#050---2023-10-09)
+- [\[0.6.0\] - 2023-10-11](#060---2023-10-11)
   - [Added](#added-5)
-- [\[0.4.0\] - 2023-09-28](#040---2023-09-28)
-  - [Added](#added-6)
   - [Changed](#changed-5)
+- [\[0.5.0\] - 2023-10-09](#050---2023-10-09)
+  - [Added](#added-6)
+- [\[0.4.0\] - 2023-09-28](#040---2023-09-28)
+  - [Added](#added-7)
+  - [Changed](#changed-6)
   - [Removed](#removed-1)
 - [\[0.3.0\] - 2023-09-26](#030---2023-09-26)
-  - [Added](#added-7)
-- [\[0.2.0\] - 2023-09-26](#020---2023-09-26)
   - [Added](#added-8)
+- [\[0.2.0\] - 2023-09-26](#020---2023-09-26)
+  - [Added](#added-9)
   - [Removed](#removed-2)
 - [\[0.1.0\] - 2023-09-25](#010---2023-09-25)
-  - [Added](#added-9)
+  - [Added](#added-10)
 
 ## [Unreleased]
 
+## [0.11.0] - 2024-01-02
+
+### Added
+
+- Add the `Given()` addon to produce a `Success(:given, value)` result. As the `Continue()` addon, it is ignored by the expectations. Use it to add a value to the result chain and invoke the next step (through `and_then`).
+
+### Changed
+
+- **(BREAKING)** Rename halted concept to terminal. Failures are terminal by default, but you can make a success terminal by enabling the `:continue` addon.
+
+- **(BREAKING)** Rename `BCDD::Result::Context::Success#and_expose` halted keyword argument to `terminal`.
+
+- **(BREAKING)** Rename `BCDD::Result#halted?` to `BCDD::Result#terminal?`.
+
 ## [0.10.0] - 2023-12-31
 
 ### Added
@@ -45,7 +62,7 @@
 
 ### Changed
 
-- **(BREAKING)** Make `BCDD::Result::Context::Success#and_expose()` to produce a halted success by default. You can turn this off by passing `halted: false`.
+- **(BREAKING)** Make `BCDD::Result::Context::Success#and_expose()` to produce a terminal success by default. You can turn this off by passing `halted: false`.
 
 ### Fixed
 

data/README.md

@@ -73,7 +73,7 @@ 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)
@@ -918,35 +918,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 terminated.
 
-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.
+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 +1584,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 +1691,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`).
+
+You can turn it off by passing `given: false` to the `config:` argument or using the `BCDD::Result.configuration`.
+
+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 halt the step chain.
+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 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.
 
 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 +1726,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 +1759,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 +1788,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 +1799,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 +1851,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, :subject=>#<Division:0x0000000103e5f7c8>, :method_name=>:check_for_zeros},
-      :time=>2023-12-31 22:19:33.281693 UTC
+      :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=>: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=>: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, :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=>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, :subject=>#<Division:0x0000000103e5f1b0>, :method_name=>:check_for_zeros},
-      :time=>2023-12-31 22:19:33.281755 UTC
+      :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=>: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=>: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, :subject=><Division:0x0000000106097ed0>, :method_name=>:divide},
+      :time=>2024-01-02 03:35:11.248682 UTC
     },
     {
       :root=>{:id=>0, :name=>"SumDivisionsByTwo", :desc=>nil},
@@ -1876,7 +1920,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 +1953,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 +1967,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.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).
 
-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).
+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 +2001,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"
 #     ]
 #   }
 # }

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'

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

@@ -3,11 +3,16 @@
 class BCDD::Result
   class Config
     module Addons
+      AFFECTS = %w[
+        BCDD::Result.mixin
+        BCDD::Result::Context.mixin
+        BCDD::Result::Expectations.mixin
+        BCDD::Result::Context::Expectations.mixin
+      ].freeze
+
       OPTIONS = {
-        continue: {
-          default: false,
-          affects: %w[BCDD::Result BCDD::Result::Context BCDD::Result::Expectations BCDD::Result::Context::Expectations]
-        }
+        continue: { default: false, affects: AFFECTS },
+        given: { default: true, affects: AFFECTS }
       }.transform_values!(&:freeze).freeze
 
       def self.switcher

data/lib/bcdd/result/context/expectations/mixin.rb

@@ -7,13 +7,21 @@ class BCDD::Result::Context
     Methods = BCDD::Result::Expectations::Mixin::Methods
 
     module Addons
-      module Continuable
+      module Continue
         private def Continue(**value)
           Success.new(type: :continued, value: value, subject: self)
         end
       end
 
-      OPTIONS = { continue: Continuable }.freeze
+      module Given
+        private def Given(*values)
+          value = values.map(&:to_h).reduce({}) { |acc, val| acc.merge(val) }
+
+          Success.new(type: :given, value: value, subject: self)
+        end
+      end
+
+      OPTIONS = { continue: Continue, given: Given }.freeze
 
       def self.options(config_flags)
         ::BCDD::Result::Config::Options.addon(map: config_flags, from: OPTIONS)

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

@@ -13,15 +13,15 @@ class BCDD::Result::Context
         _ResultAs(Failure, type, value)
       end
 
-      private def _ResultAs(kind_class, type, value, halted: nil)
-        kind_class.new(type: type, value: value, subject: self, halted: halted)
+      private def _ResultAs(kind_class, type, value, terminal: nil)
+        kind_class.new(type: type, value: value, subject: self, terminal: terminal)
       end
     end
 
     module Addons
-      module Continuable
+      module Continue
         def Success(type, **value)
-          _ResultAs(Success, type, value, halted: true)
+          _ResultAs(Success, type, value, terminal: true)
         end
 
         private def Continue(**value)
@@ -29,7 +29,15 @@ class BCDD::Result::Context
         end
       end
 
-      OPTIONS = { continue: Continuable }.freeze
+      module Given
+        private def Given(*values)
+          value = values.map(&:to_h).reduce({}) { |acc, val| acc.merge(val) }
+
+          _ResultAs(Success, :given, value)
+        end
+      end
+
+      OPTIONS = { continue: Continue, given: Given }.freeze
 
       def self.options(config_flags)
         ::BCDD::Result::Config::Options.addon(map: config_flags, from: OPTIONS)

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

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

data/lib/bcdd/result/context.rb

@@ -15,7 +15,7 @@ class BCDD::Result
       Failure.new(type: type, value: value)
     end
 
-    def initialize(type:, value:, subject: nil, expectations: nil, halted: nil)
+    def initialize(type:, value:, subject: nil, expectations: nil, terminal: nil)
       value.is_a?(::Hash) or raise ::ArgumentError, 'value must be a Hash'
 
       @acc = {}

data/lib/bcdd/result/expectations/mixin.rb

@@ -24,25 +24,31 @@ class BCDD::Result
 
       FACTORY = <<~RUBY
         private def _Result
-          @_Result ||= Result.with(subject: self, halted: %<halted>s)
+          @_Result ||= Result.with(subject: self, terminal: %<terminal>s)
         end
       RUBY
 
       def self.to_eval(addons)
-        halted = addons.key?(:continue) ? 'true' : 'nil'
+        terminal = addons.key?(:continue) ? 'true' : 'nil'
 
-        "#{BASE}\n#{format(FACTORY, halted: halted)}"
+        "#{BASE}\n#{format(FACTORY, terminal: terminal)}"
       end
     end
 
     module Addons
-      module Continuable
+      module Continue
         private def Continue(value)
           Success.new(type: :continued, value: value, subject: self)
         end
       end
 
-      OPTIONS = { continue: Continuable }.freeze
+      module Given
+        private def Given(value)
+          Success.new(type: :given, value: value, subject: self)
+        end
+      end
+
+      OPTIONS = { continue: Continue, given: Given }.freeze
 
       def self.options(config_flags)
         Config::Options.addon(map: config_flags, from: OPTIONS)

data/lib/bcdd/result/expectations.rb

@@ -38,8 +38,8 @@ class BCDD::Result
 
     private_class_method :mixin!, :mixin_module, :result_factory_without_expectations
 
-    def initialize(subject: nil, contract: nil, halted: nil, **options)
-      @halted = halted
+    def initialize(subject: nil, contract: nil, terminal: nil, **options)
+      @terminal = terminal
 
       @subject = subject
 
@@ -60,16 +60,16 @@ class BCDD::Result
       _ResultAs(Failure, type, value)
     end
 
-    def with(subject:, halted: nil)
-      self.class.new(subject: subject, halted: halted, contract: contract)
+    def with(subject:, terminal: nil)
+      self.class.new(subject: subject, terminal: terminal, contract: contract)
     end
 
     private
 
     def _ResultAs(kind_class, type, value)
-      kind_class.new(type: type, value: value, subject: subject, expectations: contract, halted: halted)
+      kind_class.new(type: type, value: value, subject: subject, expectations: contract, terminal: terminal)
     end
 
-    attr_reader :subject, :halted, :contract
+    attr_reader :subject, :terminal, :contract
   end
 end

data/lib/bcdd/result/mixin.rb

@@ -20,15 +20,15 @@ class BCDD::Result
         _ResultAs(Failure, type, value)
       end
 
-      private def _ResultAs(kind_class, type, value, halted: nil)
-        kind_class.new(type: type, value: value, subject: self, halted: halted)
+      private def _ResultAs(kind_class, type, value, terminal: nil)
+        kind_class.new(type: type, value: value, subject: self, terminal: terminal)
       end
     end
 
     module Addons
-      module Continuable
+      module Continue
         def Success(type, value = nil)
-          _ResultAs(Success, type, value, halted: true)
+          _ResultAs(Success, type, value, terminal: true)
         end
 
         private def Continue(value)
@@ -36,7 +36,13 @@ class BCDD::Result
         end
       end
 
-      OPTIONS = { continue: Continuable }.freeze
+      module Given
+        private def Given(value)
+          _ResultAs(Success, :given, value)
+        end
+      end
+
+      OPTIONS = { continue: Continue, given: Given }.freeze
 
       def self.options(config_flags)
         Config::Options.addon(map: config_flags, from: OPTIONS)

data/lib/bcdd/result/version.rb

@@ -2,6 +2,6 @@
 
 module BCDD
   class Result
-    VERSION = '0.10.0'
+    VERSION = '0.11.0'
   end
 end

data/lib/bcdd/result.rb

@@ -16,7 +16,7 @@ require_relative 'result/config'
 class BCDD::Result
   attr_accessor :unknown, :transitions
 
-  attr_reader :subject, :data, :type_checker, :halted
+  attr_reader :subject, :data, :type_checker, :terminal
 
   protected :subject
 
@@ -32,12 +32,12 @@ class BCDD::Result
     config.freeze
   end
 
-  def initialize(type:, value:, subject: nil, expectations: nil, halted: nil)
+  def initialize(type:, value:, subject: nil, expectations: nil, terminal: nil)
     data = Data.new(kind, type, value)
 
     @type_checker = Contract.evaluate(data, expectations)
     @subject = subject
-    @halted = halted || kind == :failure
+    @terminal = terminal || kind == :failure
     @data = data
 
     self.unknown = true
@@ -46,8 +46,8 @@ class BCDD::Result
     Transitions.tracking.record(self)
   end
 
-  def halted?
-    halted
+  def terminal?
+    terminal
   end
 
   def type
@@ -89,7 +89,7 @@ class BCDD::Result
   end
 
   def and_then(method_name = nil, context = nil, &block)
-    return self if halted?
+    return self if terminal?
 
     method_name && block and raise ::ArgumentError, 'method_name and block are mutually exclusive'
 

data/sig/bcdd/result/config.rbs

@@ -73,6 +73,7 @@ class BCDD::Result::Config::Switcher
 end
 
 module BCDD::Result::Config::Addons
+  AFFECTS: Array[String]
   OPTIONS: Hash[String, Hash[Symbol, untyped]]
 
   def self.switcher: -> BCDD::Result::Config::Switcher

data/sig/bcdd/result/context.rbs

@@ -10,7 +10,7 @@ class BCDD::Result::Context < BCDD::Result
     value: untyped,
     ?subject: untyped,
     ?expectations: BCDD::Result::Contract::Evaluator,
-    ?halted: bool
+    ?terminal: bool
   ) -> void
 
   def and_then: (?Symbol, **untyped) ?{ (Hash[Symbol, untyped]) -> untyped } -> BCDD::Result::Context
@@ -27,7 +27,7 @@ class BCDD::Result::Context
   class Success < BCDD::Result::Context
     include BCDD::Result::Success::Methods
 
-    def and_expose: (Symbol, Array[Symbol], halted: bool) -> BCDD::Result::Context::Success
+    def and_expose: (Symbol, Array[Symbol], terminal: bool) -> BCDD::Result::Context::Success
   end
 
   def self.Success: (Symbol, **untyped) -> BCDD::Result::Context::Success
@@ -54,11 +54,11 @@ class BCDD::Result::Context
 
       private
 
-      def _ResultAs: (singleton(BCDD::Result::Context), Symbol, untyped, ?halted: bool) -> untyped
+      def _ResultAs: (singleton(BCDD::Result::Context), Symbol, untyped, ?terminal: bool) -> untyped
     end
 
     module Addons
-      module Continuable
+      module Continue
         include BCDD::Result::Context::Mixin::Methods
 
         private
@@ -66,6 +66,14 @@ class BCDD::Result::Context
         def Continue: (**untyped) -> BCDD::Result::Context::Success
       end
 
+      module Given
+        include BCDD::Result::Context::Mixin::Methods
+
+        private
+
+        def Given: (*untyped) -> BCDD::Result::Context::Success
+      end
+
       OPTIONS: Hash[Symbol, Module]
 
       def self.options: (Hash[Symbol, Hash[Symbol, bool]]) -> Hash[Symbol, Module]
@@ -91,10 +99,14 @@ module BCDD::Result::Context::Expectations::Mixin
   Factory: singleton(BCDD::Result::Expectations::Mixin::Factory)
 
   module Addons
-    module Continuable
+    module Continue
       private def Continue: (**untyped) -> BCDD::Result::Context::Success
     end
 
+    module Given
+      private def Given: (*untyped) -> BCDD::Result::Context::Success
+    end
+
     OPTIONS: Hash[Symbol, Module]
 
     def self.options: (Hash[Symbol, Hash[Symbol, bool]]) -> Hash[Symbol, Module]

data/sig/bcdd/result/expectations.rbs

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

data/sig/bcdd/result/mixin.rbs

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

data/sig/bcdd/result.rbs

@@ -5,7 +5,7 @@ class BCDD::Result
 
   attr_reader data: BCDD::Result::Data
   attr_reader subject: untyped
-  attr_reader halted: bool
+  attr_reader terminal: bool
   attr_reader transitions: Hash[Symbol, untyped]
 
   def self.config: -> BCDD::Result::Config
@@ -16,13 +16,13 @@ class BCDD::Result
     value: untyped,
     ?subject: untyped,
     ?expectations: BCDD::Result::Contract::Evaluator,
-    ?halted: bool
+    ?terminal: bool
   ) -> void
 
   def type: -> Symbol
   def value: -> untyped
 
-  def halted?: -> bool
+  def terminal?: -> bool
   def success?: (?Symbol type) -> bool
   def failure?: (?Symbol type) -> bool
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bcdd-result
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.11.0
 platform: ruby
 authors:
 - Rodrigo Serradura
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-12-31 00:00:00.000000000 Z
+date: 2024-01-02 00:00:00.000000000 Z
 dependencies: []
 description: Empower Ruby apps with pragmatic use of Result pattern (monad), Railway
   Oriented Programming, and B/CDD.