u-case 2.0.0.pre.2 → 2.0.0.pre.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3028799bfa1648b6efd0ce3f4d69e9fa696a5bed0b5adfc9cf736e8cdb1dcdba
-  data.tar.gz: 60eae622b2bfd1e6f28342c560adc129e40bb2c1fb7d9ec0e9c7f158c07db55a
+  metadata.gz: 1faaf3599f7b9e24aca4fcab71c448b7078756a6ca9abce84426a456673c4f50
+  data.tar.gz: 329095160dc157bd6ac3dda112c83637e8fe169050497bd5e3e2698c095415cd
 SHA512:
-  metadata.gz: 1b8c49b2717af8aba8cc8eaaa1b9e84fc394e1b766e0414b46db5a91bfa4452ac0624b6da760a6c0aff7167a85311a3e93e7897e0ee88deb591b5356e9445ed2
-  data.tar.gz: 7ab4c1acdb3828c87b4914ab946029cb283a36fbbf130208cb2b2091c18151e3b9dd2713d23c0918dea6a2f787298ed9fb07bdb724df9467df7985d0b43d4c9b
+  metadata.gz: f02f2e9db0044e56e9ec690d69f69d302f666b99ccff37106369a63cf6a39c0d15cefe9d07d28464a75bbb1f236b1fd6ad3eddc40f25dd473e54b0ee2d77c02d
+  data.tar.gz: 6b81d3c72c67596229689b3bc9cccc3a9ef20c9d7fd45d506913215d3fa759e174aa94d7105aeba6dfb184278b54fbfd1a9e5d7e56cdb4468968a06a96e4f7cd

data/README.md

