u-case 2.1.0 → 2.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2cc6d19966687eef5e783d907074f36cb5b27492cea1e5e9bfadeaa68a799e69
-  data.tar.gz: cb63d747bdeaf71604fc52f7adecd80a8f2071c2087222ad9c1423fd29e381bb
+  metadata.gz: d5b58d2e19bca34b4337e348d4d498b21ee12134082f897122c957ab79e19fa7
+  data.tar.gz: 6cb9e76227b0dc96d92de0c7ae1abdfe4bce2f840f0dced7ce1cae24908c0efb
 SHA512:
-  metadata.gz: aab4e530a1a74c9a3900cf4347a1d8f01b9dea9551565943c46b5e6367aedf3c25ba0e504fdcffd691a9276a1a902242d46489f4df4dfed02b761b46da06db1c
-  data.tar.gz: b409f247130404652073cd18edaf4e69746ed4a50091ee48f936e964e7993bf45e93738b8cde19aa5fee6eddcae5fb7722f5ac23639bede336dec1303491b644
+  metadata.gz: ea7dd10cd004dc3ef7e3fbfe062afc6e7a09e172b9fca1c5d2f2300c6d876b19eeb4935d06c8650010b14ca318486226fe08ec5c9fa57a9570870caf9b470bb2
+  data.tar.gz: 5742702a5c64d2ed8a32cb83aaa6ee8fb5cb550b7144eba248cf058e340f47751528e38214991f1c92c50370b4a6240f7e29a963d872ffe78219d2d91fa5637e

data/.tool-versions

@@ -1 +1 @@
-ruby 2.6.3
+ruby 2.6.5

data/.travis.sh

@@ -11,3 +11,8 @@ if [[ ! $ruby_v =~ '2.2.0' ]]; then
   ACTIVEMODEL_VERSION='5.2' bundle update
   ACTIVEMODEL_VERSION='5.2' bundle exec rake test
 fi
+
+if [[ $ruby_v =~ '2.5.' ]] || [[ $ruby_v =~ '2.6.' ]] || [[ $ruby_v =~ '2.7.' ]]; then
+  ACTIVEMODEL_VERSION='6.0' bundle update
+  ACTIVEMODEL_VERSION='6.0' bundle exec rake test
+fi

data/.travis.yml

@@ -9,6 +9,7 @@ rvm:
 - 2.4.0
 - 2.5.0
 - 2.6.0
+- 2.7.0
 
 cache: bundler
 

data/Gemfile

@@ -7,6 +7,7 @@ activemodel_version = ENV.fetch('ACTIVEMODEL_VERSION', '6.1.0')
 activemodel = case activemodel_version
               when '3.2' then '3.2.22'
               when '5.2' then '5.2.3'
+              when '6.0' then '6.0.2'
               end
 
 if activemodel_version < '6.1.0'
@@ -17,7 +18,19 @@ end
 group :test do
   gem 'minitest', activemodel_version < '4.1' ? '~> 4.2' : '~> 5.0'
   gem 'simplecov', require: false
-  gem 'minitest-reporters', require: false
+end
+
+pry_byebug_version =
+  case RUBY_VERSION
+  when /\A2.2/ then '3.6'
+  when /\A2.3/ then '3.7'
+  else '3.9'
+  end
+
+group :development, :test do
+  gem 'awesome_print', '~> 1.8'
+
+  gem 'pry-byebug', "~> #{pry_byebug_version}"
 end
 
 # Specify your gem's dependencies in u-case.gemspec

data/README.md

