bcdd-result 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b4eb0878d2e7d75bb4cfd55c0d112db0f14b4c43255d3e02d60ec60c0f9c2d6e
-  data.tar.gz: dd8ee0d7239a63b486de7efb7876c40db1942f2d54a383ed0c67bb86e20b0622
+  metadata.gz: d43af37c2ffd8d2764fc62039ac1d3e4398b2872fa25bc80192a9aca1b08dfb5
+  data.tar.gz: 8aaab364445f279d207390479bce6680c4ed4b7fe4b2fc026e203ddece47a398
 SHA512:
-  metadata.gz: '08f8ed0b78bcf298711a52b20be08908dc3000888a94b8bd3df289fa3682909bb87ba294c2ba42a482678af0f9dd5bff5a267169a256ca7cb0a23c40b961613c'
-  data.tar.gz: cc15020416823a965c29ece5947875817df0ccc6b7c21f4dc534ba24aa68e10134a4333d0e36bcb8afc08719f9e6aeea1741ea51be6b373cc8efc61e82b08a7f
+  metadata.gz: 6dbac4fdded1e36d6f2af6e5c7e0d0bebfe44b489410a35445935c8da656fe244fca7a6e769a5b73d6070929e790be420887b2576cb9b523a798fe3ff759e564
+  data.tar.gz: 12055de39a9a3a93f69670da7b3a93a0e3749568590be14d02ce750cb5b5e5b00c7b56da422941bdea8842b073573e589d2a11681496f18f7160ddeaf3ceb7bb

data/.rubocop.yml

@@ -18,10 +18,6 @@ Layout/ExtraSpacing:
 Style/ClassAndModuleChildren:
   Enabled: false
 
-Style/MapToSet:
-  Exclude:
-    - lib/bcdd/result/expectations/contract/for_types.rb
-
 Style/CaseEquality:
   Exclude:
     - lib/bcdd/result/expectations/contract/for_types_and_values.rb
@@ -29,13 +25,21 @@ Style/CaseEquality:
 Style/Lambda:
   EnforcedStyle: literal
 
+Style/MapToSet:
+  Exclude:
+    - lib/bcdd/result/expectations/contract/for_types.rb
+
+Style/MixinGrouping:
+  Enabled: false
+
+Style/AccessModifierDeclarations:
+  Enabled: false
+
 Naming/MethodName:
   Exclude:
     - lib/bcdd/result/mixin.rb
     - lib/bcdd/result/expectations.rb
-
-Minitest/MultipleAssertions:
-  Enabled: false
+    - lib/bcdd/result/expectations/mixin.rb
 
 Metrics/BlockLength:
   Exclude:
@@ -45,3 +49,6 @@ Metrics/BlockLength:
 Metrics/ClassLength:
   Exclude:
     - test/**/*.rb
+
+Minitest/MultipleAssertions:
+  Enabled: false

data/CHANGELOG.md

@@ -1,7 +1,27 @@
 ## [Unreleased]
 
+## [0.6.0] - 2023-10-11
+
+### Added
+
+- Add `BCDD::Result.mixin` to be included or extended in any object. It will add `Success()` and `Failure()` to the target object (the object who receives the include/extend).
+
+- Add `BCDD::Result.mixin(with: :Continue)`. This addon will add a `Continue(value)` method to the target object to produce a `Success(:continued, value)` result.
+
+- Add `BCDD::Result::Expectations.mixin(with: :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.
+
+- Increase the arity of `BCDD::Result#and_then`. Now, it can receive a second argument (a value to be injected and shared with the subject's method).
+
+- Increase the arity (maximum of 2) for the methods called through `BCDD::Result#and_then`. The second argument is the value injected by `BCDD::Result#and_then`.
+
+### Changed
+
+- **(BREAKING)** Make `BCDD::Result::Mixin` be a private constant. The `BCDD::Result.mixin` method is the new way to use it.
+
 ## [0.5.0] - 2023-10-09
 
+### Added
+
 - Add `BCDD::Result::Expectations` to define contracts for your results. There are two ways to use it: the standalone (`BCDD::Result::Expectations.new`) and the mixin (`BCDD::Result::Expectations.mixin`) mode.
 
 The main difference is that the mixin mode will use the target object (who receives the include/extend) as the result's subject (like the `BCDD::Result::Mixin` does), while the standalone mode won't.
