bcdd-result 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e27dee9c053eeb9f6025b17e09eede49ca6cbc69cd9120947bad34b26a79859d
-  data.tar.gz: c8c080d43a3eb46139f7bf5299c64346809d1c0df4bf0181ccb02ba3005d5ee0
+  metadata.gz: 96c58d6a9132fbf42fc8f3c1d9ba683f0b6297e23b1f0536fc4bcb7efb5084df
+  data.tar.gz: fcef45f3c5ddacc20ff5e9533012c7fbe5817878cef1ff528dabd8920e1cbccd
 SHA512:
-  metadata.gz: 253e14ef154c2b863bb65139134a903b2a6fd035fb7a995158cf5ebab395d6ba2bd9f8e999c29305f2d2cd2f6e10db9923166a13d1f06e627df276c87c7a644d
-  data.tar.gz: 7d62559447a5ee3cb665713645f1db7729428f9cf94bd349574758ea3f9bae361f65a218640b2d5bfeb138ef108c27dec426a44ec89dbc971620671b6eab945c
+  metadata.gz: d4cf048907571205c6cd0b90ca4b95c2480c34de79d082132e4f1cab1e809f4c6eec538d9d38b036ad313d9653420625b68a502272e73371b99b157f43315123
+  data.tar.gz: 4662aaeb33a7eb770ab51529cc1f2c4e9d86844dec70dfcdc4f37674aab33d010d6cbe7932fc635f09979d47b4b631748a3d4791021e99108a011a93469a2d73

data/.rubocop.yml

@@ -18,5 +18,9 @@ Layout/ExtraSpacing:
 Style/ClassAndModuleChildren:
   Enabled: false
 
+Naming/MethodName:
+  Exclude:
+    - lib/bcdd/resultable.rb
+
 Minitest/MultipleAssertions:
   Enabled: false

data/.rubocop_todo.yml

@@ -1,19 +1,21 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2023-09-23 03:05:24 UTC using RuboCop version 1.56.3.
+# on 2023-09-27 00:47:03 UTC using RuboCop version 1.56.3.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
 # versions of RuboCop, may require this file to be generated again.
 
-# Offense count: 8
+# Offense count: 13
 # Configuration parameters: AllowedConstants.
 Style/Documentation:
   Exclude:
     - 'spec/**/*'
     - 'test/**/*'
     - 'lib/bcdd/result.rb'
-    - 'lib/bcdd/result/base.rb'
     - 'lib/bcdd/result/error.rb'
     - 'lib/bcdd/result/failure.rb'
+    - 'lib/bcdd/result/handler.rb'
     - 'lib/bcdd/result/success.rb'
+    - 'lib/bcdd/result/type.rb'
+    - 'lib/bcdd/resultable.rb'

data/CHANGELOG.md

@@ -1,5 +1,105 @@
 ## [Unreleased]
 
+## [0.3.0] - 2023-09-26
+
+### Added
+
+- Add `BCDD::Result#handle`. This method allows defining blocks for each hook (type, failure, success), but instead of returning the result itself, it will return the output of the first match/block execution.
+
+## [0.2.0] - 2023-09-26
+
+### Added
+
+- Add `BCDD::Resultable`. This module can add `Success()` and `Failure()` in any object. The target object will be the subject of the result object produced by these methods.
+
+**Classes (instance methods)**
+
+```ruby
+class Divide
+  include BCDD::Resultable
+
+  attr_reader :arg1, :arg2
+
+  def initialize(arg1, arg2)
+    @arg1 = arg1
+    @arg2 = arg2
+  end
+
+  def call
+    validate_numbers
+      .and_then(:validate_non_zero)
+      .and_then(:divide)
+  end
+
+  private
+
+  def validate_numbers
+    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)
+    return Success(:ok, 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
+```
+
+**Module (singleton methods)**
+
+```ruby
+module Divide
+  extend BCDD::Resultable
+  extend self
+
+  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')
+
+    Success(:ok, [arg1, arg2])
+  end
+
+  def validate_non_zero(numbers)
+    return Success(:ok, 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
+```
+
+- Make the `BCDD::Result#initialize` enabled to receive a subject.
+
+- Make the `BCDD::Result#and_then` method receive a method name (symbol) and perform it on the result subject (added by `BCDD::Resultable`). The called method must return a result; otherwise, an error (`BCDD::Result::Error::UnexpectedOutcome`) will be raised.
+
+- Add `BCDD::Result::Error::UnexpectedOutcome` to represent an unexpected outcome.
+
+- Add `BCDD::Result::Error::WrongResultSubject` to represent a wrong result subject. When using `BCDD::Resultable`, the result subject must be the same as the target object.
+
+- Add `BCDD::Result::Error::WrongSubjectMethodArity` to represent a wrong subject method arity. Valid arities are 0 and 1.
+
+### Removed
+
+- **(BREAKING)** Remove `BCDD::Result::Error::UnexpectedBlockOutcome`. It was replaced by `BCDD::Result::Error::UnexpectedOutcome`.
+
 ## [0.1.0] - 2023-09-25
 
 ### Added