@@ -1,54 +1,64 @@
+![Ruby](https://img.shields.io/badge/ruby-2.2+-ruby.svg?colorA=99004d&colorB=cc0066)
 [![Gem](https://img.shields.io/gem/v/u-case.svg?style=flat-square)](https://rubygems.org/gems/u-case)
 [![Build Status](https://travis-ci.com/serradura/u-case.svg?branch=master)](https://travis-ci.com/serradura/u-case)
 [![Maintainability](https://api.codeclimate.com/v1/badges/5c3c8ad1b0b943f88efd/maintainability)](https://codeclimate.com/github/serradura/u-case/maintainability)
 [![Test Coverage](https://api.codeclimate.com/v1/badges/5c3c8ad1b0b943f88efd/test_coverage)](https://codeclimate.com/github/serradura/u-case/test_coverage)
 
-μ-case (Micro::Case)
-==========================
+μ-case (Micro::Case) <!-- omit in toc -->
+====================
 
 Create simple and powerful use cases as objects.
 
 The main project goals are:
-1. Be simple to use and easy to learn (input **>>** process / transform **>>** output).
+1. Easy to use and easy to learn (input **>>** process **>>** output).
 2. Promote referential transparency (transforming instead of modifying) and data integrity.
 3. No callbacks (e.g: before, after, around).
 4. Solve complex business logic, by allowing the composition of use cases.
 5. Be fast and optimized (Check out the [benchmarks](#benchmarks) section).
 
+> Note: Check out the repo https://github.com/serradura/from-fat-controllers-to-use-cases to see a Rails application that uses this gem to handle its business logic.
+
 ## Table of Contents <!-- omit in toc -->
-- [μ-case (Micro::Case)](#μ-case-microcase)
-  - [Required Ruby version](#required-ruby-version)
-  - [Dependencies](#dependencies)
-  - [Installation](#installation)
-  - [Usage](#usage)
-    - [Micro::Case - How to define a use case?](#microcase---how-to-define-a-use-case)
-    - [Micro::Case::Result - What is a use case result?](#microcaseresult---what-is-a-use-case-result)
-      - [What are the default result types?](#what-are-the-default-result-types)
-      - [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 failure hook (without a type) exposes a different kind of data?](#why-the-failure-hook-without-a-type-exposes-a-different-kind-of-data)
-      - [What happens if a result hook was declared multiple times?](#what-happens-if-a-result-hook-was-declared-multiple-times)
-    - [Micro::Case::Flow - How to compose use cases?](#microcaseflow---how-to-compose-use-cases)
-      - [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 their use cases?](#is-it-possible-a-flow-accumulates-its-input-and-merges-each-success-result-to-use-as-the-argument-of-their-use-cases)
-      - [Is it possible to declare a flow using the use case itself?](#is-it-possible-to-declare-a-flow-using-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)
-    - [u-case/with_validation - How to validate use case attributes?](#u-casewith_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)
-  - [Benchmarks](#benchmarks)
-    - [Micro::Case](#microcase)
-      - [Best overall](#best-overall)
-      - [Success results](#success-results)
-      - [Failure results](#failure-results)
-    - [Micro::Case::Flow](#microcaseflow)
-    - [Comparisons](#comparisons)
-  - [Examples](#examples)
-  - [Development](#development)
-  - [Contributing](#contributing)
-  - [License](#license)
-  - [Code of Conduct](#code-of-conduct)
+- [Required Ruby version](#required-ruby-version)
+- [Dependencies](#dependencies)
+- [Installation](#installation)
+- [Usage](#usage)
+  - [`Micro::Case` - How to define a use case?](#microcase---how-to-define-a-use-case)
+  - [`Micro::Case::Result` - What is a use case result?](#microcaseresult---what-is-a-use-case-result)
+    - [What are the default result types?](#what-are-the-default-result-types)
+    - [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 failure hook (without a type) exposes a different kind of data?](#why-the-failure-hook-without-a-type-exposes-a-different-kind-of-data)
+    - [What happens if a result hook was declared multiple times?](#what-happens-if-a-result-hook-was-declared-multiple-times)
+    - [How to use the `Micro::Case::Result#then` method?](#how-to-use-the-microcaseresultthen-method)
+  - [`Micro::Case::Flow` - How to compose use cases?](#microcaseflow---how-to-compose-use-cases)
+    - [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)
+    - [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)
+  - [`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)
+- [Benchmarks](#benchmarks)
+  - [`Micro::Case`](#microcase)
+    - [Best overall](#best-overall)
+    - [Success results](#success-results)
+    - [Failure results](#failure-results)
+  - [`Micro::Case::Flow`](#microcaseflow)
+  - [Comparisons](#comparisons)
+- [Examples](#examples)
+  - [1️⃣ Rails App (API)](#1️⃣-rails-app-api)
+  - [2️⃣ CLI calculator](#2️⃣-cli-calculator)
+  - [3️⃣ Users creation](#3️⃣-users-creation)
+  - [4️⃣ Rescuing exception inside of the use cases](#4️⃣-rescuing-exception-inside-of-the-use-cases)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+- [Code of Conduct](#code-of-conduct)
 
 ## Required Ruby version
 
@@ -56,8 +66,15 @@ The main project goals are:
 
 ## Dependencies
 
-This project depends on [Micro::Attribute](https://github.com/serradura/u-attributes) gem.
-It is used to define the use case attributes.
+1. [`kind`](https://github.com/serradura/kind) gem.
+
+    A simple type system (at runtime) for Ruby.
+
+    Used to validate method inputs, expose `Kind.of.Micro::Case::Result` type checker and its [`activemodel validation`](https://github.com/serradura/kind#kindvalidator-activemodelvalidations) module is auto required by [`u-case/with_activemodel_validation`](#u-casewith_activemodel_validation---how-to-validate-use-case-attributes) mode.
+2. [`u-attributes`](https://github.com/serradura/u-attributes) gem.
+
+    This gem allows defining read-only attributes, that is, your objects will have only getters to access their attributes data.
+    It is used to define the use case attributes.
 
 ## Installation
 
@@ -139,6 +156,7 @@ A `Micro::Case::Result` stores the use cases output data. These are their main m
 - `#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 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).
+- `#then` allows if the current result is a success, the `then` method will allow to applying a new use case for its value.
 
 [⬆️ Back to Top](#table-of-contents-)
 
@@ -409,6 +427,48 @@ accum # 24
 result.value * 4 == accum # true
 ```
 
+#### How to use the `Micro::Case::Result#then` method?
+
+```ruby
+class ForbidNegativeNumber < Micro::Case
+  attribute :number
+
+  def call!
+    return Success { attributes } if number >= 0
+
+    Failure { attributes }
+  end
+end
+
+class Add3 < Micro::Case
+  attribute :number
+
+  def call!
+    Success { { number: number + 3 } }
+  end
+end
+
+result1 =
+  ForbidNegativeNumber
+    .call(number: -1)
+    .then(Add3)
+
+result1.type     # :error
+result1.value    # {'number' => -1}
+result1.failure? # true
+
+# ---
+
+result2 =
+  ForbidNegativeNumber
+    .call(number: 1)
+    .then(Add3)
+
+result2.type     # :ok
+result2.value    # {'number' => 4}
+result2.success? # true
+```
+
 [⬆️ Back to Top](#table-of-contents-)
 
 ### `Micro::Case::Flow` - How to compose use cases?
@@ -592,13 +652,148 @@ Note: You can blend any of the [available syntaxes/approaches](#how-to-create-a-
 
 [⬆️ Back to Top](#table-of-contents-)
 
-#### Is it possible a flow accumulates its input and merges each success result to use as the argument of their 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?
+
+Answer: Yes, it is! Look at the example below to understand how the data accumulation works inside of the flow execution.
+
+```ruby
+module Users
+  class Find < Micro::Case
+    attribute :email
+
+    def call!
+      user = User.find_by(email: email)
+
+      return Success { { user: user } } if user
+
+      Failure(:user_not_found)
+    end
+  end
+end
+
+module Users
+  class ValidatePassword < Micro::Case::Strict
+    attributes :user, :password
+
+    def call!
+      return Failure(:user_must_be_persisted) if user.new_record?
+      return Failure(:wrong_password) if user.wrong_password?(password)
+
+      return Success { attributes(:user) }
+    end
+  end
+end
+
+module Users
+  Authenticate = Micro::Case::Flow([
+    Find,
+    ValidatePassword
+  ])
+end
+
+Users::Authenticate
+  .call(email: 'somebody@test.com', password: 'password')
+  .on_success { |result| sign_in(result[:user]) }
+  .on_failure(:wrong_password) { |result| render status: 401 }
+  .on_failure(:user_not_found) { |result| render status: 404 }
+```
+
+First, lets see the attribute of each use case:
 
-Answer: Yes, it is! Check out these test examples [Micro::Case::Flow](https://github.com/serradura/u-case/blob/e0066d8a6e3a9404069dfcb9bf049b854f08a33c/test/micro/case/flow/reducer_test.rb) and [Micro::Case::Safe::Flow](https://github.com/serradura/u-case/blob/e0066d8a6e3a9404069dfcb9bf049b854f08a33c/test/micro/case/safe/flow/reducer_test.rb) to see different use cases sharing their own data.
+```ruby
+class Users::Find < Micro::Case
+  attribute :email
+end
+
+class Users::ValidatePassword < Micro::Case
+  attributes :user, :password
+end
+```
+
+As you can see the `Users::ValidatePassword` expects a user as its input. So, how 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
+of one flow will compose the input of the next use case in the flow!
+
+> input **>>** process **>>** output
+
+> **Note:** Check out these test examples [Micro::Case::Flow](https://github.com/serradura/u-case/blob/b6d63b0db0caada67d2a6cf5cc5937000c0acf04/test/micro/case/flow/reducer_test.rb) and [Micro::Case::Safe::Flow](https://github.com/serradura/u-case/blob/b1d84b355f2b92d329e10d5d56d8012df1d32681/test/micro/case/safe/flow/reducer_test.rb) to see different use cases sharing their own data.
 
 [⬆️ Back to Top](#table-of-contents-)
 
-#### Is it possible to declare a flow using the use case itself?
+#### How to understand what is happening during a flow execution?
+
+Use `Micro::Case::Result#transitions`!
+
+Let's use the [previous section example](#is-it-possible-a-flow-accumulates-its-input-and-merges-each-success-result-to-use-as-the-argument-of-the-next-use-cases) to ilustrate how to use this feature.
+
+```ruby
+user_authenticated =
+  Users::Authenticate.call(email: 'rodrigo@test.com', password: user_password)
+
+user_authenticated.transitions
+[
+  {
+    :use_case => {
+      :class      => Users::Find,
+      :attributes => { :email => "rodrigo@test.com" }
+    },
+    :success => {
+      :type  => :ok,
+      :value => {
+        :user => #<User:0x00007fb57b1c5f88 @email="rodrigo@test.com" ...>
+      }
+    },
+    :accessible_attributes => [ :email, :password ]
+  },
+  {
+    :use_case => {
+      :class      => Users::ValidatePassword,
+      :attributes => {
+        :user     => #<User:0x00007fb57b1c5f88 @email="rodrigo@test.com" ...>
+        :password => "123456"
+      }
+    },
+    :success => {
+      :type  => :ok,
+      :value => {
+        :user => #<User:0x00007fb57b1c5f88 @email="rodrigo@test.com" ...>
+      }
+    },
+    :accessible_attributes => [ :email, :password, :user ]
+  }
+]
+```
+
+The example above shows the output generated by the `Micro::Case::Result#transitions`.
+With it is possible to analyze the use cases execution order and what were the given `inputs` (attributes) and `outputs` (`success.value`) in the entire execution.
+
+And look up the `accessible_attributes` property, because it shows whats attributes are accessible in that flow step. For example, in the last step, you can see that the `accessible_attributes` increased because of the [flow data accumulation](#is-it-possible-a-flow-accumulates-its-input-and-merges-each-success-result-to-use-as-the-argument-of-the-next-use-cases).
+
+> **Note:** The [`Micro::Case::Result#then`](#how-to-use-the-microcaseresultthen-method) increments the `Micro::Case::Result#transitions`.
+
+##### Micro::Case::Result#transitions schema.
+```ruby
+[
+  {
+    use_case: {
+      class:      <Micro::Case>,# Use case which was executed
+      attributes: <Hash>        # (Input) The use case's attributes
+    },
+    [success:, failure:] => {   # (Output)
+      type:  <Symbol>,          # Result type. Defaults:
+                                # Success = :ok, Failure = :error/:exception
+      value: <Hash>             # The data returned by the use case
+    },
+    accessible_attributes: <Array>, # Properties that can be accessed by the use case's attributes,
+                                    # starting with Hash used to invoke it and which are incremented
+                                    # with each result value of the flow's use cases.
+  }
+]
+```
+
+#### Is it possible to declare a flow which includes the use case itself?
 
 Answer: Yes, it is! You can use the `self.call!` macro. e.g:
 
@@ -620,16 +815,15 @@ class ConvertNumberToText < Micro::Case
 end
 
 class Double < Micro::Case
+  flow ConvertTextToNumber,
+       self.call!,
+       ConvertNumberToText
+
   attribute :number
 
   def call!
     Success { { number: number * 2 } }
   end
-
-  # NOTE: You need to declare the flow after the definition of the attributes.
-  flow ConvertTextToNumber,
-       self.call!,
-       ConvertNumberToText
 end
 
 result = Double.call(text: '4')
@@ -767,11 +961,11 @@ end
 
 [⬆️ Back to Top](#table-of-contents-)
 
-### `u-case/with_validation` - How to validate use case attributes?
+### `u-case/with_activemodel_validation` - How to validate use case attributes?
 
 **Requirement:**
 
-To do this your application must have the [activemodel >= 3.2](https://rubygems.org/gems/activemodel) as a dependency.
+To do this your application must have the [activemodel >= 3.2, < 6.1.0](https://rubygems.org/gems/activemodel) as a dependency.
 
 ```ruby
 #
@@ -795,10 +989,10 @@ end
 # your use cases on validation errors, you can use:
 
 # In some file. e.g: A Rails initializer
-require 'u-case/with_validation' # or require 'micro/case/with_validation'
+require 'u-case/with_activemodel_validation' # or require 'micro/case/with_validation'
 
 # In the Gemfile
-gem 'u-case', require: 'u-case/with_validation'
+gem 'u-case', require: 'u-case/with_activemodel_validation'
 
 # Using this approach, you can rewrite the previous example with less code. e.g:
 
@@ -823,7 +1017,7 @@ end
 Answer: Yes, it is. To do this, you only need to use the `disable_auto_validation` macro. e.g:
 
 ```ruby
-require 'u-case/with_validation'
+require 'u-case/with_activemodel_validation'
 
 class Multiply < Micro::Case
   disable_auto_validation
@@ -845,6 +1039,31 @@ Multiply.call(a: 2, b: 'a')
 
 [⬆️ Back to Top](#table-of-contents-)
 
+#### Kind::Validator
+
+The [kind gem](https://github.com/serradura/kind) has a module to enable the validation of data type through [`ActiveModel validations`](https://guides.rubyonrails.org/active_model_basics.html#validations). So, when you require the `'u-case/with_activemodel_validation'`, this module will require the [`Kind::Validator`](https://github.com/serradura/kind#kindvalidator-activemodelvalidations).
+
+The example below shows how to validate the attributes data types.
+
+```ruby
+class Todo::List::AddItem < Micro::Case
+  attributes :user, :params
+
+  validates :user, kind: User
+  validates :params, kind: ActionController::Parameters
+
+  def call!
+    todo_params = Todo::Params.to_save(params)
+
+    todo = user.todos.create(todo_params)
+
+    Success { { todo: todo} }
+  rescue ActionController::ParameterMissing => e
+    Failure(:parameter_missing) { { message: e.message } }
+  end
+end
+```
+
 ## Benchmarks
 
 ### `Micro::Case`
@@ -853,25 +1072,25 @@ Multiply.call(a: 2, b: 'a')
 
 The table below contains the average between the [Success results](#success-results) and [Failure results](#failure-results) benchmarks.
 
-| Gem / Abstraction      | Iterations per second |       Comparison |
-| ---------------------- | --------------------: | ---------------: |
-| **Micro::Case**        |              116629.7 | _**The Faster**_ |
-| Dry::Monads            |              101796.3 |     1.14x slower |
-| Interactor             |               21230.5 |     5.49x slower |
-| Trailblazer::Operation |               16466.6 |     7.08x slower |
-| Dry::Transaction       |                5069.5 |    23.00x slower |
+| Gem / Abstraction      | Iterations per second |       Comparison  |
+| ---------------------- | --------------------: | ----------------: |
+| **Micro::Case**        |              116629.7 | _**The Fastest**_ |
+| Dry::Monads            |              101796.3 |     1.14x slower  |
+| Interactor             |               21230.5 |     5.49x slower  |
+| Trailblazer::Operation |               16466.6 |     7.08x slower  |
+| Dry::Transaction       |                5069.5 |    23.00x slower  |
 
 ---
 
 #### Success results
 
-| Gem / Abstraction      | Iterations per second |       Comparison |
-| -----------------      | --------------------: | ---------------: |
-| Dry::Monads            |              139352.5 | _**The Faster**_ |
-| **Micro::Case**        |              124749.4 |     1.12x slower |
-| Interactor             |               28974.4 |     4.81x slower |
-| Trailblazer::Operation |               17275.6 |     8.07x slower |
-| Dry::Transaction       |                5571.7 |    25.01x slower |
+| Gem / Abstraction      | Iterations per second |       Comparison  |
+| -----------------      | --------------------: | ----------------: |
+| Dry::Monads            |              139352.5 | _**The Fastest**_ |
+| **Micro::Case**        |              124749.4 |     1.12x slower  |
+| Interactor             |               28974.4 |     4.81x slower  |
+| Trailblazer::Operation |               17275.6 |     8.07x slower  |
+| Dry::Transaction       |                5571.7 |    25.01x slower  |
 
 <details>
   <summary>Show the full <a href="https://github.com/evanphx/benchmark-ips">benchmark/ips</a> results.</summary>
@@ -911,13 +1130,13 @@ https://github.com/serradura/u-case/blob/master/benchmarks/use_case/with_success
 
 #### Failure results
 
-| Gem / Abstraction      | Iterations per second |       Comparison |
-| -----------------      | --------------------: | ---------------: |
-| **Micro::Case**        |              108510.0 | _**The Faster**_ |
-| Dry::Monads            |               64240.1 |     1.69x slower |
-| Trailblazer::Operation |               15657.7 |     6.93x slower |
-| Interactor             |               13486.7 |     8.05x slower |
-| Dry::Transaction       |                4567.3 |    23.76x slower |
+| Gem / Abstraction      | Iterations per second |       Comparison  |
+| -----------------      | --------------------: | ----------------: |
+| **Micro::Case**        |              108510.0 | _**The Fastest**_ |
+| Dry::Monads            |               64240.1 |     1.69x slower  |
+| Trailblazer::Operation |               15657.7 |     6.93x slower  |
+| Interactor             |               13486.7 |     8.05x slower  |
+| Dry::Transaction       |                4567.3 |    23.76x slower  |
 
 <details>
   <summary>Show the full <a href="https://github.com/evanphx/benchmark-ips">benchmark/ips</a> results.</summary>
@@ -960,10 +1179,10 @@ https://github.com/serradura/u-case/blob/master/benchmarks/use_case/with_failure
 ### `Micro::Case::Flow`
 
 | Gems / Abstraction      | [Success results](https://github.com/serradura/u-case/blob/master/benchmarks/flow/with_success_result.rb#L40) | [Failure results](https://github.com/serradura/u-case/blob/master/benchmarks/flow/with_failure_result.rb#L40) |
-| ------------------      | ---------------: | ---------------: |
-| Micro::Case::Flow       | _**The Faster**_ | _**The Faster**_ |
-| Micro::Case::Safe::Flow |        0x slower |        0x slower |
-| Interactor::Organizer   |     1.47x slower |     5.51x slower |
+| ------------------      | ----------------: | ----------------: |
+| Micro::Case::Flow       | _**The Fastest**_ | _**The Fastest**_ |
+| Micro::Case::Safe::Flow |        0x slower  |        0x slower  |
+| Interactor::Organizer   |     1.47x slower  |     5.51x slower  |
 
 \* The `Dry::Monads`, `Dry::Transaction`, `Trailblazer::Operation` are out of this analysis because all of them doesn't have this kind of feature.
 
@@ -1022,13 +1241,27 @@ Check it out implementations of the same use case with different gems/abstractio
 
 ## Examples
 
-1. [Rescuing an exception inside of use cases](https://github.com/serradura/u-case/blob/master/examples/rescuing_exceptions.rb)
-2. [Users creation](https://github.com/serradura/u-case/blob/master/examples/users_creation.rb)
+### 1️⃣ Rails App (API)
+
+> This project shows different kinds of architecture (one per commit), and in the last one, how to use the Micro::Case gem to handle the application business logic.
+>
+> Link: https://github.com/serradura/from-fat-controllers-to-use-cases
+
+### 2️⃣ CLI calculator
+
+> Rake tasks to demonstrate how to handle user data, and how to use different failure types to control the program flow.
+>
+> Link: https://github.com/serradura/u-case/tree/master/examples/calculator
+
+### 3️⃣ Users creation
+
+> An example of a use case flow that define steps to sanitize, validate, and persist its input data.
+>
+> Link: https://github.com/serradura/u-case/blob/master/examples/users_creation.rb
 
-    An example of flow in how to define steps to sanitize, validate, and persist some input data.
-3. [CLI calculator](https://github.com/serradura/u-case/tree/master/examples/calculator)
+### 4️⃣ Rescuing exception inside of the use cases
 
-    A more complex example which use rake tasks to demonstrate how to handle user data, and how to use different failures type to control the program flow.
+> Link: https://github.com/serradura/u-case/blob/master/examples/rescuing_exceptions.rb
 
 [⬆️ Back to Top](#table-of-contents-)
 

data/lib/micro/case.rb

@@ -1,11 +1,12 @@
 # frozen_string_literal: true
 
+require 'kind'
 require 'micro/attributes'
-# frozen_string_literal: true
 
 module Micro
   class Case
     require 'micro/case/version'
+    require 'micro/case/utils'
     require 'micro/case/result'
     require 'micro/case/error'
     require 'micro/case/safe'
@@ -42,23 +43,15 @@ module Micro
       instance
     end
 
-    def self.__get_flow__
-      @__flow
-    end
-
-    private_class_method def self.__set_flow__(reducer, args)
-      def self.use_cases; __get_flow__.use_cases; end
-
-      self.class_eval('def use_cases; self.class.use_cases; end')
-
-      reducer.build(args)
-    end
+    def self.__call_and_set_transition__(result, arg)
+      if arg.respond_to?(:keys)
+        result.__set_transitions_accessible_attributes__(arg.keys)
+      end
 
-    def self.flow(*args)
-      @__flow ||= __set_flow__(Flow::Reducer, args)
+      __new__(result, arg).call
     end
 
-    def self.call!
+    def self.__call!
       return const_get(:Flow_Step) if const_defined?(:Flow_Step)
 
       const_set(:Flow_Step, Class.new(self) do
@@ -68,9 +61,51 @@ module Micro
       end)
     end
 
+    def self.call!
+      self
+    end
+
+    def self.__flow_reducer
+      Flow::Reducer
+    end
+
+    def self.__flow_get
+      return @__flow if defined?(@__flow)
+    end
+
+    private_class_method def self.__flow_use_cases
+      return @__flow_use_cases if defined?(@__flow_use_cases)
+    end
+
+    private_class_method def self.__flow_use_cases_get
+      Array(__flow_use_cases)
+        .map { |use_case| use_case == self ? self.__call! : use_case }
+    end
+
+    private_class_method def self.__flow_use_cases_set(args)
+      @__flow_use_cases = args
+    end
+
+    private_class_method def self.__flow_set(args)
+      return if __flow_get
+
+      def self.use_cases; __flow_get.use_cases; end
+
+      self.class_eval('def use_cases; self.class.use_cases; end')
+
+      @__flow = __flow_reducer.build(args)
+    end
+
+    def self.__flow_set!
+      __flow_set(__flow_use_cases_get) if !__flow_get && __flow_use_cases
+    end
+
+    def self.flow(*args)
+      __flow_use_cases_set(args)
+    end
+
     def initialize(input)
-      @__input = input
-      self.attributes = input
+      __setup_use_case(input)
     end
 
     def call!
@@ -83,15 +118,23 @@ module Micro
 
     def __set_result__(result)
       raise Error::InvalidResultInstance unless result.is_a?(Result)
-      raise Error::ResultIsAlreadyDefined if @__result
+      raise Error::ResultIsAlreadyDefined if defined?(@__result)
 
       @__result = result
     end
 
     private
 
+      def __setup_use_case(input)
+        self.class.__flow_set!
+
+        @__input = input
+
+        self.attributes = input
+      end
+
       def __call
-        return self.class.__get_flow__.call(@__input) if self.class.__get_flow__
+        return __call_use_case_flow if __call_use_case_flow?
 
         __call_use_case
       end
@@ -104,21 +147,25 @@ module Micro
         raise Error::UnexpectedResult.new(self.class)
       end
 
+      def __call_use_case_flow?
+        self.class.__flow_get
+      end
+
+      def __call_use_case_flow
+        self.class.__flow_get.call(@__input)
+      end
+
       def Success(arg = :ok)
         value, type = block_given? ? [yield, arg] : [arg, :ok]
 
-        __get_result__.__set__(true, value, type, nil)
+        __get_result_with(true, value, type)
       end
 
       def Failure(arg = :error)
         value = block_given? ? yield : arg
         type = __map_failure_type(value, block_given? ? arg : :error)
 
-        __get_result__.__set__(false, value, type, self)
-      end
-
-      def __get_result__
-        @__result ||= Result.new
+        __get_result_with(false, value, type)
       end
 
       def __map_failure_type(arg, type)
@@ -128,5 +175,13 @@ module Micro
 
         type
       end
+
+      def __get_result__
+        @__result ||= Result.new
+      end
+
+      def __get_result_with(is_success, value, type)
+        __get_result__.__set__(is_success, value, type, self)
+      end
   end
 end

data/lib/micro/case/error.rb

@@ -9,20 +9,36 @@ module Micro
         def initialize(klass); super(klass.name + MESSAGE); end
       end
 
-      ResultIsAlreadyDefined = ArgumentError.new('result is already defined'.freeze)
+      class ResultIsAlreadyDefined < ArgumentError
+        def initialize; super('result is already defined'.freeze); end
+      end
 
-      InvalidResultType = TypeError.new('type must be a Symbol'.freeze)
-      InvalidResultInstance = ArgumentError.new('argument must be an instance of Micro::Case::Result'.freeze)
+      class InvalidResultType < TypeError
+        def initialize; super('type must be a Symbol'.freeze); end
+      end
 
-      InvalidUseCase = TypeError.new('use case must be a kind or an instance of Micro::Case'.freeze)
-      InvalidUseCases = ArgumentError.new('argument must be a collection of `Micro::Case` classes'.freeze)
+      class InvalidResultInstance < ArgumentError
+        def initialize; super('argument must be an instance of Micro::Case::Result'.freeze); end
+      end
 
-      UndefinedFlow = ArgumentError.new("This class hasn't declared its flow. Please, use the `flow()` macro to define one.".freeze)
+      class InvalidUseCase < TypeError
+        def initialize; super('use case must be a kind or an instance of Micro::Case'.freeze); end
+      end
 
-      class InvalidAccessToTheUseCaseObject < StandardError
-        MSG = 'only a failure result can access its use case object'.freeze
+      class InvalidUseCases < ArgumentError
+        def initialize; super('argument must be a collection of `Micro::Case` classes'.freeze); end
+      end
 
-        def initialize(message = MSG); super; end
+      class InvalidInvocationOfTheThenMethod < StandardError
+        def initialize; super('Invalid invocation of the Micro::Case::Result#then method'); end
+      end
+
+      class UndefinedFlow < ArgumentError
+        def initialize; super("This class hasn't declared its flow. Please, use the `flow()` macro to define one.".freeze); end
+      end
+
+      class InvalidAccessToTheUseCaseObject < StandardError
+        def initialize; super('only a failure result can access its use case object'.freeze); end
       end
 
       module ByWrongUsage

data/lib/micro/case/flow.rb

@@ -5,7 +5,7 @@ module Micro
     module Flow
       module ClassMethods
         def __flow__
-          @__flow
+          return @__flow if defined?(@__flow)
         end
 
         def flow(*args)

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

@@ -23,19 +23,18 @@ module Micro
 
         def initialize(use_cases)
           @use_cases = use_cases
+          @first_use_case = use_cases[0]
+          @next_use_cases = use_cases[1..-1]
         end
 
         def call(arg = {})
           memo = arg.is_a?(Hash) ? arg.dup : {}
 
-          @use_cases.reduce(initial_result(arg)) do |result, use_case|
-            break result if result.failure?
+          first_result = first_use_case_result(arg)
 
-            value = result.value
-            input = value.is_a?(Hash) ? memo.tap { |data| data.merge!(value) } : value
+          return first_result if @next_use_cases.empty?
 
-            use_case_result(use_case, result, input)
-          end
+          next_use_cases_result(first_result, memo)
         end
 
         def >>(arg)
@@ -52,16 +51,8 @@ module Micro
 
         private
 
-          def use_case_result(use_case, result, input)
-            use_case.__new__(result, input).call
-          end
-
-          def initial_result(arg)
-            return arg.call if arg_to_call?(arg)
-            return arg if arg.is_a?(Micro::Case::Result)
-
-            result = ::Micro::Case::Result.new
-            result.__set__(true, arg, :ok, nil)
+          def is_a_result?(arg)
+            arg.is_a?(Micro::Case::Result)
           end
 
           def arg_to_call?(arg)
@@ -69,6 +60,44 @@ module Micro
             return true if arg.is_a?(Class) && (arg < ::Micro::Case || arg < ::Micro::Case::Flow)
             return false
           end
+
+          def call_arg(arg)
+            output = arg.call
+
+            is_a_result?(output) ? output.value : output
+          end
+
+          def first_use_case_input(arg)
+            return call_arg(arg) if arg_to_call?(arg)
+            return arg.value if is_a_result?(arg)
+
+            arg
+          end
+
+          def first_use_case_result(arg)
+            input = first_use_case_input(arg)
+
+            result = ::Micro::Case::Result.new
+
+            @first_use_case.__call_and_set_transition__(result, input)
+          end
+
+          def next_use_case_result(use_case, result, input)
+            use_case.__new__(result, input).call
+          end
+
+          def next_use_cases_result(first_result, memo)
+            @next_use_cases.reduce(first_result) do |result, use_case|
+              break result if result.failure?
+
+              value = result.value
+              input = value.is_a?(Hash) ? memo.tap { |data| data.merge!(value) } : value
+
+              result.__set_transitions_accessible_attributes__(memo.keys)
+
+              next_use_case_result(use_case, result, input)
+            end
+          end
       end
     end
   end

data/lib/micro/case/result.rb

@@ -1,8 +1,18 @@
 # frozen_string_literal: true
 
+require 'set'
+
 module Micro
   class Case
     class Result
+      Kind::Types.add(self)
+
+      @@transition_tracking_disabled = false
+
+      def self.disable_transition_tracking
+        @@transition_tracking_disabled = true
+      end
+
       class Data
         attr_reader :value, :type
 
@@ -17,12 +27,19 @@ module Micro
 
       attr_reader :value, :type
 
+      def initialize
+        @__transitions__ = {}
+        @__transitions_accessible_attributes__ = Set.new
+      end
+
       def __set__(is_success, value, type, use_case)
         raise Error::InvalidResultType unless type.is_a?(Symbol)
-        raise Error::InvalidUseCase if !is_success && !is_a_use_case?(use_case)
+        raise Error::InvalidUseCase if !is_a_use_case?(use_case)
 
         @success, @value, @type, @use_case = is_success, value, type, use_case
 
+        __set_transition__ unless @@transition_tracking_disabled
+
         self
       end
 
@@ -52,8 +69,47 @@ module Micro
         self.tap { yield(data, @use_case) }
       end
 
+      def then(arg = nil, &block)
+        can_yield_self = respond_to?(:yield_self)
+
+        if block
+          raise Error::InvalidInvocationOfTheThenMethod if arg
+          raise NotImplementedError if !can_yield_self
+
+          yield_self(&block)
+        else
+          return yield_self if !arg && can_yield_self
+
+          raise Error::InvalidInvocationOfTheThenMethod if !is_a_use_case?(arg)
+
+          return self if failure?
+
+          arg.__call_and_set_transition__(self, self.value)
+        end
+      end
+
+      def transitions
+        return [] if @__transitions__.empty?
+
+        @__transitions__.map { |_use_case, transition| transition }
+      end
+
+      def __set_transitions_accessible_attributes__(attribute_names)
+        return if @@transition_tracking_disabled
+
+        __set_transitions_accessible_attributes__!(
+          attribute_names.map!(&:to_sym)
+        )
+      end
+
       private
 
+        def __set_transitions_accessible_attributes__!(attribute_names)
+          @__transitions_accessible_attributes__.merge(
+            attribute_names
+          )
+        end
+
         def success_type?(expected_type)
           success? && (expected_type.nil? || expected_type == type)
         end
@@ -65,6 +121,22 @@ module Micro
         def is_a_use_case?(arg)
           (arg.is_a?(Class) && arg < ::Micro::Case) || arg.is_a?(::Micro::Case)
         end
+
+        def __set_transition__
+          use_case_class = @use_case.class
+          use_case_attributes = Utils.symbolize_keys(@use_case.attributes)
+
+          __set_transitions_accessible_attributes__!(use_case_attributes.keys)
+
+          result = @success ? :success : :failure
+          transition = {
+            use_case: { class: use_case_class, attributes: use_case_attributes },
+            result => { type: @type, value: @value },
+            accessible_attributes: @__transitions_accessible_attributes__.to_a
+          }
+
+          @__transitions__[use_case_class] = transition
+        end
     end
   end
 end

data/lib/micro/case/safe.rb

@@ -4,7 +4,7 @@ module Micro
   class Case
     class Safe < ::Micro::Case
       def call
-        super
+        __call
       rescue => exception
         raise exception if Error::ByWrongUsage.check(exception)
 

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

@@ -19,7 +19,7 @@ module Micro
 
           private
 
-            def use_case_result(use_case, result, input)
+            def next_use_case_result(use_case, result, input)
               begin
                 instance = use_case.__new__(result, input)
                 instance.call
@@ -36,8 +36,8 @@ module Micro
         Flow::Reducer.build(Array(args))
       end
 
-      def self.flow(*args)
-        @__flow ||= __set_flow__(Flow::Reducer, args)
+      def self.__flow_reducer
+        Flow::Reducer
       end
     end
   end

data/lib/micro/case/utils.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Micro
+  class Case
+    module Utils
+      def self.symbolize_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|
+            key = k.to_sym rescue k
+
+            memo[key] = v
+          end
+        end
+      end
+    end
+  end
+end

data/lib/micro/case/version.rb

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

data/lib/micro/case/with_activemodel_validation.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'micro/case'
+
+module Micro
+  class Case
+    include Micro::Attributes::Features::ActiveModelValidations
+
+    def self.auto_validation_disabled?
+      return @disable_auto_validation if defined?(@disable_auto_validation)
+    end
+
+    def self.disable_auto_validation
+      @disable_auto_validation = true
+    end
+
+    def initialize(input)
+      __setup_use_case(input)
+
+      run_validations! if respond_to?(:run_validations!, true)
+    end
+
+    private
+
+      def __call_use_case
+        return failure_by_validation_error(self) if !self.class.auto_validation_disabled? && invalid?
+
+        result = call!
+
+        return result if result.is_a?(Result)
+
+        raise Error::UnexpectedResult.new(self.class)
+      end
+
+      def failure_by_validation_error(object)
+        errors = object.respond_to?(:errors) ? object.errors : object
+
+        Failure(:validation_error) { { errors: errors } }
+      end
+  end
+end

data/lib/u-case/with_activemodel_validation.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require 'kind/active_model/validation'
+
+require 'micro/case/with_activemodel_validation'

data/lib/u-case/with_validation.rb

@@ -1,3 +1,6 @@
 # frozen_string_literal: true
 
-require 'micro/case/with_validation'
+warn 'Deprecation: "u-case/with_validation" will be deprecated in the next major release.' \
+    'Please use "u-case/with_activemodel_validation" instead of it.'
+
+require 'u-case/with_activemodel_validation'

data/u-case.gemspec

@@ -14,20 +14,8 @@ Gem::Specification.new do |spec|
   spec.homepage      = 'https://github.com/serradura/u-case'
   spec.license       = 'MIT'
 
-  # Prevent pushing this gem to RubyGems.org. To allow pushes either set the 'allowed_push_host'
-  # to allow pushing to a single host or delete this section to allow pushing to any host.
-  if spec.respond_to?(:metadata)
-    # spec.metadata["allowed_push_host"] = "TODO: Set to 'http://mygemserver.com'"
-
-    # spec.metadata["homepage_uri"] = spec.homepage
-    # spec.metadata["source_code_uri"] = "TODO: Put your gem's public repo URL here."
-    # spec.metadata["changelog_uri"] = "TODO: Put your gem's CHANGELOG.md URL here."
-  else
-    raise 'RubyGems 2.0 or newer is required to protect against public gem pushes.'
-  end
+  raise 'RubyGems 2.0 or newer is required to protect against public gem pushes.' unless spec.respond_to?(:metadata)
 
-  # Specify which files should be added to the gem when it is released.
-  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
   spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
     `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features|assets|benchmarks|comparisons|examples)/}) }
   end
@@ -37,8 +25,9 @@ Gem::Specification.new do |spec|
 
   spec.required_ruby_version = '>= 2.2.0'
 
+  spec.add_runtime_dependency 'kind', '~> 3.0'
   spec.add_runtime_dependency 'u-attributes', '~> 1.1'
 
   spec.add_development_dependency 'bundler'
-  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'rake', '~> 13.0'
 end

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: u-case
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 2.4.0
 platform: ruby
 authors:
 - Rodrigo Serradura
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-12-12 00:00:00.000000000 Z
+date: 2020-06-26 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: kind
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
 - !ruby/object:Gem::Dependency
   name: u-attributes
   requirement: !ruby/object:Gem::Requirement
@@ -44,14 +58,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '13.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '13.0'
 description: Create simple and powerful use cases as objects.
 email:
 - rodrigo.serradura@gmail.com
@@ -78,9 +92,11 @@ files:
 - lib/micro/case/safe.rb
 - lib/micro/case/safe/flow.rb
 - lib/micro/case/strict.rb
+- lib/micro/case/utils.rb
 - lib/micro/case/version.rb
-- lib/micro/case/with_validation.rb
+- lib/micro/case/with_activemodel_validation.rb
 - lib/u-case.rb
+- lib/u-case/with_activemodel_validation.rb
 - lib/u-case/with_validation.rb
 - test.sh
 - u-case.gemspec
@@ -103,7 +119,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
+rubygems_version: 3.0.6
 signing_key: 
 specification_version: 4
 summary: Create simple and powerful use cases as objects.

data/lib/micro/case/with_validation.rb

@@ -1,35 +0,0 @@
-# frozen_string_literal: true
-
-require 'micro/case'
-
-module Micro
-  class Case
-    include Micro::Attributes::Features::ActiveModelValidations
-
-    def self.auto_validation_disabled?
-      @disable_auto_validation
-    end
-
-    def self.disable_auto_validation
-      @disable_auto_validation = true
-    end
-
-    def initialize(input)
-      @__input = input
-      self.attributes = input
-      run_validations! if respond_to?(:run_validations!, true)
-    end
-
-    def call
-      return failure_by_validation_error(self) if !self.class.auto_validation_disabled? && invalid?
-
-      __call
-    end
-
-    private def failure_by_validation_error(object)
-      errors = object.respond_to?(:errors) ? object.errors : object
-
-      Failure(:validation_error) { { errors: errors } }
-    end
-  end
-end