bcdd-result 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8a41105b84f902004736a171bd42c943923ee188d14fe6630bf379fb3e3ef158
-  data.tar.gz: 7b879ee4c04c2b60e95d1c2af18e28c8e7f1edb475c0cdb8274c56f6a577198a
+  metadata.gz: 0a6bfbf4821c7674fd0af6dbd4e88d274cbf14595eff278ef40ebdaf5bf4490a
+  data.tar.gz: 9cc905974762089c3f3827ac40aa730040ad9e88176e8cae0275954bedd6e7a8
 SHA512:
-  metadata.gz: 48e9dd67d1f69a4b9aae0bbf1166aab532ca2f8cdc8883bf303b5a41f702a77c8531c4ae2baa96bf256a828e9db0624d631c1259e0870c9ee22ecd65b4ed2ce9
-  data.tar.gz: cb2a0e618b21a4bf98c61b0a4dabfac322efe4293eab18c84cf729df920c49bf47557dcf20ceb01c42ac7c4673fa6fb55c235a2e93f2555a2021cbbfb3f37b36
+  metadata.gz: 5446879d905a42e257b3dd5724b6dc53a455cf2ec8e3fd7a5f339f74216e8d87ce779912dd4124163a6af4a19052e558382e74e7b20a434420b8d2eae055ab37
+  data.tar.gz: c91588b64905a6d86b84dc04db128e42fb0c570cf1e973ccd76563b0126e0e30d31764e918aa93aa71b06115a95c984299d4a57c249391d366d8738469aa8ecb

data/.rubocop.yml

@@ -20,7 +20,7 @@ Style/ClassAndModuleChildren:
 
 Naming/MethodName:
   Exclude:
-    - lib/bcdd/resultable.rb
+    - lib/bcdd/result/mixin.rb
 
 Minitest/MultipleAssertions:
   Enabled: false

data/.rubocop_todo.yml

@@ -1,19 +1,22 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2023-09-25 17:14:03 UTC using RuboCop version 1.56.3.
+# on 2023-09-29 01:50:30 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: 9
+# Offense count: 14
 # Configuration parameters: AllowedConstants.
 Style/Documentation:
   Exclude:
     - 'spec/**/*'
     - 'test/**/*'
     - 'lib/bcdd/result.rb'
+    - 'lib/bcdd/result/data.rb'
     - 'lib/bcdd/result/error.rb'
     - 'lib/bcdd/result/failure.rb'
+    - 'lib/bcdd/result/handler.rb'
+    - 'lib/bcdd/result/mixin.rb'
     - 'lib/bcdd/result/success.rb'
-    - 'lib/bcdd/resultable.rb'
+    - 'lib/bcdd/result/type.rb'

data/CHANGELOG.md

@@ -1,5 +1,33 @@
 ## [Unreleased]
 
+## [0.4.0] - 2023-09-28
+
+### Added
+
+- Add `require 'result'` to define `Result` as an alias for `BCDD::Result`.
+
+- Add support to pattern matching (Ruby 2.7+).
+
+- Add `BCDD::Result#on_unknown` to execute a block if no other hook (`#on`, `#on_type`, `#on_failure`, `#on_success`) has been executed. Attention: always use it as the last hook.
+
+- Add `BCDD::Result::Handler#unknown` to execute a block if no other handler (`#[]`, `#type`, `#failure`, `#success`) has been executed. Attention: always use it as the last handler.
+
+### Changed
+
+- **(BREAKING)** Rename `BCDD::Resultable` to `BCDD::Result::Mixin`.
+
+- **(BREAKING)** Change `BCDD::Result#data` to return a `BCDD::Result::Data` instead of the result value. This object exposes the result attributes (name, type, value) directly and as a hash (`to_h`/`to_hash`) and array (`to_a`/`to_ary`).
+
+### Removed
+
+- **(BREAKING)** Remove `BCDD::Result#data_or`.
+
+## [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

data/README.md

@@ -1,10 +1,13 @@
 <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 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">
+  </p>
 </p>
 
-A general-purpose result monad that allows you to create objects that represent a success (`BCDD::Result::Success`) or failure (`BCDD::Result::Failure`).
+It's a general-purpose result monad that allows you to create objects representing a success (`BCDD::Result::Success`) or failure (`BCDD::Result::Failure`).
 
 **What problem does it solve?**
 
@@ -14,8 +17,10 @@ Furthermore, this abstraction exposes several features that will be useful to ma
 
 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)
+    - [`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)
@@ -24,34 +29,48 @@ Use it to enable the [Railway Oriented Programming](https://fsharpforfunandprofi
     - [`result.on_type`](#resulton_type)
     - [`result.on_success`](#resulton_success)
     - [`result.on_failure`](#resulton_failure)
+    - [`result.on_unknown`](#resulton_unknown)
+    - [`result.handle`](#resulthandle)
   - [Result Value](#result-value)
     - [`result.value_or`](#resultvalue_or)
-    - [`result.data_or`](#resultdata_or)
+  - [Result Data](#result-data)
+    - [`result.data`](#resultdata)
   - [Railway Oriented Programming](#railway-oriented-programming)
     - [`result.and_then`](#resultand_then)
-    - [`BCDD::Resultable`](#bcddresultable)
+    - [`BCDD::Result::Mixin`](#bcddresultmixin)
       - [Class example (instance methods)](#class-example-instance-methods)
       - [Module example (singleton methods)](#module-example-singleton-methods)
       - [Restrictions](#restrictions)
+  - [Pattern Matching](#pattern-matching)
+    - [`Array`/`Find` patterns](#arrayfind-patterns)
+    - [`Hash` patterns](#hash-patterns)
 - [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:
 
-    $ bundle add bcdd-result
+```ruby
+gem 'bcdd-result', require: 'bcdd/result'
+```
+
+And then execute:
+
+    $ bundle install
 
 If bundler is not being used to manage dependencies, install the gem by executing:
 
     $ gem install bcdd-result
 
-> **NOTE:** This gem is compatible with Ruby >= 2.7.0
-
-<p align="right">(<a href="#-bcddresult">⬆️ &nbsp;back to top</a>)</p>
+<p align="right"><a href="#-bcddresult">⬆️ &nbsp;back to top</a></p>
 
 ## Usage
 
@@ -71,7 +90,23 @@ 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>
+
+#### `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.
+
+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.
+
+```ruby
+require 'result'
+
+Result::Success(:ok) # <BCDD::Result::Success type=:ok value=nil>
+```
+
+All the examples in this README that use `BCDD::Result` can also be used with `Result`.
+
+<p align="right"><a href="#-bcddresult">⬆️ &nbsp;back to top</a></p>
 
 ## Reference
 
@@ -127,7 +162,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?`
 
@@ -153,7 +188,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
 
@@ -172,7 +207,7 @@ def divide(arg1, arg2)
 end
 ```
 
-<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.on`
 
@@ -210,7 +245,7 @@ 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>
+<p align="right"><a href="#-bcddresult">⬆️ &nbsp;back to top</a></p>
 
 #### `result.on_type`
 
@@ -239,7 +274,7 @@ divide(4, 4).on_failure { |error| puts error }
 
 *PS: The `divide()` implementation is [here](#result-hooks).*
 
-<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.on_failure`
 
@@ -261,7 +296,78 @@ divide(4, 0).on_failure(:invalid_arg) { |error| puts error }
 
 *PS: The `divide()` implementation is [here](#result-hooks).*
 
-<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.on_unknown`
+
+`BCDD::Result#on_unknown` will perform 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.
+
+The result value will be exposed as the first argument of the block.
+
+```ruby
+divide(4, 2)
+  .on(:invalid_arg) { |msg| puts msg }
+  .on(:division_by_zero) { |msg| puts msg }
+  .on_unknown { |value, type| puts [type, value].inspect }
+
+# The code above will print '[:division_completed, 2]' and return the result itself.
+```
+
+*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 }
+  result.unknown { raise NotImplementedError }
+end
+
+#or
+
+divide(4, 2).handle do |on|
+  on.success { |number| number }
+  on.failure { |err| puts err }
+  on.unknown { raise NotImplementedError }
+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 }
+  on.unknown { raise NotImplementedError }
+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 }
+  on.unknown { raise NotImplementedError }
+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
 