data/README.md

@@ -1,4 +1,8 @@
-# BCDD::Result <!-- omit in toc -->
+<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>
+  <br>
+</p>
 
 A general-purpose result monad that allows you to create objects that represent a success (`BCDD::Result::Success`) or failure (`BCDD::Result::Failure`).
 
@@ -6,8 +10,11 @@ A general-purpose result monad that allows you to create objects that represent
 
 It allows you to consistently represent the concept of success and failure throughout your codebase.
 
-Furthermore, this abstraction exposes several methods that will be useful to make the code flow react clearly and cleanly to the result represented by these objects.
+Furthermore, this abstraction exposes several features that will be useful to make the application flow react cleanly and securely to the result represented by these objects.
 
+Use it to enable the [Railway Oriented Programming](https://fsharpforfunandprofit.com/rop/) pattern (superpower) in your code.
+
+- [Ruby Version](#ruby-version)
 - [Installation](#installation)
 - [Usage](#usage)
 - [Reference](#reference)
@@ -18,28 +25,44 @@ Furthermore, this abstraction exposes several methods that will be useful to mak
     - [`result.on_type`](#resulton_type)
     - [`result.on_success`](#resulton_success)
     - [`result.on_failure`](#resulton_failure)
-  - [Result value](#result-value)
+    - [`result.handle`](#resulthandle)
+  - [Result Value](#result-value)
     - [`result.value_or`](#resultvalue_or)
     - [`result.data_or`](#resultdata_or)
   - [Railway Oriented Programming](#railway-oriented-programming)
     - [`result.and_then`](#resultand_then)
+    - [`BCDD::Resultable`](#bcddresultable)
+      - [Class example (instance methods)](#class-example-instance-methods)
+      - [Module example (singleton methods)](#module-example-singleton-methods)
+      - [Restrictions](#restrictions)
 - [About](#about)
 - [Development](#development)
 - [Contributing](#contributing)
 - [License](#license)
 - [Code of Conduct](#code-of-conduct)
 
+## Ruby Version
+
+`>= 2.7.0`
 
 ## Installation
 
-Install the gem and add to the application's Gemfile by executing:
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'bcdd-result', require: 'bcdd/result'
+```
+
+And then execute:
 
-    $ bundle add bcdd-result
+    $ bundle install
 
 If bundler is not being used to manage dependencies, install the gem by executing:
 
     $ gem install bcdd-result
 
+<p align="right">(<a href="#-bcddresult">⬆️ &nbsp;back to top</a>)</p>
+
 ## Usage
 
 To create a result, you must define a type (symbol) and its value (any kind of object). e.g.,
@@ -58,7 +81,7 @@ BCDD::Result::Success(:ok)  #
 BCDD::Result::Failure(:err) #
 ```
 
-<p align="right">(<a href="#bcddresult-">⬆️ &nbsp;back to top</a>)</p>
+<p align="right">(<a href="#-bcddresult">⬆️ &nbsp;back to top</a>)</p>
 
 ## Reference
 
@@ -114,7 +137,7 @@ result.type     # :no
 result.value    # nil
 ```
 
-<p align="right">(<a href="#bcddresult-">⬆️ &nbsp;back to top</a>)</p>
+<p align="right">(<a href="#-bcddresult">⬆️ &nbsp;back to top</a>)</p>
 
 #### Receiving types in `result.success?` or `result.failure?`
 
@@ -140,7 +163,7 @@ result.failure?(:err)   # true
 result.failure?(:error) # false
 ```
 
-<p align="right">(<a href="#bcddresult-">⬆️ &nbsp;back to top</a>)</p>
+<p align="right">(<a href="#-bcddresult">⬆️ &nbsp;back to top</a>)</p>
 
 ### Result Hooks
 
@@ -159,6 +182,8 @@ def divide(arg1, arg2)
 end
 ```
 
+<p align="right">(<a href="#-bcddresult">⬆️ &nbsp;back to top</a>)</p>
+
 #### `result.on`
 
 `BCDD::Result#on` will perform the block when the type matches the result type.
@@ -193,7 +218,9 @@ output =
 result.object_id == output.object_id # true
 ```
 
-<p align="right">(<a href="#bcddresult-">⬆️ &nbsp;back to top</a>)</p>
+*PS: The `divide()` implementation is [here](#result-hooks).*
+
+<p align="right">(<a href="#-bcddresult">⬆️ &nbsp;back to top</a>)</p>
 
 #### `result.on_type`
 
@@ -220,7 +247,9 @@ divide(4, 4).on_success(:ok) { |value| puts value }
 divide(4, 4).on_failure { |error| puts error }
 ```
 
-<p align="right">(<a href="#bcddresult-">⬆️ &nbsp;back to top</a>)</p>
+*PS: The `divide()` implementation is [here](#result-hooks).*
+
+<p align="right">(<a href="#-bcddresult">⬆️ &nbsp;back to top</a>)</p>
 
 #### `result.on_failure`
 
@@ -240,9 +269,57 @@ divide(4, 0).on_success { |number| puts number }
 divide(4, 0).on_failure(:invalid_arg) { |error| puts error }
 ```
 
-<p align="right">(<a href="#bcddresult-">⬆️ &nbsp;back to top</a>)</p>
+*PS: The `divide()` implementation is [here](#result-hooks).*
+
+<p align="right">(<a href="#-bcddresult">⬆️ &nbsp;back to top</a>)</p>
+
+#### `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.
+
+```ruby
+divide(4, 2).handle do |result|
+  result.success { |number| number }
+  result.failure(:invalid_arg) { |err| puts err }
+  result.type(:division_by_zero) { raise ZeroDivisionError }
+end
+
+#or
+
+divide(4, 2).handle do |on|
+  on.success { |number| number }
+  on.failure { |err| puts err }
+end
+
+#or
+
+divide(4, 2).handle do |on|
+  on.type(:invalid_arg) { |err| puts err }
+  on.type(:division_by_zero) { raise ZeroDivisionError }
+  on.type(:division_completed) { |number| number }
+end
+
+# or
+
+divide(4, 2).handle do |on|
+  on[:invalid_arg] { |err| puts err }
+  on[:division_by_zero] { raise ZeroDivisionError }
+  on[:division_completed] { |number| number }
+end
+
+# The [] syntax 👆 is an alias of #type.
+```
+
+**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.
+
+*PS: The `divide()` implementation is [here](#result-hooks).*
+
+<p align="right">(<a href="#-bcddresult">⬆️ &nbsp;back to top</a>)</p>
 
-### Result value
+### Result Value
 
 The most simple way to get the result value is by calling `BCDD::Result#value` or `BCDD::Result#data`.
 
@@ -271,17 +348,16 @@ divide(4, '2').value_or { 0 } # 0
 divide(100, 0).value_or { 0 } # 0
 ```
 
-<p align="right">(<a href="#bcddresult-">⬆️ &nbsp;back to top</a>)</p>
+*PS: The `divide()` implementation is [here](#result-hooks).*
+
+<p align="right">(<a href="#-bcddresult">⬆️ &nbsp;back to top</a>)</p>
 
 #### `result.data_or`
 
 `BCDD::Result#data_or` is an alias of `BCDD::Result#value_or`.
 
-
 ### Railway Oriented Programming
 
-#### `result.and_then`
-
 This feature/pattern is also known as ["Railway Oriented Programming"](https://fsharpforfunandprofit.com/rop/).
 
 The idea is to chain blocks and creates a pipeline of operations that can be interrupted by a failure.
@@ -289,7 +365,9 @@ The idea is to chain blocks and creates a pipeline of operations that can be int
 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.
 
-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. e.g.,
+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.
+
+#### `result.and_then`
 
 ```ruby
 module Divide
@@ -313,7 +391,7 @@ module Divide
   def validate_non_zero(numbers)
     return BCDD::Result::Success(:ok, numbers) unless numbers.last.zero?
 
-    BCDD::Result::Failure(:division_by_zero, "arg2 must not be zero")
+    BCDD::Result::Failure(:division_by_zero, 'arg2 must not be zero')
   end
 
   def divide((number1, number2))
@@ -338,13 +416,119 @@ Divide.call(2, 2)
 #<BCDD::Result::Success type=:division_completed data=1>
 ```
 
-<p align="right">(<a href="#bcddresult-">⬆️ &nbsp;back to top</a>)</p>
+<p align="right">(<a href="#-bcddresult">⬆️ &nbsp;back to top</a>)</p>
+
+#### `BCDD::Resultable`
+
+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 as the result's subject.
+
+And because of this, you can use the `#and_then` method to call methods from the target object (result's subject).
+
+##### Class example (instance methods)
+
+```ruby
+class Divide
+  include BCDD::Resultable
+
+  attr_reader :arg1, :arg2
+
+  def initialize(arg1, arg2)
+    @arg1 = arg1
+    @arg2 = arg2
+  end
+
+  def call
+    validate_numbers
+      .and_then(:validate_non_zero)
+      .and_then(:divide)
+  end
+
+  private
+
+  def validate_numbers
+    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')
+
+    # As arg1 and arg2 are instance methods, they will be available in the instance scope.
+    # So, in this case, I'm passing them as an array to show how the next method can receive the value as its argument.
+    Success(:ok, [arg1, arg2])
+  end
+
+  def validate_non_zero(numbers)
+    return Success(:ok, 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
+
+Divide.new(4, 2).call #<BCDD::Result::Success type=:division_completed value=2>
+
+Divide.new(4, 0).call   #<BCDD::Result::Failure type=:division_by_zero value="arg2 must not be zero">
+Divide.new('4', 2).call #<BCDD::Result::Failure type=:invalid_arg value="arg1 must be numeric">
+Divide.new(4, '2').call #<BCDD::Result::Failure type=:invalid_arg value="arg2 must be numeric">
+```
+
+##### Module example (singleton methods)
+
+```ruby
+module Divide
+  extend BCDD::Resultable
+  extend self
+
+  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')
+
+    Success(:ok, [arg1, arg2])
+  end
+
+  def validate_non_zero(numbers)
+    return Success(:ok, 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
+
+Divide.call(4, 2) #<BCDD::Result::Success type=:division_completed value=2>
+
+Divide.call(4, 0)   #<BCDD::Result::Failure type=:division_by_zero value="arg2 must not be zero">
+Divide.call('4', 2) #<BCDD::Result::Failure type=:invalid_arg value="arg1 must be numeric">
+Divide.call(4, '2') #<BCDD::Result::Failure type=:invalid_arg value="arg2 must be numeric">
+```
+
+##### Restrictions
+
+The unique condition for using the `#and_then` to call methods is that they must use the `Success()` and `Failure()` to produce their results.
+
+If you use `BCDD::Result::Subject()`/`BCDD::Result::Failure()`, or call another `BCDD::Resultable` object, the `#and_then` will raise an error because the subjects will be different.
+
+> **Note**: You still can use the block syntax, but all the results must be produced by the subject's `Success()` and `Failure()` methods.
+
+<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.
 
-<p align="right">(<a href="#bcddresult-">⬆️ &nbsp;back to top</a>)</p>
+<p align="right">(<a href="#-bcddresult">⬆️ &nbsp;back to top</a>)</p>
 
 ## Development
 
@@ -352,19 +536,19 @@ After checking out the repo, run `bin/setup` to install dependencies. Then, run
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
-<p align="right">(<a href="#bcddresult-">⬆️ &nbsp;back to top</a>)</p>
+<p align="right">(<a href="#-bcddresult">⬆️ &nbsp;back to top</a>)</p>
 
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/B-CDD/bcdd-result. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/B-CDD/bcdd-result/blob/master/CODE_OF_CONDUCT.md).
 
-<p align="right">(<a href="#bcddresult-">⬆️ &nbsp;back to top</a>)</p>
+<p align="right">(<a href="#-bcddresult">⬆️ &nbsp;back to top</a>)</p>
 
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
 
-<p align="right">(<a href="#bcddresult-">⬆️ &nbsp;back to top</a>)</p>
+<p align="right">(<a href="#-bcddresult">⬆️ &nbsp;back to top</a>)</p>
 
 ## Code of Conduct
 

data/lib/bcdd/result/error.rb

@@ -2,6 +2,10 @@
 
 class BCDD::Result
   class Error < ::StandardError
+    def self.build(**_kargs)
+      new
+    end
+
     class NotImplemented < self
     end
 
@@ -11,13 +15,31 @@ class BCDD::Result
       end
     end
 
-    class UnexpectedBlockOutcome < self
-      def initialize(arg = nil)
+    class UnexpectedOutcome < self
+      def self.build(outcome:, origin:)
         message =
-          "Unexpected outcome: #{arg.inspect}. The block must return this object wrapped by " \
+          "Unexpected outcome: #{outcome.inspect}. The #{origin} must return this object wrapped by " \
           'BCDD::Result::Success or BCDD::Result::Failure'
 
-        super(message)
+        new(message)
+      end
+    end
+
+    class WrongResultSubject < self
+      def self.build(given_result:, expected_subject:)
+        message =
+          "You cannot call #and_then and return a result that does not belong to the subject!\n" \
+          "Expected subject: #{expected_subject.inspect}\n" \
+          "Given subject: #{given_result.send(:subject).inspect}\n" \
+          "Given result: #{given_result.inspect}"
+
+        new(message)
+      end
+    end
+
+    class WrongSubjectMethodArity < self
+      def self.build(subject:, method:)
+        new("#{subject.class}##{method.name} has unsupported arity (#{method.arity}). Expected 0 or 1.")
       end
     end
   end

data/lib/bcdd/result/handler.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+class BCDD::Result
+  class Handler
+    UNDEFINED = ::Object.new
+
+    def initialize(result)
+      @outcome = UNDEFINED
+
+      @_type = result._type
+      @result = result
+    end
+
+    def [](*types, &block)
+      raise Error::MissingTypeArgument if types.empty?
+
+      self.outcome = block if _type.in?(types, allow_empty: false)
+    end
+
+    def failure(*types, &block)
+      self.outcome = block if result.failure? && _type.in?(types, allow_empty: true)
+    end
+
+    def success(*types, &block)
+      self.outcome = block if result.success? && _type.in?(types, allow_empty: true)
+    end
+
+    alias type []
+
+    private
+
+    attr_reader :_type, :result
+
+    def outcome?
+      @outcome != UNDEFINED
+    end
+
+    def outcome
+      @outcome if outcome?
+    end
+
+    def outcome=(block)
+      @outcome = block.call(result.value, result.type) unless outcome?
+    end
+  end
+
+  private_constant :Handler
+end

data/lib/bcdd/result/type.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+class BCDD::Result
+  class Type
+    attr_reader :to_sym
+
+    def initialize(type)
+      @to_sym = type.to_sym
+    end
+
+    def in?(types, allow_empty: false)
+      (allow_empty && types.empty?) || types.any?(to_sym)
+    end
+  end
+
+  private_constant :Type
+end

data/lib/bcdd/result/version.rb

@@ -2,6 +2,6 @@
 
 module BCDD
   class Result
-    VERSION = '0.1.0'
+    VERSION = '0.3.0'
   end
 end

data/lib/bcdd/result.rb

@@ -2,15 +2,26 @@
 
 require_relative 'result/version'
 require_relative 'result/error'
+require_relative 'result/type'
+require_relative 'result/handler'
 require_relative 'result/failure'
 require_relative 'result/success'
 
+require_relative 'resultable'
+
 class BCDD::Result
-  attr_reader :type, :value
+  attr_reader :_type, :value, :subject
+
+  protected :subject
 
-  def initialize(type:, value:)
-    @type = type.to_sym
+  def initialize(type:, value:, subject: nil)
+    @_type = Type.new(type)
     @value = value
+    @subject = subject
+  end
+
+  def type
+    _type.to_sym
   end
 
   def success?(_type = nil)
@@ -41,25 +52,33 @@ class BCDD::Result
   def on(*types)
     raise Error::MissingTypeArgument if types.empty?
 
-    tap { yield(value, type) if expected_type?(types) }
+    tap { yield(value, type) if _type.in?(types, allow_empty: false) }
   end
 
   def on_success(*types)
-    tap { yield(value, type) if success? && allowed_to_handle?(types) }
+    tap { yield(value, type) if success? && _type.in?(types, allow_empty: true) }
   end
 
   def on_failure(*types)
-    tap { yield(value, type) if failure? && allowed_to_handle?(types) }
+    tap { yield(value, type) if failure? && _type.in?(types, allow_empty: true) }
   end
 
-  def and_then
+  def and_then(method_name = nil)
     return self if failure?
 
+    return call_subject_method(method_name) if method_name
+
     result = yield(value)
 
-    return result if result.is_a?(::BCDD::Result)
+    ensure_result_object(result, origin: :block)
+  end
+
+  def handle
+    handler = Handler.new(self)
+
+    yield handler
 
-    raise Error::UnexpectedBlockOutcome, result
+    handler.send(:outcome)
   end
 
   alias data value
@@ -68,11 +87,24 @@ class BCDD::Result
 
   private
 
-  def expected_type?(types)
-    types.any?(type)
+  def call_subject_method(method_name)
+    method = subject.method(method_name)
+
+    result =
+      case method.arity
+      when 0 then subject.send(method_name)
+      when 1 then subject.send(method_name, value)
+      else raise Error::WrongSubjectMethodArity.build(subject: subject, method: method)
+      end
+
+    ensure_result_object(result, origin: :method)
   end
 
-  def allowed_to_handle?(types)
-    types.empty? || expected_type?(types)
+  def ensure_result_object(result, origin:)
+    raise Error::UnexpectedOutcome.build(outcome: result, origin: origin) unless result.is_a?(::BCDD::Result)
+
+    return result if result.subject.equal?(subject)
+
+    raise Error::WrongResultSubject.build(given_result: result, expected_subject: subject)
   end
 end

data/lib/bcdd/resultable.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module BCDD::Resultable
+  def Success(type, value = nil)
+    BCDD::Result::Success.new(type: type, value: value, subject: self)
+  end
+
+  def Failure(type, value = nil)
+    BCDD::Result::Failure.new(type: type, value: value, subject: self)
+  end
+end

data/sig/bcdd/result.rbs

@@ -5,10 +5,13 @@ module BCDD
 end
 
 class BCDD::Result
-  attr_reader type: Symbol
+  attr_reader _type: BCDD::Result::Type
   attr_reader value: untyped
+  attr_reader subject: untyped
 
-  def initialize: (type: Symbol, value: untyped) -> void
+  def initialize: (type: Symbol, value: untyped, ?subject: untyped) -> void
+
+  def type: -> Symbol
 
   def success?: (?Symbol type) -> bool
   def failure?: (?Symbol type) -> bool
@@ -26,7 +29,9 @@ class BCDD::Result
   def on_success: (*Symbol) { (untyped, Symbol) -> void } -> BCDD::Result
   def on_failure: (*Symbol) { (untyped, Symbol) -> void } -> BCDD::Result
 
-  def and_then: { (untyped) -> untyped } -> BCDD::Result
+  def and_then: (?Symbol method_name) { (untyped) -> untyped } -> BCDD::Result
+
+  def handle: { (BCDD::Result::Handler) -> void } -> untyped
 
   alias data value
   alias data_or value_or
@@ -34,33 +39,90 @@ class BCDD::Result
 
   private
 
-  def expected_type?: (Array[Symbol]) -> bool
-  def allowed_to_handle?: (Array[Symbol]) -> bool
+  def call_subject_method: (Symbol) -> BCDD::Result
+  def ensure_result_object: (untyped, origin: Symbol) -> BCDD::Result
 end
 
 class BCDD::Result
   class Failure < BCDD::Result
   end
 
-  def self.Success: (Symbol type, untyped value) -> BCDD::Result::Success
+  def self.Success: (Symbol type, ?untyped value) -> BCDD::Result::Success
 end
 
 class BCDD::Result
   class Success < BCDD::Result
   end
 
-  def self.Failure: (Symbol type, untyped value) -> BCDD::Result::Failure
+  def self.Failure: (Symbol type, ?untyped value) -> BCDD::Result::Failure
+end
+
+class BCDD::Result
+  class Handler
+    UNDEFINED: Object
+
+    def initialize: (BCDD::Result) -> void
+
+    def []: (*Symbol) { (untyped, Symbol) -> void } -> untyped
+    def failure: (*Symbol) { (untyped, Symbol) -> void } -> untyped
+    def success: (*Symbol) { (untyped, Symbol) -> void } -> untyped
+
+    alias type []
+
+    private
+
+    attr_reader _type: BCDD::Result::Type
+    attr_reader result: BCDD::Result
+
+    def outcome?: -> bool
+
+    def outcome: -> untyped
+
+    def outcome=: (Proc) -> void
+  end
+end
+
+module BCDD
+  module Resultable
+    def Success: (Symbol type, ?untyped value) -> BCDD::Result::Success
+
+    def Failure: (Symbol type, ?untyped value) -> BCDD::Result::Failure
+  end
+end
+
+class BCDD::Result
+  class Type
+    attr_reader to_sym: Symbol
+
+    def initialize: (Symbol) -> void
+
+    def in?: (Array[Symbol], allow_empty: bool) -> bool
+  end
 end
 
 class BCDD::Result
   class Error < ::StandardError
+    def self.build: (**untyped) -> BCDD::Result::Error
+
     class NotImplemented < BCDD::Result::Error
     end
 
     class MissingTypeArgument < BCDD::Result::Error
     end
 
-    class UnexpectedBlockOutcome < BCDD::Result::Error
+    class UnexpectedOutcome < BCDD::Result::Error
+      def self.build: (outcome: untyped, origin: Symbol)
+          -> BCDD::Result::Error::UnexpectedOutcome
+    end
+
+    class WrongResultSubject < BCDD::Result::Error
+      def self.build: (given_result: BCDD::Result, expected_subject: untyped)
+          -> BCDD::Result::Error::WrongResultSubject
+    end
+
+    class WrongSubjectMethodArity < BCDD::Result::Error
+      def self.build: (subject: untyped, method: ::Method)
+        -> BCDD::Result::Error::WrongSubjectMethodArity
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bcdd-result
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Rodrigo Serradura
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-09-25 00:00:00.000000000 Z
+date: 2023-09-27 00:00:00.000000000 Z
 dependencies: []
 description: A general-purpose result monad that allows you to create objects that
   represent a success (BCDD::Result::Success) or failure (BCDD::Result::Failure).
@@ -29,8 +29,11 @@ files:
 - lib/bcdd/result.rb
 - lib/bcdd/result/error.rb
 - lib/bcdd/result/failure.rb
+- lib/bcdd/result/handler.rb
 - lib/bcdd/result/success.rb
+- lib/bcdd/result/type.rb
 - lib/bcdd/result/version.rb
+- lib/bcdd/resultable.rb
 - sig/bcdd/result.rbs
 homepage: https://github.com/b-cdd/result
 licenses: