rest_my_case 1.10.9 → 1.11.0

checksums.yaml

@@ -1,15 +1,7 @@
 ---
-!binary "U0hBMQ==":
-  metadata.gz: !binary |-
-    NDg4NmJlMDBmZjRiMzBlZjg4MWE1ZDUxMzc1MGQwZThlNmI3MmViNw==
-  data.tar.gz: !binary |-
-    Yjk3MjkxNzg0MzU4ODA4OTVhYmFmMGM4Zjg0ZWYyZWUxY2RmZTQ5NQ==
+SHA1:
+  metadata.gz: a0f32849ac70e42eea144b0fc564245bd76afa3a
+  data.tar.gz: 78ed4d4e6833243cfce284be8ec5d22407084111
 SHA512:
-  metadata.gz: !binary |-
-    NzhlMmU3MDMyYWQwYjQ4NjA0Y2VkMzhjZTJiOGNkNGE0YTEwOWE1MTRjYzg0
-    OThkMzI3Njg0MzFlYzc2OWI4OGZjOWYxZjM3MGUyOTBkYzgzZGU5MDY5YjI2
-    MTg1MTBmNjExZDY5M2MyNzVlZTRkMjVlNTQyY2U5MmY2NTk2Yjg=
-  data.tar.gz: !binary |-
-    ODIxZmI2NTNmZWU4NWEwNzE3ODUxY2E2N2EyZjA2ODNlMGY3ODA1OWQ3Y2I0
-    MDNlZTExZjUzOGEyZTAyNjM4NDZhMGQ1ODgyNTYxN2JlYzNlODc2MGFhNDE2
-    MmIzMTRhYjM0YWEzZDg4M2UyODQ4ZjY1OWUxY2M3ODQ0MWYyMzQ=
+  metadata.gz: c3725d52e75e29c2b9b3724ac38522a95a45a48e282a1560e4ce39245094fbc6718911378f67810c3055aff84eef9a7f57da215a0a5e0da982641da4f67e0878
+  data.tar.gz: 470adc3bfef70af304db5be018f7f57b5adb2d10eed7a17b325110148feccad8887d97fe258743e11f825982029bae19d9e2df5f4811fc430d0342f01cfa8cd1

data/README.md

@@ -1,4 +1,332 @@
 # RestMyCase [![Code Climate](https://codeclimate.com/github/goncalvesjoao/rest_my_case/badges/gpa.svg)](https://codeclimate.com/github/goncalvesjoao/rest_my_case) [![Build Status](https://travis-ci.org/goncalvesjoao/rest_my_case.svg?branch=master)](https://travis-ci.org/goncalvesjoao/rest_my_case) [![Test Coverage](https://codeclimate.com/github/goncalvesjoao/rest_my_case/badges/coverage.svg)](https://codeclimate.com/github/goncalvesjoao/rest_my_case) [![Gem Version](https://badge.fury.io/rb/rest_my_case.svg)](http://badge.fury.io/rb/rest_my_case)
 