@@ -294,11 +400,50 @@ divide(100, 0).value_or { 0 } # 0
 
 *PS: The `divide()` implementation is [here](#result-hooks).*
 
-<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 Data
+
+#### `result.data`
 
-#### `result.data_or`
+The `BCDD::Result#data` exposes the result attributes (name, type, value) directly and as a hash (`to_h`/`to_hash`) and array (`to_a`/`to_ary`).
 
-`BCDD::Result#data_or` is an alias of `BCDD::Result#value_or`.
+This is helpful if you need to access the result attributes generically or want to use Ruby features like splat (`*`) and double splat (`**`) operators.
+
+See the examples below to understand how to use it.
+
+```ruby
+result = BCDD::Result::Success(:ok, 1)
+
+success_data = result.data # #<BCDD::Result::Data name=:success type=:ok value=1>
+
+success_data.name  # :success
+success_data.type  # :ok
+success_data.value # 1
+
+success_data.to_h  # {:name=>:success, :type=>:ok, :value=>1}
+success_data.to_a  # [:success, :ok, 1]
+
+name, type, value = success_data
+
+[name, type, value] # [:success, :ok, 1]
+
+def print_to_ary(name, type, value)
+  puts [name, type, value].inspect
+end
+
+def print_to_hash(name:, type:, value:)
+  puts [name, type, value].inspect
+end
+
+print_to_ary(*success_data)   # [:success, :ok, 1]
+
+print_to_hash(**success_data) # [:success, :ok, 1]
+```
+
+> **NOTE:** The example above uses a success result, but the same is valid for a failure result.
+
+<p align="right"><a href="#-bcddresult">⬆️ &nbsp;back to top</a></p>
 
 ### Railway Oriented Programming
 
@@ -360,9 +505,9 @@ 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`
+#### `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()`.
 
@@ -374,7 +519,7 @@ And because of this, you can use the `#and_then` method to call methods from the
 
 ```ruby
 class Divide
-  include BCDD::Resultable
+  include BCDD::Result::Mixin
 
   attr_reader :arg1, :arg2
 
@@ -422,7 +567,7 @@ Divide.new(4, '2').call #<BCDD::Result::Failure type=:invalid_arg value="arg2 mu
 
 ```ruby
 module Divide
-  extend BCDD::Resultable
+  extend BCDD::Result::Mixin
   extend self
 
   def call(arg1, arg2)
@@ -462,17 +607,78 @@ Divide.call(4, '2') #<BCDD::Result::Failure type=:invalid_arg value="arg2 must b
 
 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.
+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.
 
 > **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>
+<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.
+
+```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
+
+```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>
 
 ## 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
 
@@ -480,19 +686,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/data.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+class BCDD::Result
+  class Data
+    attr_reader :name, :type, :value, :to_h, :to_a
+
+    def initialize(result)
+      @name = result.send(:name)
+      @type = result.type
+      @value = result.value
+
+      @to_h = { name: name, type: type, value: value }
+      @to_a = [name, type, value]
+    end
+
+    def inspect
+      format(
+        '#<%<class_name>s name=%<name>p type=%<type>p value=%<value>p>',
+        class_name: self.class.name, name: name, type: type, value: value
+      )
+    end
+
+    alias to_ary to_a
+    alias to_hash to_h
+  end
+
+  private_constant :Data
+end

data/lib/bcdd/result/error.rb

@@ -1,46 +1,44 @@
 # frozen_string_literal: true
 
-class BCDD::Result
-  class Error < ::StandardError
-    def self.build(**_kargs)
-      new
-    end
+class BCDD::Result::Error < StandardError
+  def self.build(**_kargs)
+    new
+  end
 
-    class NotImplemented < self
-    end
+  class NotImplemented < self
+  end
 
-    class MissingTypeArgument < self
-      def initialize(_arg = nil)
-        super('A type (argument) is required to invoke the #on/#on_type method')
-      end
+  class MissingTypeArgument < self
+    def initialize(_arg = nil)
+      super('A type (argument) is required to invoke the #on/#on_type method')
     end
+  end
 
-    class UnexpectedOutcome < self
-      def self.build(outcome:, origin:)
-        message =
-          "Unexpected outcome: #{outcome.inspect}. The #{origin} must return this object wrapped by " \
-          'BCDD::Result::Success or BCDD::Result::Failure'
+  class UnexpectedOutcome < self
+    def self.build(outcome:, origin:)
+      message =
+        "Unexpected outcome: #{outcome.inspect}. The #{origin} must return this object wrapped by " \
+        'BCDD::Result::Success or BCDD::Result::Failure'
 
-        new(message)
-      end
+      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}"
+  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
+      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
+  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/failure.rb

@@ -14,7 +14,11 @@ class BCDD::Result
       yield
     end
 
-    alias data_or value_or
+    private
+
+    def name
+      :failure
+    end
   end
 
   def self.Failure(type, value = nil)

data/lib/bcdd/result/handler.rb