@@ -152,8 +172,7 @@ end
 
 ```ruby
 module Divide
-  extend BCDD::Resultable
-  extend self
+  extend self, BCDD::Resultable
 
   def call(arg1, arg2)
     validate_numbers(arg1, arg2)

data/README.md

@@ -3,7 +3,7 @@
   <p align="center"><i>Empower Ruby apps with a pragmatic use of Railway Oriented Programming.</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">
-    <img src="https://badge.fury.io/rb/bcdd-result.svg" alt="bcdd-result gem version" height="18">
+    <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>
   </p>
 </p>
 
@@ -37,10 +37,12 @@ Use it to enable the [Railway Oriented Programming](https://fsharpforfunandprofi
     - [`result.data`](#resultdata)
   - [Railway Oriented Programming](#railway-oriented-programming)
     - [`result.and_then`](#resultand_then)
-    - [`BCDD::Result::Mixin`](#bcddresultmixin)
+    - [`BCDD::Result.mixin`](#bcddresultmixin)
       - [Class example (Instance Methods)](#class-example-instance-methods)
       - [Module example (Singleton Methods)](#module-example-singleton-methods)
-      - [Restrictions](#restrictions)
+      - [Important Requirement](#important-requirement)
+      - [Dependency Injection](#dependency-injection)
+      - [Addons](#addons)
   - [Pattern Matching](#pattern-matching)
     - [`Array`/`Find` patterns](#arrayfind-patterns)
     - [`Hash` patterns](#hash-patterns)
@@ -58,6 +60,7 @@ 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)
 - [About](#about)
 - [Development](#development)
 - [Contributing](#contributing)
@@ -521,9 +524,9 @@ Divide.call(2, 2)
 
 <p align="right"><a href="#-bcddresult">⬆️ &nbsp;back to top</a></p>
 
-#### `BCDD::Result::Mixin`
+#### `BCDD::Result.mixin`
 
-It is 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 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.
 
 And because of this, you can use the `#and_then` method to call methods from the result's subject.
 
@@ -531,7 +534,7 @@ And because of this, you can use the `#and_then` method to call methods from the
 
 ```ruby
 class Divide
-  include BCDD::Result::Mixin
+  include BCDD::Result.mixin
 
   attr_reader :arg1, :arg2
 
@@ -579,8 +582,7 @@ Divide.new(4, '2').call #<BCDD::Result::Failure type=:invalid_arg value="arg2 mu
 
 ```ruby
 module Divide
-  extend BCDD::Result::Mixin
-  extend self
+  extend self, BCDD::Result.mixin
 
   def call(arg1, arg2)
     validate_numbers(arg1, arg2)
@@ -615,7 +617,9 @@ Divide.call('4', 2) #<BCDD::Result::Failure type=:invalid_arg value="arg1 must b
 Divide.call(4, '2') #<BCDD::Result::Failure type=:invalid_arg value="arg2 must be numeric">
 ```
 
-##### Restrictions
+<p align="right"><a href="#-bcddresult">⬆️ &nbsp;back to top</a></p>
+
+##### 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.
 
@@ -625,6 +629,104 @@ If you use `BCDD::Result::Subject()`/`BCDD::Result::Failure()`, or use result fr
 
 <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.
+
+```ruby
+require 'logger'
+
+module Divide
+  extend self, BCDD::Result.mixin
+
+  def call(arg1, arg2, logger: ::Logger.new(STDOUT))
+    validate_numbers(arg1, arg2)
+      .and_then(:validate_non_zero, logger)
+      .and_then(:divide, logger)
+  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_non_zero(numbers, logger)
+    if numbers.last.zero?
+      logger.error('arg2 must not be zero')
+
+      Failure(:division_by_zero, 'arg2 must not be zero')
+    else
+      logger.info('The numbers are valid')
+
+      Success(:ok, numbers)
+    end
+  end
+
+  def divide((number1, number2), logger)
+    division = number1 / number2
+
+    logger.info("The division result is #{division}")
+
+    Success(:division_completed, division)
+  end
+end
+
+Divide.call(4, 2)
+# I, [2023-10-11T00:08:05.546237 #18139]  INFO -- : The numbers are valid
+# I, [2023-10-11T00:08:05.546337 #18139]  INFO -- : The division result is 2
+#=> #<BCDD::Result::Success type=:division_completed value=2>
+
+Divide.call(4, 2, logger: Logger.new(IO::NULL))
+#=> #<BCDD::Result::Success type=:division_completed value=2>
+```
+
+<p align="right"><a href="#-bcddresult">⬆️ &nbsp;back to top</a></p>
+
+##### Addons
+
+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.
+
+**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)
+
+  def call(arg1, arg2)
+    validate_numbers(arg1, arg2)
+      .and_then(:validate_non_zero)
+      .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')
+
+    Continue([arg1, arg2])
+  end
+
+  def validate_non_zero(numbers)
+    return Continue(numbers) unless numbers.last.zero?
+
+    Failure(:division_by_zero, 'arg2 must not be zero')
+  end
+
+  def divide((number1, number2))
+    Success(:division_completed, number1 / number2)
+  end
+end
+```
+
+<p align="right"><a href="#-bcddresult">⬆️ &nbsp;back to top</a></p>
+
 ### Pattern Matching
 
 The `BCDD::Result` also provides support to pattern matching.