@@ -17,6 +17,7 @@ The main goals of this project are:
 ## Table of Contents <!-- omit in toc -->
 - [μ-case (Micro::Case)](#%ce%bc-case-microcase)
   - [Required Ruby version](#required-ruby-version)
+  - [Dependencies](#dependencies)
   - [Installation](#installation)
   - [Usage](#usage)
     - [How to define a use case?](#how-to-define-a-use-case)
@@ -25,6 +26,7 @@ The main goals of this project are:
       - [How to define custom result types?](#how-to-define-custom-result-types)
       - [Is it possible to define a custom result type without a block?](#is-it-possible-to-define-a-custom-result-type-without-a-block)
       - [How to use the result hooks?](#how-to-use-the-result-hooks)
+      - [Why the on_failure result hook exposes a different kind of data?](#why-the-onfailure-result-hook-exposes-a-different-kind-of-data)
       - [What happens if a result hook is declared multiple times?](#what-happens-if-a-result-hook-is-declared-multiple-times)
     - [How to compose uses cases to represents complex ones?](#how-to-compose-uses-cases-to-represents-complex-ones)
       - [Is it possible to compose a use case flow with other ones?](#is-it-possible-to-compose-a-use-case-flow-with-other-ones)
@@ -43,6 +45,11 @@ The main goals of this project are:
 
 > \>= 2.2.0
 
+## Dependencies
+
+This project depends on [Micro::Attribute](https://github.com/serradura/u-attributes) gem.
+It is used to define the use case attributes.
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -71,7 +78,7 @@ class Multiply < Micro::Case
   # 2. Define the method `call!` with its business logic
   def call!
 
-    # 3. Wrap the use case result/output using the `Success()` and `Failure()` methods
+    # 3. Wrap the use case result/output using the `Success()` or `Failure()` methods
     if a.is_a?(Numeric) && b.is_a?(Numeric)
       Success(a * b)
     else
@@ -116,12 +123,12 @@ result.value # 6
 
 ### What is a `Micro::Case::Result`?
 
-A `Micro::Case::Result` stores use cases output data. These are their main methods:
+A `Micro::Case::Result` stores the use cases output data. These are their main methods:
 - `#success?` returns true if is a successful result.
 - `#failure?` returns true if is an unsuccessful result.
 - `#value` the result value itself.
 - `#type` a Symbol which gives meaning for the result, this is useful to declare different types of failures or success.
-- `#on_success` or `#on_failure` are hook methods which help you define the application flow.
+- `#on_success` or `#on_failure` are hook methods that help you define the application flow.
 - `#use_case` if is a failure result, the use case responsible for it will be accessible through this method. This feature is handy to handle a flow failure (this topic will be covered ahead).
 
 [⬆️ Back to Top](#table-of-contents-)
@@ -256,7 +263,7 @@ The examples below show how to use them:
 
 ```ruby
 class Double < Micro::Case
-  attributes :number
+  attribute :number
 
   def call!
     return Failure(:invalid) { 'the number must be a numeric value' } unless number.is_a?(Numeric)
@@ -286,25 +293,85 @@ Double
 Double
   .call(number: -1)
   .on_success { |number| p number }
-  .on_failure { |_msg, use_case| puts "#{use_case.class.name} was the use case responsible for the failure" }
+  .on_failure { |_result, use_case| puts "#{use_case.class.name} was the use case responsible for the failure" }
   .on_failure(:invalid) { |msg| raise TypeError, msg }
   .on_failure(:lte_zero) { |msg| raise ArgumentError, msg }
 
-# The outputs because it is a failure:
-#   Double was the use case responsible for the failure
-# (throws the error)
-#   ArgumentError (the number must be greater than 0)
+# The outputs will be:
+#
+# 1. Prints the message: Double was the use case responsible for the failure
+# 2. Raises the exception: ArgumentError (the number must be greater than 0)
 
 # Note:
 # ----
 # The use case responsible for the failure will be accessible as the second hook argument
 ```
 
+#### Why the on_failure result hook exposes a different kind of data?
+
+Answer: To allow you to define how to handle the program flow using some
+conditional statement (like an `if`, `case/when`).
+
+```ruby
+class Double < Micro::Case
+  attribute :number
+
+  def call!
+    return Failure(:invalid) unless number.is_a?(Numeric)
+    return Failure(:lte_zero) if number <= 0
+
+    Success(number * 2)
+  end
+end
+
+#=================================#
+# Using the result type and value #
+#=================================#
+
+Double
+  .call(-1)
+  .on_failure do |result, use_case|
+    case result.type
+    when :invalid then raise TypeError, 'the number must be a numeric value'
+    when :lte_zero then raise ArgumentError, "the number `#{result.value}` must be greater than 0"
+    else raise NotImplementedError
+    end
+  end
+
+# The output will be the exception:
+#
+# ArgumentError (the number `-1` must be greater than 0)
+
+#=====================================================#
+# Using decomposition to access result value and type #
+#=====================================================#
+
+# The syntax to decompose an Array can be used in methods, blocks and assigments.
+# If you doesn't know that, check out:
+# https://ruby-doc.org/core-2.2.0/doc/syntax/assignment_rdoc.html#label-Array+Decomposition
+#
+# And the object exposed in the hook failure can be decomposed using this syntax. e.g:
+
+Double
+  .call(-2)
+  .on_failure do |(value, type), use_case|
+    case type
+    when :invalid then raise TypeError, 'the number must be a numeric value'
+    when :lte_zero then raise ArgumentError, "the number `#{value}` must be greater than 0"
+    else raise NotImplementedError
+    end
+  end
+
+# The output will be the exception:
+#
+# ArgumentError (the number `-2` must be greater than 0)
+```
+
 [⬆️ Back to Top](#table-of-contents-)
 
 #### What happens if a result hook is declared multiple times?
 
-Answer: The hook will be triggered if it matches the result type.
+Answer: The hook always will be triggered if it matches the result type.
 
 ```ruby
 class Double < Micro::Case
@@ -337,11 +404,11 @@ result.value * 4 == accum # true
 
 ### How to compose uses cases to represents complex ones?
 
-In this case, this will be is a **flow**, because the idea is to use/reuse use cases as steps which will define a more complex one.
+In this case, this will be a **flow**. The main idea is to use/reuse use cases as steps of a new use case.
 
 ```ruby
 module Steps
-  class ConvertToNumbers < Micro::Case
+  class ConvertTextToNumbers < Micro::Case
     attribute :numbers
 
     def call!
@@ -383,7 +450,7 @@ end
 #---------------------------------------------#
 
 Add2ToAllNumbers = Micro::Case::Flow([
-  Steps::ConvertToNumbers,
+  Steps::ConvertTextToNumbers,
   Steps::Add2
 ])
 
@@ -399,7 +466,7 @@ p result.value    # {:numbers => [3, 3, 4, 4, 5, 6]}
 class DoubleAllNumbers
   include Micro::Case::Flow
 
-  flow Steps::ConvertToNumbers, Steps::Double
+  flow Steps::ConvertTextToNumbers, Steps::Double
 end
 
 DoubleAllNumbers
@@ -411,7 +478,7 @@ DoubleAllNumbers
 #-------------------------------------------------------------#
 
 SquareAllNumbers =
-  Steps::ConvertToNumbers >> Steps::Square
+  Steps::ConvertTextToNumbers >> Steps::Square
 
 SquareAllNumbers
   .call(numbers: %w[1 1 2 2 3 4])
@@ -425,10 +492,10 @@ SquareAllNumbers
 result = SquareAllNumbers.call(numbers: %w[1 1 b 2 3 4])
 
 result.failure?                                # true
-result.use_case.is_a?(Steps::ConvertToNumbers) # true
+result.use_case.is_a?(Steps::ConvertTextToNumbers) # true
 
 result.on_failure do |_message, use_case|
-  puts "#{use_case.class.name} was the use case responsible for the failure" # Steps::ConvertToNumbers was the use case responsible for the failure
+  puts "#{use_case.class.name} was the use case responsible for the failure" # Steps::ConvertTextToNumbers was the use case responsible for the failure
 end
 ```
 
@@ -440,7 +507,7 @@ Answer: Yes, it is.
 
 ```ruby
 module Steps
-  class ConvertToNumbers < Micro::Case
+  class ConvertTextToNumbers < Micro::Case
     attribute :numbers
 
     def call!
@@ -477,9 +544,9 @@ module Steps
   end
 end
 
-Add2ToAllNumbers = Steps::ConvertToNumbers >> Steps::Add2
-DoubleAllNumbers = Steps::ConvertToNumbers >> Steps::Double
-SquareAllNumbers = Steps::ConvertToNumbers >> Steps::Square
+Add2ToAllNumbers = Steps::ConvertTextToNumbers >> Steps::Add2
+DoubleAllNumbers = Steps::ConvertTextToNumbers >> Steps::Double
+SquareAllNumbers = Steps::ConvertTextToNumbers >> Steps::Square
 
 DoubleAllNumbersAndAdd2 = DoubleAllNumbers >> Steps::Add2
 SquareAllNumbersAndAdd2 = SquareAllNumbers >> Steps::Add2
@@ -515,7 +582,7 @@ end
 
 Double.call({})
 
-# The output (raised an error):
+# The output will be the following exception:
 # ArgumentError (missing keyword: :numbers)
 ```
 

data/lib/micro/case/result.rb

@@ -3,6 +3,18 @@
 module Micro
   class Case
     class Result
+      class Data
+        attr_reader :value, :type
+
+        def initialize(value, type)
+          @value, @type = value, type
+        end
+
+        def to_ary; [value, type]; end
+      end
+
+      private_constant :Data
+
       attr_reader :value, :type
 
       def __set__(is_success, value, type, use_case)
@@ -28,22 +40,26 @@ module Micro
         raise Error::InvalidAccessToTheUseCaseObject
       end
 
-      def on_success(arg = nil)
-        self.tap { yield(value) if success_type?(arg) }
+      def on_success(expected_type = nil)
+        self.tap { yield(value) if success_type?(expected_type) }
       end
 
-      def on_failure(arg = nil)
-        self.tap{ yield(value, @use_case) if failure_type?(arg) }
+      def on_failure(expected_type = nil)
+        return self unless failure_type?(expected_type)
+
+        data = expected_type.nil? ? Data.new(value, type).tap(&:freeze) : value
+
+        self.tap { yield(data, @use_case) }
       end
 
       private
 
-        def success_type?(arg)
-          success? && (arg.nil? || arg == type)
+        def success_type?(expected_type)
+          success? && (expected_type.nil? || expected_type == type)
         end
 
-        def failure_type?(arg)
-          failure? && (arg.nil? || arg == type)
+        def failure_type?(expected_type)
+          failure? && (expected_type.nil? || expected_type == type)
         end
 
         def is_a_use_case?(arg)

data/lib/micro/case/safe.rb

@@ -3,10 +3,6 @@
 module Micro
   class Case
     class Safe < ::Micro::Case
-      def self.Flow(args)
-        Flow::Reducer.build(Array(args))
-      end
-
       def call
         super
       rescue => exception

data/lib/micro/case/safe/flow.rb

@@ -10,10 +10,6 @@ module Micro
           def base.flow_reducer; Reducer; end
         end
 
-        def self.Flow(args)
-          Reducer.build(Array(args))
-        end
-
         class Reducer < ::Micro::Case::Flow::Reducer
           def call(arg = {})
             @use_cases.reduce(initial_result(arg)) do |result, use_case|
@@ -43,6 +39,10 @@ module Micro
             end
         end
       end
+
+      def self.Flow(args)
+        Flow::Reducer.build(Array(args))
+      end
     end
   end
 end

data/lib/micro/case/version.rb

@@ -2,6 +2,6 @@
 
 module Micro
   class Case
-    VERSION = '2.0.0.pre.2'.freeze
+    VERSION = '2.0.0.pre.3'.freeze
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: u-case
 version: !ruby/object:Gem::Version
-  version: 2.0.0.pre.2
+  version: 2.0.0.pre.3
 platform: ruby
 authors:
 - Rodrigo Serradura
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-11-13 00:00:00.000000000 Z
+date: 2019-11-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: u-attributes