@@ -0,0 +1,52 @@
+# 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
+
+    def unknown(&block)
+      self.outcome = block unless outcome?
+    end
+
+    alias type []
+
+    private
+
+    attr_reader :_type, :result
+
+    def outcome?
+      @outcome != UNDEFINED
+    end
+
+    def outcome=(block)
+      @outcome = block.call(result.value, result.type) unless outcome?
+    end
+
+    def outcome
+      @outcome if outcome?
+    end
+  end
+
+  private_constant :Handler
+end

data/lib/bcdd/result/mixin.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+class BCDD::Result
+  module Mixin
+    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
+end

data/lib/bcdd/result/success.rb

@@ -14,7 +14,11 @@ class BCDD::Result
       value
     end
 
-    alias data_or value_or
+    private
+
+    def name
+      :success
+    end
   end
 
   def self.Success(type, value = nil)

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.2.0'
+    VERSION = '0.4.0'
   end
 end

data/lib/bcdd/result.rb

@@ -2,20 +2,32 @@
 
 require_relative 'result/version'
 require_relative 'result/error'
+require_relative 'result/type'
+require_relative 'result/data'
+require_relative 'result/handler'
 require_relative 'result/failure'
 require_relative 'result/success'
-
-require_relative 'resultable'
+require_relative 'result/mixin'
 
 class BCDD::Result
-  attr_reader :type, :value, :subject
+  attr_accessor :unknown
+
+  attr_reader :_type, :value, :subject
 
   protected :subject
 
+  private :unknown, :unknown=
+
   def initialize(type:, value:, subject: nil)
-    @type = type.to_sym
+    @_type = Type.new(type)
     @value = value
     @subject = subject
+
+    self.unknown = true
+  end
+
+  def type
+    _type.to_sym
   end
 
   def success?(_type = nil)
@@ -30,31 +42,22 @@ class BCDD::Result
     raise Error::NotImplemented
   end
 
-  def ==(other)
-    self.class == other.class && type == other.type && value == other.value
-  end
-  alias eql? ==
-
-  def hash
-    [self.class, type, value].hash
-  end
+  def on(*types, &block)
+    raise Error::MissingTypeArgument if types.empty?
 
-  def inspect
-    format('#<%<class_name>s type=%<type>p value=%<value>p>', class_name: self.class.name, type: type, value: value)
+    tap { known(block) if _type.in?(types, allow_empty: false) }
   end
 
-  def on(*types)
-    raise Error::MissingTypeArgument if types.empty?
-
-    tap { yield(value, type) if expected_type?(types) }
+  def on_success(*types, &block)
+    tap { known(block) if success? && _type.in?(types, allow_empty: true) }
   end
 
-  def on_success(*types)
-    tap { yield(value, type) if success? && allowed_to_handle?(types) }
+  def on_failure(*types, &block)
+    tap { known(block) if failure? && _type.in?(types, allow_empty: true) }
   end
 
-  def on_failure(*types)
-    tap { yield(value, type) if failure? && allowed_to_handle?(types) }
+  def on_unknown
+    tap { yield(value, type) if unknown }
   end
 
   def and_then(method_name = nil)
@@ -67,18 +70,51 @@ class BCDD::Result
     ensure_result_object(result, origin: :block)
   end
 
-  alias data value
-  alias data_or value_or
+  def handle
+    handler = Handler.new(self)
+
+    yield handler
+
+    handler.send(:outcome)
+  end
+
+  def data
+    Data.new(self)
+  end
+
+  def ==(other)
+    self.class == other.class && type == other.type && value == other.value
+  end
+
+  def hash
+    [self.class, type, value].hash
+  end
+
+  def inspect
+    format('#<%<class_name>s type=%<type>p value=%<value>p>', class_name: self.class.name, type: type, value: value)
+  end
+
+  def deconstruct
+    [type, value]
+  end
+
+  def deconstruct_keys(_keys)
+    { name => { type => value } }
+  end
+
+  alias eql? ==
   alias on_type on
 
   private
 
-  def expected_type?(types)
-    types.any?(type)
+  def name
+    raise Error::NotImplemented
   end
 
-  def allowed_to_handle?(types)
-    types.empty? || expected_type?(types)
+  def known(block)
+    self.unknown = false
+
+    block.call(value, type)
   end
 
   def call_subject_method(method_name)

data/lib/result.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative 'bcdd/result'
+
+Object.const_set(:Result, BCDD::Result)

data/sig/bcdd/result.rbs

@@ -5,38 +5,46 @@ module BCDD
 end
 
 class BCDD::Result
