u-case 2.4.0 → 2.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d5b58d2e19bca34b4337e348d4d498b21ee12134082f897122c957ab79e19fa7
-  data.tar.gz: 6cb9e76227b0dc96d92de0c7ae1abdfe4bce2f840f0dced7ce1cae24908c0efb
+  metadata.gz: 349609a8d927ab7fd8edb1eb96141dff2f78f9957f31f2b88a8975239fc0de87
+  data.tar.gz: 4b6293023f49f28dd8283656a0d423f7d24abbfb7f010a90ba4d0dd17f577d22
 SHA512:
-  metadata.gz: ea7dd10cd004dc3ef7e3fbfe062afc6e7a09e172b9fca1c5d2f2300c6d876b19eeb4935d06c8650010b14ca318486226fe08ec5c9fa57a9570870caf9b470bb2
-  data.tar.gz: 5742702a5c64d2ed8a32cb83aaa6ee8fb5cb550b7144eba248cf058e340f47751528e38214991f1c92c50370b4a6240f7e29a963d872ffe78219d2d91fa5637e
+  metadata.gz: 0553e560e40f71d0e8284ebbbbf7a51326d8c9bc9de6ad0de76db526466a94f633e2b038563868a2c93234800b7bdacc30a99ba57f1624ce08463fdc012d165d
+  data.tar.gz: 2866ca201676827b2ffc82877b1615e7ecbb6fc6e993df17007c6446b348a850266faf162a0953954ee6adfb0d35a88c303bee385d2fb52a9c228f45513655db

data/README.md