-Very light Ruby gem with everything you need in a "The Clean Architecture" use case scenario.
-Props to [@tdantas](https://github.com/tdantas) and [@junhanamaki](https://github.com/junhanamaki)
+Light Ruby gem with everything you need in a "The Clean Architecture" use case scenario.
+
+Many thanks to [@tdantas](https://github.com/tdantas) and [@junhanamaki](https://github.com/junhanamaki) and a shout-out to [@joaquimadraz](https://github.com/joaquimadraz) and his [compel](https://github.com/joaquimadraz/compel) ruby validations gem.
+
+---
+
+## 1) Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'rest_my_case'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install rest_my_case
+
+---
+
+## 2) Ideology
+Your business logic goes into separated use cases...
+```ruby
+class FindPost < RestMyCase::Base
+
+  def perform
+    context.post = Post.find(context.id)
+  end
+
+end
+
+class ArchivePost < RestMyCase::Base
+
+  depends FindPost
+
+  def perform
+    context.post.status = 'archived'
+
+    context.result = context.post.save
+  end
+
+end
+```
+
+web framework should only act as a bridge between the user and your business logic.
+```ruby
+class PostsController < ApplicationController
+
+  def archive
+    @context = ArchivePost.perform id: params[:id]
+
+    if @context.result
+      redirect_to @context.post
+    else
+      render "archive" #view post.errors
+    end
+  end
+
+end
+```
+
+Ideally your business logic should be a ruby gem that can be tested independently from your framework.
+
+Checkout this step by step tutorial: (WIP) on how to isolate your code into a ruby gem and connect it to your rails or sinatra api.
+
+---
+
+## 3) Basic usage
+
+```ruby
+class BuildPost < RestMyCase::Base
+  def perform
+    puts context.id
+    puts context.post_attributes
+  end
+end
+```
+
+```
+irb> params = { id: 1, post: { title: 'my first post' } }
+irb> context = BuildPost.perform id: params[:id], post_attributes: params[:post]
+1
+{:title=>"my first post"}
+irb> context.id
+1
+```
+
+The Hash passed down to **BuildPost.perform** will be available through an instance method called **#context** that will return an OpenStruct object initialized with that Hash (see more in section 7).
+
+Executing **BuildPost.perform** will instantiate your use case and all of its **dependencies**, build a **context** with the contents of **params**, run your use case (and its dependencies) with that context and return it at the end.
+
+## 3.1) Normal usage
+Organize your use cases by single responsibilities and establish your use case flow through "dependencies".
+
+```ruby
+class FindPost < RestMyCase::Base
+  def perform
+    context.post = Post.find(context.id)
+  end
+end
+
+class BuildPost < RestMyCase::Base
+  depends FindPost
+
+  def perform
+    context.post.assign_attributes context.post_attributes
+  end
+end
+```
+The class method **.depends** will make **BuildPost** dependent of **FindPost** which means that calling **BuildPost.perform** will run **FindPost#perform** first and **BuildPost#perform** last. Both use cases will share the same context.
+
+```
+irb> params = { id: 1, post: { title: 'my first post' } }
+irb> context = BuildPost.perform id: params[:id], post_attributes: params[:post]
+irb> context.post.name
+"my first post"
+```
+
+---
+
+## 4) Lifecycle
+
+## 4.1) Waiting to be implemented methods
+Methods: **#setup**, **#perform**, **#rollback** and **#final**
+```ruby
+class UseCase1 < RestMyCase::Base
+  def setup
+    puts 'UseCase1#setup'
+  end
+  def perform
+    puts 'UseCase1#perform'
+    error if context.should_fail
+  end
+  def rollback
+    puts 'UseCase1#rollback'
+  end
+  def final
+    puts 'UseCase1#final'
+  end
+end
+```
+
+```
+irb> UseCase1.perform #will print
+"UseCase1#setup"
+"UseCase1#perform"
+"UseCase1#final"
+```
+
+Method **#rollback** will be called after **#perform** and before **#final** if **#error** is invoked inside a **#setup** of **#perform** (see more in section 5).
+```
+irb> UseCase1.perform(should_fail: true) #will print
+"UseCase1#setup"
+"UseCase1#perform"
+"UseCase1#rollback"
+"UseCase1#final"
+```
+
+Method **#final** will run last and always, no matter how many times **#error** was called.
+
+---
+
+### 4.2) Dependencies
+Default behaviour is to run your dependencies (**#setup**, **#perform**, **#rollback** and **#final**) methods, first.
+```ruby
+class UseCase2 < RestMyCase::Base
+  def perform
+    puts 'UseCase2#perform'
+  end
+end
+
+class UseCase3 < RestMyCase::Base
+  def perform
+    puts 'UseCase3#perform'
+  end
+end
+
+class UseCase1 < RestMyCase::Base
+  depends UseCase2,
+          UseCase3
+
+  def perform
+    puts 'UseCase1#perform'
+  end
+end
+```
+
+```
+irb> UseCase1.perform #will print
+"UseCase2#perform"
+"UseCase3#perform"
+"UseCase1#perform"
+```
+
+See section 8 for more examples.
+
+---
+
+## 5) Flow control methods
+
+Methods | Behaviour
+------- | ---------
+**#abort** | Stops other remaining use cases from running and triggers **#rollback** on already executed use cases (in reverse order).
+**#skip** | Will prevent **#perform** (of the use case that called **#skip**) from running and will not stop other use cases from running nor trigger a **#rollback** (only works by being used inside a **#setup** method).
+**#error(error_message = '')** | Will do the same as **#abort** but will also push **error_message** to **#context.errors** array so you can track down what happen in what use case (see more in section 7).
+**#invoke(*use_case_classes)** | Does the same as the class method **.depends** but executes the use cases on demand. Shares the context to them and if they call **#abort** on their side, the use case that **invoked** will also **abort**.
+
+**#skip**, **#abort**, **#error** and **#invoke** have a "bang!" version that will raise a controlled exception, preventing the remaining lines of code from running.
+```ruby
+class UseCase1 < RestMyCase::Base
+  def perform
+    puts 'before #error!'
+    error!
+    puts 'after #error!'
+  end
+end
+```
+
+```
+irb> UseCase1.perform #will print only
+"before #error!"
+```
+
+---
+
+## 6) Configuration methods
+
+Methods | Behaviour
+------- | ---------
+**.depends(*use_case_classes)** | Adds the **use_case_classes** array to the use case's **dependencies** list, that will be executed by order before the actual use case (see more in section 4).
+**.required_context(*attributes)** | WIP.
+**.context_reader(*methods)** | Defines getter methods that return **context.send method**, to help reduce the **context.method** boilerplate.
+**.context_writer(*methods)** | Defines setter methods that set **context.send "#{method}=", value**, to help reduce the **context.method = value** boilerplate.
+**.context_accessor(*methods)** | Calls both **.context_reader** and **.context_writer** methods.
+**.silence_dependencies_abort=** | If **false** once a dependency calls **#abort(!)** the next in line dependencies will not be called (and **#rollback** will be called in reverse order) but if **true** all dependencies will run no matter how many times **#abort(!)** was called (usefull when you want to run multiple validations (see more in section 9).
+
+---
+
+## 7) **#context** methods
+The returning object is an instance of **RestMyCase::Context::Base** class that inherits from **OpenStruct** and implements the following methods:
+
+Methods | Behaviour
+------- | ---------
+**#attributes** | Alias to **#marshal_dump**, returns all of the context's stored data.
+**#to_hash** | Serializes and unserializes **#attributes** turning any existing ruby objects into serialized strings.
+**#valid?** | Checks if **#errors** is empty
+**#ok?** | Alias to **#valid?**
+**#success?** | Alias to **#ok?**
+**#errors** | Array that gets 'pushed' with **{ message: error_message, class_name: UseCase.class.name }** (or **error_message** itself if **error_message** already a Hash) every time **UseCase#error(error_message)** is called.
+
+If **defined?(ActiveModel)** is true, **ActiveModel::Serialization** will be included and in turn methods like **#to_json(options = {})** and **#serializable_hash(options = nil)** will become available.
+
+---
+
+### 8) Examples
+If **UseCase1** depends on **UseCase2** and **UseCase3** in that respective order.
+
+Running **UseCase1.perform** will pass down the context to each use case in the following manner:
+
+#### 8.1) Given that no use case called the method(s) **#error(!)**
+```
+UseCase2#setup -> UseCase3#setup -> UseCase1#setup ->
+UseCase2#perform -> UseCase3#perform -> UseCase1#perform ->
+UseCase2#final -> UseCase3#final -> UseCase1#final
+```
+
+#### 8.2) Given that **UseCase3#setup** calls **#skip(!)**
+```
+UseCase2#setup -> UseCase3#setup -> UseCase1#setup ->
+UseCase2#perform -> UseCase1#perform ->
+UseCase2#final -> UseCase3#final -> UseCase1#final
+```
+
+#### 8.3) Given that **UseCase3#setup** calls **#error(!)**
+```
+UseCase2#setup -> UseCase3#setup ->
+UseCase3#rollback -> UseCase2#rollback ->
+UseCase2#final -> UseCase3#final -> UseCase1#final
+```
+
+#### 8.4) Given that **UseCase3#perform** calls **#error(!)**
+```
+UseCase2#setup -> UseCase3#setup -> UseCase1#setup ->
+UseCase2#perform -> UseCase3#perform ->
+UseCase3#rollback -> UseCase2#rollback ->
+UseCase2#final -> UseCase3#final -> UseCase1#final
+```
+
+---
+
+## 9) RestMyCase::Validator class
+WIP
+
+---
+
+## 10) RestMyCase::Status module
+```ruby
+class UseCase1 < RestMyCase::Base
+  include RestMyCase::Status
+end
+```
+
+Adds following methods:
+
+Methods | Behaviour
+------- | ---------
+**#context** | Returns an instance of **RestMyCase::Context::Status**
+**#status** | Returns **context.status** (see more in section 10.1)
+**#failure(status, error_message = nil)** | WIP
+
+**#failure!** is also present and does the same as the other flow control "bang!" methods (see section 5).
+
+### 10.1) RestMyCase::Context::Status
+WIP
+
+---
+
+## 11) RestMyCase::HttpStatus module (for seamless API integration)
+```ruby
+class UseCase1 < RestMyCase::Base
+  include RestMyCase::HttpStatus
+end
+```
+
+Includes the module **RestMyCase::Status** and **#context** becomes an instance of **RestMyCase::Context::HttpStatus**.
+
+### 11.1) RestMyCase::Context::HttpStatus
+WIP

data/lib/rest_my_case/base.rb

@@ -9,6 +9,18 @@ module RestMyCase
         Judge::Base, DefenseAttorney::Base, RestMyCase::Base, Context::Base
     end
 
+    def self.required_context(*schema)
+      if schema.length == 1 && (schema[0].is_a?(Hash) || schema[0].is_a?(Array))
+        @required_context_schema = schema[0]
+      else
+        @required_context_schema = schema
+      end
+    end
+
+    def self.required_context_schema
+      @required_context_schema ||= {}
+    end
+
     def self.depends(*use_case_classes)
       dependencies.push(*use_case_classes)
     end
@@ -44,42 +56,56 @@ module RestMyCase
 
     ######################## INSTANCE METHODS BELLOW ###########################
 
-    attr_reader :context, :dependent_use_case, :options
+    attr_reader :context, :options
 
     def initialize(context, dependent_use_case = nil)
-      @options            = {}
-      @context            = context
-      @dependent_use_case = dependent_use_case
+      @context = context
+      @options = { dependent_use_case: dependent_use_case }
+
+      return unless dependent_use_case
+
+      @options[:silent_abort] = RestMyCase.get_config \
+        :silence_dependencies_abort, dependent_use_case.class
     end
 
-    def setup;  end
+    def setup; end
 
-    def perform;  end
+    def perform; end
 
     def rollback; end
 
     def final; end
 
     def invoke(*use_case_classes)
-      trial_court.execute(use_case_classes, context.to_hash).context
+      self.class.trial_court.execute(use_case_classes, context.to_hash).context
     end
 
     def invoke!(*use_case_classes)
-      trial_court.execute(use_case_classes, context).tap do |trial_case|
-        abort! if trial_case.aborted
-      end.context
+      trial_case = self.class.trial_court.execute(use_case_classes, context)
+
+      abort! if trial_case.aborted
+
+      trial_case.context
     end
 
     def abort
-      silent_abort? ? dependent_use_case.abort : (options[:should_abort] = true)
+      if options[:silent_abort]
+        options[:dependent_use_case].abort
+      else
+        options[:should_abort] = true
+      end
     end
 
     def abort!
       abort && fail(Errors::Abort)
     end
 
-    def error(error_data = '')
-      error_data = { message: error_data } unless error_data.is_a?(Hash)
+    def error(error_message = '')
+      if error_message.is_a?(Hash)
+        error_data = error_message
+      else
+        error_data = { message: error_message }
+      end
 
       error_data[:class_name] = self.class.name
 
@@ -98,17 +124,16 @@ module RestMyCase
       skip && fail(Errors::Skip)
     end
 
-    protected ######################## PROTECTED ###############################
+    def validate_context(schema = self.class.required_context_schema)
+      errors = context.validate_schema(schema)
 
-    def trial_court
-      self.class.trial_court
-    end
+      error(context_errors: errors, message: 'invalid context') if errors
 
-    def silent_abort?
-      return false if dependent_use_case.nil?
+      Helpers.blank? errors
+    end
 
-      RestMyCase.get_config \
-        :silence_dependencies_abort, dependent_use_case.class
+    def validate_context!(schema = self.class.required_context)
+      validate_context(schema) && fail(Errors::Abort)
     end
 
   end

data/lib/rest_my_case/context/base.rb

@@ -1,3 +1,6 @@
+require 'rest_my_case/context/errors/base'
+require 'rest_my_case/context/schema_validator/base'
+
 module RestMyCase
   module Context
 
@@ -11,10 +14,18 @@ module RestMyCase
         Errors::Base
       end
 
+      def self.schema_validator_class
+        SchemaValidator::Base
+      end
+
       def to_hash
         Marshal.load Marshal.dump(attributes)
       end
 
+      def validate_schema(schema)
+        self.class.schema_validator_class.new(self).validate(schema)
+      end
+
       def errors
         @errors ||= self.class.error_class.new(self)
       end

data/lib/rest_my_case/context/schema_validator/base.rb

@@ -0,0 +1,27 @@
+module RestMyCase
+  module Context
+    module SchemaValidator
+
+      class Base
+
+        def initialize(context)
+          @context = context
+        end
+
+        def validate(schema)
+          errors = {}
+
+          schema.each do |required_attribute|
+            if Helpers.blank?(@context.send(required_attribute))
+              errors[required_attribute] = 'is required'
+            end
+          end
+
+          Helpers.blank?(errors) ? nil : errors
+        end
+
+      end
+
+    end
+  end
+end

data/lib/rest_my_case/context/schema_validator/compel.rb

@@ -0,0 +1,36 @@
+require 'compel'
+
+module RestMyCase
+  module Context
+    module SchemaValidator
+
+      class Base
+
+        def initialize(context)
+          @context = context
+        end
+
+        def validate(schema)
+          result = ::Compel.run(@context, build_schema(schema))
+
+          result.valid? ? nil : result.errors
+        end
+
+        protected ###################### PROTECTED #############################
+
+        def build_schema(schema)
+          ::Compel.hash.keys \
+            schema.is_a?(Hash) ? schema : all_attributes_required(schema)
+        end
+
+        def all_attributes_required(schema)
+          {}.tap do |new_schema|
+            schema.each { |key| new_schema[key] = Compel.any.required }
+          end
+        end
+
+      end
+
+    end
+  end
+end

data/lib/rest_my_case/context/status.rb

@@ -1,3 +1,5 @@
+require 'rest_my_case/context/errors/status'
+
 module RestMyCase
   module Context
 

data/lib/rest_my_case/defense_attorney/base.rb

@@ -4,7 +4,7 @@ module RestMyCase
     class Base
 
       def initialize(trial_case)
-        @trial_case           = trial_case
+        @trial_case = trial_case
         @trial_case.use_cases = []
       end
 

data/lib/rest_my_case/http_status.rb

@@ -1,18 +1,15 @@
+require 'rest_my_case/context/http_status'
+
 module RestMyCase
 
   module HttpStatus
 
     include Status
 
-    module ClassMethods
-      def trial_court
-        @trial_court ||= Trial::Court.new \
-          Judge::Base, DefenseAttorney::Base, Base, Context::HttpStatus
-      end
-    end
-
     def self.included(parent_class)
-      parent_class.extend ClassMethods
+      return unless parent_class.respond_to? :trial_court
+
+      parent_class.trial_court.context_class = Context::HttpStatus
     end
 
   end

data/lib/rest_my_case/judge/base.rb

@@ -4,8 +4,8 @@ module RestMyCase
     class Base
 
       def initialize(trial_case)
-        @trial_case            = trial_case
-        @performed_use_cases   = []
+        @trial_case = trial_case
+        @performed_use_cases = []
         @use_case_that_aborted = nil
       end
 
@@ -22,16 +22,21 @@ module RestMyCase
 
       def run_setup_methods
         @trial_case.use_cases.each do |use_case|
-          break if method_setup_has_aborted use_case
+          break if method_aborts?(:setup, use_case)
         end
       end
 
       def run_perform_methods
-        return nil if @use_case_that_aborted
-
         @trial_case.use_cases.each do |use_case|
-          break if method_perform_has_aborted use_case
+          validate_context_aborts?(use_case)
+
+          next if use_case.options[:should_skip] || @use_case_that_aborted
+
+          @performed_use_cases.push use_case
+
+          method_aborts?(:perform, use_case)
         end
+
       end
 
       def run_rollback_methods
@@ -50,16 +55,16 @@ module RestMyCase
 
       private ########################### PRIVATE ##############################
 
-      def method_setup_has_aborted(use_case)
-        method_aborts?(:setup, use_case)
-      end
-
-      def method_perform_has_aborted(use_case)
-        return false if use_case.options[:should_skip]
+      def validate_context_aborts?(use_case)
+        should_abort_before = use_case.options[:should_abort]
 
-        @performed_use_cases.push use_case
+        use_case.validate_context
 
-        method_aborts?(:perform, use_case)
+        if !should_abort_before && use_case.options[:should_abort]
+          @use_case_that_aborted = use_case
+        end
+      rescue Errors::Abort
+        @use_case_that_aborted = use_case
       end
 
       def method_aborts?(method_name, use_case)