-  attr_reader type: Symbol
+  private attr_accessor unknown: bool
+
+  attr_reader _type: BCDD::Result::Type
   attr_reader value: untyped
   attr_reader subject: untyped
 
   def initialize: (type: Symbol, value: untyped, ?subject: untyped) -> void
 
+  def type: -> Symbol
+
   def success?: (?Symbol type) -> bool
   def failure?: (?Symbol type) -> bool
 
   def value_or: { () -> untyped } -> untyped
 
-  def ==: (untyped) -> bool
-  alias eql? ==
-
-  def hash: -> Integer
-
-  def inspect: -> String
-
   def on: (*Symbol) { (untyped, Symbol) -> void } -> BCDD::Result
   def on_success: (*Symbol) { (untyped, Symbol) -> void } -> 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
 
-  alias data value
-  alias data_or value_or
+  def handle: { (BCDD::Result::Handler) -> void } -> untyped
+
+  def data: -> BCDD::Result::Data
+
+  def ==: (untyped) -> bool
+  def hash: -> Integer
+  def inspect: -> String
+
+  def deconstruct: -> [Symbol, [Symbol, untyped]]
+  def deconstruct_keys: (Array[Symbol]) -> Hash[Symbol, Hash[Symbol, untyped]]
+
+  alias eql? ==
   alias on_type on
 
   private
 
-  def expected_type?: (Array[Symbol]) -> bool
-  def allowed_to_handle?: (Array[Symbol]) -> bool
+  def name: -> Symbol
+  def known: (Proc) -> untyped
   def call_subject_method: (Symbol) -> BCDD::Result
   def ensure_result_object: (untyped, origin: Symbol) -> BCDD::Result
 end
@@ -55,14 +63,65 @@ class BCDD::Result
   def self.Failure: (Symbol type, ?untyped value) -> BCDD::Result::Failure
 end
 
-module BCDD
-  module Resultable
+class BCDD::Result
+  module Mixin
     def Success: (Symbol type, ?untyped value) -> BCDD::Result::Success
 
     def Failure: (Symbol type, ?untyped value) -> BCDD::Result::Failure
   end
 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
+    def unknown: () { (untyped, Symbol) -> void } -> untyped
+
+    alias type []
+
+    private
+
+    attr_reader _type: BCDD::Result::Type
+    attr_reader result: BCDD::Result
+
+    def outcome?: -> bool
+    def outcome=: (Proc) -> void
+    def outcome: -> untyped
+  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 Data
+    attr_reader name: Symbol
+    attr_reader type: Symbol
+    attr_reader value: untyped
+    attr_reader to_h: Hash[Symbol, untyped]
+    attr_reader to_a: [Symbol, Symbol, untyped]
+
+    def initialize: (BCDD::Result) -> void
+
+    def inspect: -> String
+
+    alias to_ary to_a
+    alias to_hash to_h
+  end
+end
+
 class BCDD::Result
   class Error < ::StandardError
     def self.build: (**untyped) -> BCDD::Result::Error

metadata

@@ -1,17 +1,19 @@
 --- !ruby/object:Gem::Specification
 name: bcdd-result
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Rodrigo Serradura
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-09-26 00:00:00.000000000 Z
+date: 2023-09-29 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).
+description: |-
+  Empower Ruby apps with a pragmatic use of Railway Oriented Programming.
+
+  It's a general-purpose result monad that allows you to create objects representing a success (BCDD::Result::Success) or failure (BCDD::Result::Failure).
 email:
 - rodrigo.serradura@gmail.com
 executables: []
@@ -27,11 +29,15 @@ files:
 - Rakefile
 - Steepfile
 - lib/bcdd/result.rb
+- lib/bcdd/result/data.rb
 - lib/bcdd/result/error.rb
 - lib/bcdd/result/failure.rb
+- lib/bcdd/result/handler.rb
+- lib/bcdd/result/mixin.rb
 - lib/bcdd/result/success.rb
+- lib/bcdd/result/type.rb
 - lib/bcdd/result/version.rb
-- lib/bcdd/resultable.rb
+- lib/result.rb
 - sig/bcdd/result.rbs
 homepage: https://github.com/b-cdd/result
 licenses:
@@ -60,5 +66,5 @@ requirements: []
 rubygems_version: 3.4.19
 signing_key:
 specification_version: 4
-summary: A result abstraction (monad based) for Ruby.
+summary: A pragmatic result abstraction (monad based) for Ruby.
 test_files: []

data/lib/bcdd/resultable.rb

@@ -1,11 +0,0 @@
-# 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