@@ -36,10 +36,12 @@ The main project goals are:
     - [Is it possible to compose a use case flow with other ones?](#is-it-possible-to-compose-a-use-case-flow-with-other-ones)
     - [Is it possible a flow accumulates its input and merges each success result to use as the argument of the next use cases?](#is-it-possible-a-flow-accumulates-its-input-and-merges-each-success-result-to-use-as-the-argument-of-the-next-use-cases)
     - [How to understand what is happening during a flow execution?](#how-to-understand-what-is-happening-during-a-flow-execution)
-      - [Micro::Case::Result#transitions schema.](#microcaseresulttransitions-schema)
+      - [`Micro::Case::Result#transitions` schema](#microcaseresulttransitions-schema)
     - [Is it possible to declare a flow which includes the use case itself?](#is-it-possible-to-declare-a-flow-which-includes-the-use-case-itself)
   - [`Micro::Case::Strict` - What is a strict use case?](#microcasestrict---what-is-a-strict-use-case)
   - [`Micro::Case::Safe` - Is there some feature to auto handle exceptions inside of a use case or flow?](#microcasesafe---is-there-some-feature-to-auto-handle-exceptions-inside-of-a-use-case-or-flow)
+    - [`Micro::Case::Safe::Flow`](#microcasesafeflow)
+    - [`Micro::Case::Result#on_exception`](#microcaseresulton_exception)
   - [`u-case/with_activemodel_validation` - How to validate use case attributes?](#u-casewith_activemodel_validation---how-to-validate-use-case-attributes)
     - [If I enabled the auto validation, is it possible to disable it only in specific use case classes?](#if-i-enabled-the-auto-validation-is-it-possible-to-disable-it-only-in-specific-use-case-classes)
     - [Kind::Validator](#kindvalidator)
@@ -710,7 +712,7 @@ class Users::ValidatePassword < Micro::Case
 end
 ```
 
-As you can see the `Users::ValidatePassword` expects a user as its input. So, how it receives the user?
+As you can see the `Users::ValidatePassword` expects a user as its input. So, how does it receives the user?
 It receives the user from the `Users::Find` success result!
 
 And this, is the power of use cases composition because the output
@@ -773,7 +775,9 @@ And look up the `accessible_attributes` property, because it shows whats attribu
 
 > **Note:** The [`Micro::Case::Result#then`](#how-to-use-the-microcaseresultthen-method) increments the `Micro::Case::Result#transitions`.
 
-##### Micro::Case::Result#transitions schema.
+PS: Use the `Micro::Case::Result.disable_transition_tracking` global feature toggle to disable this feature (use once) and increase the use cases' performance.
+
+##### `Micro::Case::Result#transitions` schema
 ```ruby
 [
   {
@@ -906,7 +910,9 @@ end
 # Examples: https://github.com/serradura/u-case/blob/5a85fc238b63811a32737493dc6c59965f92491d/test/micro/case/safe_test.rb#L95-L123
 ```
 
-**Flows:**
+[⬆️ Back to Top](#table-of-contents-)
+
+#### `Micro::Case::Safe::Flow`
 
 As the safe use cases, safe flows can intercept an exception in any of its steps. These are the ways to define one:
 
@@ -940,7 +946,6 @@ module Users
   end
 end
 
-
 # !------------------------------------------ ! #
 # ! Deprecated: Micro::Case::Safe::Flow mixin ! #
 # !-------------------------------------------! #
@@ -961,6 +966,54 @@ end
 
 [⬆️ Back to Top](#table-of-contents-)
 
+#### `Micro::Case::Result#on_exception`
+
+In functional programming errors/exceptions are handled as regular data, the idea is to transform the output even when it happens an unexpected behavior. For many, [exceptions are very similar to the GOTO statement](https://softwareengineering.stackexchange.com/questions/189222/are-exceptions-as-control-flow-considered-a-serious-antipattern-if-so-why), jumping the application flow to paths which could be difficult to figure out how things work in a system.
+
+To address this the `Micro::Case::Result` has a special hook `#on_exception` to helping you to handle the control flow in the case of exceptions.
+
+> **Note** this feature will work better if you use it with a `Micro::Case::Safe` use case/flow.
+
+How does it work?
+
+```ruby
+class Divide < Micro::Case::Safe
+  attributes :a, :b
+
+  def call!
+    Success(division: a / b)
+  end
+end
+
+Divide
+  .call(a: 2, b: 0)
+  .on_success { |result| puts result[:division] }
+  .on_exception(TypeError) { puts 'Please, use only numeric attributes.' }
+  .on_exception(ZeroDivisionError) { |_error| puts "Can't divide a number by 0." }
+  .on_exception { |_error, _use_case| puts 'Oh no, something went wrong!' }
+
+# Output:
+# -------
+# Can't divide a number by 0
+# Oh no, something went wrong!
+
+Divide.
+  .call(a: 2, b: '2').
+  .on_success { |result| puts result[:division] }
+  .on_exception(TypeError) { puts 'Please, use only numeric attributes.' }
+  .on_exception(ZeroDivisionError) { |_error| puts "Can't divide a number by 0." }
+  .on_exception { |_error, _use_case| puts 'Oh no, something went wrong!' }
+
+# Output:
+# -------
+# Please, use only numeric attributes.
+# Oh no, something went wrong!
+```
+
+As you can see, this hook has the same behavior of `result.on_failure(:exception)`, but, the ideia here is to have a better communication in the code, making an explicit reference when some failure happened because of an exception.
+
+[⬆️ Back to Top](#table-of-contents-)
+
 ### `u-case/with_activemodel_validation` - How to validate use case attributes?
 
 **Requirement:**

data/lib/micro/case.rb

@@ -51,20 +51,32 @@ module Micro
       __new__(result, arg).call
     end
 
+    FLOW_STEP = 'Flow_Step'.freeze
+
+    private_constant :FLOW_STEP
+
     def self.__call!
-      return const_get(:Flow_Step) if const_defined?(:Flow_Step)
+      return const_get(FLOW_STEP) if const_defined?(FLOW_STEP, false)
 
-      const_set(:Flow_Step, Class.new(self) do
-        private def __call
-          __call_use_case
-        end
-      end)
+      class_eval("class #{FLOW_STEP} < #{self.name}; private def __call; __call_use_case; end; end")
     end
 
     def self.call!
       self
     end
 
+    def self.inherited(subclass)
+      subclass.attributes(self.attributes_data({}))
+      subclass.extend ::Micro::Attributes.const_get('Macros::ForSubclasses'.freeze)
+
+      if self.send(:__flow_use_cases) && !subclass.name.to_s.end_with?(FLOW_STEP)
+        raise "Wooo, you can't do this! Inherits from a use case which has an inner flow violates "\
+          "one of the project principles: Solve complex business logic, by allowing the composition of use cases. "\
+          "Instead of doing this, declare a new class/constant with the steps needed.\n\n"\
+          "Related issue: https://github.com/serradura/u-case/issues/19\n"
+      end
+    end
+
     def self.__flow_reducer
       Flow::Reducer
     end

data/lib/micro/case/result.rb

@@ -58,7 +58,9 @@ module Micro
       end
 
       def on_success(expected_type = nil)
-        self.tap { yield(value) if success_type?(expected_type) }
+        yield(value) if success_type?(expected_type)
+
+        self
       end
 
       def on_failure(expected_type = nil)
@@ -66,7 +68,19 @@ module Micro
 
         data = expected_type.nil? ? Data.new(value, type).tap(&:freeze) : value
 
-        self.tap { yield(data, @use_case) }
+        yield(data, @use_case)
+
+        self
+      end
+
+      def on_exception(expected_exception = nil)
+        return self unless failure_type?(:exception)
+
+        if !expected_exception || (Kind.is(Exception, expected_exception) && value.is_a?(expected_exception))
+          yield(value, @use_case)
+        end
+
+        self
       end
 
       def then(arg = nil, &block)
@@ -124,7 +138,7 @@ module Micro
 
         def __set_transition__
           use_case_class = @use_case.class
-          use_case_attributes = Utils.symbolize_keys(@use_case.attributes)
+          use_case_attributes = Utils.symbolize_hash_keys(@use_case.attributes)
 
           __set_transitions_accessible_attributes__!(use_case_attributes.keys)
 

data/lib/micro/case/utils.rb

@@ -3,8 +3,8 @@
 module Micro
   class Case
     module Utils
-      def self.symbolize_keys(hash)
-        if Kind.of.Hash(hash).respond_to?(:transform_keys)
+      def self.symbolize_hash_keys(hash)
+        if Kind::Of::Hash(hash).respond_to?(:transform_keys)
           hash.transform_keys { |key| key.to_sym rescue key }
         else
           hash.each_with_object({}) do |(k, v), memo|

data/lib/micro/case/version.rb

@@ -2,6 +2,6 @@
 
 module Micro
   class Case
-    VERSION = '2.4.0'.freeze
+    VERSION = '2.5.0'.freeze
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: u-case
 version: !ruby/object:Gem::Version
-  version: 2.4.0
+  version: 2.5.0
 platform: ruby
 authors:
 - Rodrigo Serradura