@@ -1071,6 +1173,61 @@ Divide::Expected::Failure(:division_by_zero, msg: 'arg2 must not be zero')
 
 <p align="right"><a href="#-bcddresult">⬆️ &nbsp;back to top</a></p>
 
+#### `BCDD::Result::Expectations.mixin` Addons
+
+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.
+
+**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.
+
+```ruby
+class Divide
+  include BCDD::Result::Expectations.mixin(
+    with: :Continue,
+    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(: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')
+
+    Continue([arg1, arg2])
+  end
+
+  def validate_non_zero(numbers)
+    return Continue(numbers) unless numbers.last.zero?
+
+    Failure(:division_by_zero, 'arg2 must not be zero')
+  end
+
+  def divide((number1, number2))
+    Success(:division_completed, number1 / number2)
+  end
+end
+
+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.
+# But look at the allowed types have only one type (:division_completed).
+# 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)
+```
+
+<p align="right"><a href="#-bcddresult">⬆️ &nbsp;back to top</a></p>
+
 ## About
 
 [Rodrigo Serradura](https://github.com/serradura) created this project. He is the B/CDD process/method creator and has already made similar gems like the [u-case](https://github.com/serradura/u-case) and [kind](https://github.com/serradura/kind/blob/main/lib/kind/result.rb). This gem is a general-purpose abstraction/monad, but it also contains key features that serve as facilitators for adopting B/CDD in the code.

data/lib/bcdd/result/error.rb

@@ -38,7 +38,7 @@ class BCDD::Result::Error < StandardError
 
   class WrongSubjectMethodArity < self
     def self.build(subject:, method:)
-      new("#{subject.class}##{method.name} has unsupported arity (#{method.arity}). Expected 0 or 1.")
+      new("#{subject.class}##{method.name} has unsupported arity (#{method.arity}). Expected 0, 1 or 2.")
     end
   end
 

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

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+class BCDD::Result::Expectations
+  module Mixin
+    METHODS = <<~RUBY
+      def Success(...)
+        __expected::Success(...)
+      end
+
+      def Failure(...)
+        __expected::Failure(...)
+      end
+
+      private
+
+      def __expected
+        @__expected ||= Expected.with(subject: self)
+      end
+    RUBY
+
+    module Addons
+      module Continuable
+        private def Continue(value)
+          ::BCDD::Result::Success.new(type: :continued, value: value, subject: self)
+        end
+      end
+
+      OPTIONS = { Continue: Continuable }.freeze
+
+      def self.options(names)
+        Array(names).filter_map { |name| OPTIONS[name] }
+      end
+    end
+  end
+
+  private_constant :Mixin
+end

data/lib/bcdd/result/expectations.rb

@@ -1,30 +1,18 @@
 # frozen_string_literal: true
 
 class BCDD::Result::Expectations
+  require_relative 'expectations/mixin'
   require_relative 'expectations/error'
   require_relative 'expectations/contract'
   require_relative 'expectations/type_checker'
 
-  MIXIN_METHODS = <<~RUBY
-    def Success(...)
-      _expected_result::Success(...)
-    end
+  def self.mixin(success: nil, failure: nil, with: nil)
+    addons = Mixin::Addons.options(with)
 
-    def Failure(...)
-      _expected_result::Failure(...)
-    end
-
-    private
-
-    def _expected_result
-      @_expected_result ||= Expected.with(subject: self)
-    end
-  RUBY
-
-  def self.mixin(success: nil, failure: nil)
     mod = Module.new
     mod.const_set(:Expected, new(success: success, failure: failure).freeze)
-    mod.module_eval(MIXIN_METHODS)
+    mod.module_eval(Mixin::METHODS)
+    mod.send(:include, *addons) unless addons.empty?
     mod
   end
 

data/lib/bcdd/result/mixin.rb

@@ -2,12 +2,39 @@
 
 class BCDD::Result
   module Mixin
-    def Success(type, value = nil)
-      Success.new(type: type, value: value, subject: self)
+    module Methods
+      def Success(type, value = nil)
+        Success.new(type: type, value: value, subject: self)
+      end
+
+      def Failure(type, value = nil)
+        Failure.new(type: type, value: value, subject: self)
+      end
     end
 
-    def Failure(type, value = nil)
-      Failure.new(type: type, value: value, subject: self)
+    module Addons
+      module Continuable
+        private def Continue(value)
+          Success(:continued, value)
+        end
+      end
+
+      OPTIONS = { Continue: Continuable }.freeze
+
+      def self.options(names)
+        Array(names).filter_map { |name| OPTIONS[name] }
+      end
     end
   end
+
+  def self.mixin(with: nil)
+    addons = Mixin::Addons.options(with)
+
+    mod = Module.new
+    mod.send(:include, Mixin::Methods)
+    mod.send(:include, *addons) unless addons.empty?
+    mod
+  end
+
+  private_constant :Mixin
 end

data/lib/bcdd/result/version.rb

@@ -2,6 +2,6 @@
 
 module BCDD
   class Result
-    VERSION = '0.5.0'
+    VERSION = '0.6.0'
   end
 end

data/lib/bcdd/result.rb

@@ -66,10 +66,12 @@ class BCDD::Result
     tap { yield(value, type) if unknown }
   end
 
-  def and_then(method_name = nil)
+  def and_then(method_name = nil, context = nil)
     return self if failure?
 
-    return call_subject_method(method_name) if method_name
+    method_name && block_given? and raise ArgumentError, 'method_name and block are mutually exclusive'
+
+    return call_subject_method(method_name, context) if method_name
 
     result = yield(value)
 
@@ -119,13 +121,14 @@ class BCDD::Result
     block.call(value, type)
   end
 
-  def call_subject_method(method_name)
+  def call_subject_method(method_name, context)
     method = subject.method(method_name)
 
     result =
       case method.arity
       when 0 then subject.send(method_name)
       when 1 then subject.send(method_name, value)
+      when 2 then subject.send(method_name, value, context)
       else raise Error::WrongSubjectMethodArity.build(subject: subject, method: method)
       end
 

data/sig/bcdd/result.rbs

@@ -31,7 +31,7 @@ class BCDD::Result
   def on_failure: (*Symbol) { (untyped, Symbol) -> void } -> BCDD::Result
   def on_unknown: () { (untyped, Symbol) -> void } -> BCDD::Result
 
-  def and_then: (?Symbol method_name) { (untyped) -> untyped } -> BCDD::Result
+  def and_then: (?Symbol method_name, ?untyped context) ?{ (untyped) -> untyped } -> BCDD::Result
 
   def handle: () { (BCDD::Result::Handler) -> void } -> untyped
 
@@ -49,7 +49,7 @@ class BCDD::Result
 
   def name: -> Symbol
   def known: (Proc) -> untyped
-  def call_subject_method: (Symbol) -> BCDD::Result
+  def call_subject_method: (Symbol, untyped) -> BCDD::Result
   def ensure_result_object: (untyped, origin: Symbol) -> BCDD::Result
 end
 
@@ -69,10 +69,26 @@ end
 
 class BCDD::Result
   module Mixin
-    def Success: (Symbol type, ?untyped value) -> BCDD::Result::Success
+    module Methods
+      def Success: (Symbol type, ?untyped value) -> BCDD::Result::Success
 
-    def Failure: (Symbol type, ?untyped value) -> BCDD::Result::Failure
+      def Failure: (Symbol type, ?untyped value) -> BCDD::Result::Failure
+    end
+
+    module Addons
+      module Continuable
+        include BCDD::Result::Mixin::Methods
+
+        private def Continue: (untyped) -> BCDD::Result::Success
+      end
+
+      OPTIONS: Hash[Symbol, Module]
+
+      def self.options: (Array[Symbol]) -> Array[Module]
+    end
   end
+
+  def self.mixin: (?with: Array[Symbol]) -> Module
 end
 
 class BCDD::Result
@@ -201,6 +217,20 @@ class BCDD::Result::Expectations
   attr_reader contract: BCDD::Result::Expectations::Contract::Evaluator
 end
 
+module BCDD::Result::Expectations::Mixin
+  METHODS: String
+
+  module Addons
+    module Continuable
+      private def Continue: (untyped) -> BCDD::Result::Success
+    end
+
+    OPTIONS: Hash[Symbol, Module]
+
+    def self.options: (Array[Symbol]) -> Array[Module]
+  end
+end
+
 module BCDD::Result::Expectations::Contract
   NONE: BCDD::Result::Expectations::Contract::Evaluator
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bcdd-result
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Rodrigo Serradura
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-10-10 00:00:00.000000000 Z
+date: 2023-10-11 00:00:00.000000000 Z
 dependencies: []
 description: |-
   Empower Ruby apps with a pragmatic use of Railway Oriented Programming.
@@ -39,6 +39,7 @@ files:
 - lib/bcdd/result/expectations/contract/for_types_and_values.rb
 - lib/bcdd/result/expectations/contract/interface.rb
 - lib/bcdd/result/expectations/error.rb
+- lib/bcdd/result/expectations/mixin.rb
 - lib/bcdd/result/expectations/type_checker.rb
 - lib/bcdd/result/failure.rb
 - lib/bcdd/result/handler.rb