usecasing 0.1.0

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format progress

data/.travis.yml

@@ -0,0 +1,3 @@
+language: ruby
+rvm:
+  - 1.9.3

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in usecasing.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Thiago Dantas
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,156 @@
+# UseCase your code
+
+
+## Installation
+
+[![Build Status](https://secure.travis-ci.org/tdantas/usecasing.png)](http://travis-ci.org/tdantas/usecasing)
+
+Add this line to your application's Gemfile:
+
+I did not (YET) upload this code to the rubygems.   
+To early adopters use the :git path
+
+    gem 'usecasing', :git => 'https://github.com/tdantas/usecasing.git'
+
+And then execute:
+
+    $ bundle
+    
+### Usage
+
+Let's build a Invoice System, right ?  
+So the product owner will create some usecases/stories to YOU.
+
+Imagine this usecase/story:
+
+````
+As a user I want to finalize an Invoice and an email should be delivered to the customer.
+````
+
+Let's build a controller
+
+````
+	class InvoicesController < ApplicationController
+		
+		def finalize
+		
+		    params[:current_user] = current_user
+   		    # params = { invoice_id: 123 , current_user: #<User:007> }
+			context = FinalizeInvoiceUseCase.perform(params)
+			
+			if context.success?
+				redirect_to invoices_path(context.invoice)
+			else
+				@errors = context.errors
+				redirect_to invoices_path
+			end
+		
+		end
+		
+	end
+````
+
+Ok, What is FinalizeInvoiceUseCase ?
+
+FinalizeInvoiceUseCase will be responsible for perform the Use Case/Story.  
+Each usecase should satisfy the [Single Responsability Principle](http://en.wikipedia.org/wiki/Single_responsibility_principle) and to achieve this principle, one usecase depends of others usecases building a Chain of Resposability.
+
+
+````
+
+	class FinalizeInvoiceUseCase < UseCase::Base
+		depends FindInvoice, ValidateToFinalize, FinalizeInvoice, SendEmail
+	end	
+	
+````
+
+IMHO, when I read this Chain I really know what this class will do.   
+astute readers will ask: How FindInvoice pass values to ValidateToFinalize ?
+
+When we call in the Controller *FinalizeInvoiceUseCase.perform* we pass a parameter (Hash) to the usecase.
+
+This is what we call context, the usecase context will be shared between all chain.
+
+````
+	class FindInvoice < UseCase::Base
+		
+		def perform
+		
+			# available because it was added in the controller context 
+			user = context.current_user 
+			
+			# we could do that in one before_filter
+			invoice = user.invoices.find(context.invoice_id)
+			
+			# asign to the context make available to all chain
+			context.invoice = invoice
+			   
+		end
+
+	end
+````
+
+Is the invoice valid to be finalized ?
+
+````
+	class ValidateToFinalize < UseCase::Base
+		
+		def perform
+			#failure will stop the chain flow and mark the context as error.
+			
+			failure(:validate, "#{context.invoice.id} not ready to be finalized") unless valid?
+		end
+		
+		private
+		def valid?
+			#contextual validation to finalize an invoice
+		end
+	end
+
+````
+
+So, after validate, we already know that the invoice exists and it is ready to be finalized.
+
+````
+	class FinalizeInvoice < UseCase::Base
+		
+		def perform
+			invoice = context.invoice
+			invoice.finalize! #update database with finalize state
+			context.customer = invoice.customer
+		end
+	
+	end
+````
+
+Oww, yeah, let's notify the customer
+
+````
+	class SendEmail < UseCase::Base
+	
+		def perform
+			to = context.customer.email
+			
+			# Call whatever service
+			EmailService.send('customer_invoice_template', to, locals: { invoice: context.invoice } )
+		end
+	
+	end
+````
+
+
+Let me know what do you think about it.
+
+#### TODO
+ 
+ Create real case examples (40%)
+
+
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+
+require 'rspec/core/rake_task'
+
+task :default => :test
+RSpec::Core::RakeTask.new(:test)

data/lib/usecasing/base.rb

@@ -0,0 +1,82 @@
+module UseCase
+
+  module BaseClassMethod
+
+    def self.included(base)
+      base.extend ClassMethods
+    end
+
+    module ClassMethods
+
+      def depends(*deps)
+        @dependencies ||= []
+        @dependencies.push(*deps)
+      end
+
+      def dependencies
+        return [] unless superclass.ancestors.include? UseCase::Base
+        value = (@dependencies && @dependencies.dup || []).concat(superclass.dependencies)
+        value
+      end
+
+      def perform(ctx = { })
+        execution_order = build_execution_order(self, {})
+        tx(execution_order, ctx) do |usecase, context| 
+          usecase.new(context).perform 
+        end
+      end
+
+      private
+
+      def tx(execution_order, context)
+        ctx = Context.new(context)
+        executed = []
+        execution_order.each do |usecase|
+          break unless ctx.success?
+          executed.push(usecase)
+          yield usecase, ctx
+        end
+        rollback(executed, ctx) unless ctx.success?
+        ctx
+      end
+
+      def rollback(execution_order, context)
+        execution_order.each do |usecase|
+          usecase.new(context).rollback
+        end
+        context
+      end
+
+      def build_execution_order(start_point, visited)
+        raise StandardError.new("cyclic detected: #{start_point} in #{self}") if visited[start_point]
+        visited[start_point] = true
+        return [start_point] if start_point.dependencies.empty?
+
+        childrens = start_point.dependencies.each do |point|
+          build_execution_order(point, visited).unshift point
+        end
+        childrens.push(start_point)
+
+      end
+    end
+
+  end
+
+  class Base
+
+    include BaseClassMethod
+
+    attr_reader :context
+    def initialize(context)
+      @context = context
+    end
+
+    def perform;  end
+    def rollback; end
+
+    def failure(key, value)
+      @context.failure(key, value)
+    end
+    
+  end
+end

data/lib/usecasing/context.rb

@@ -0,0 +1,48 @@
+module UseCase
+
+  class Context
+
+    attr_reader :errors
+
+    def initialize(hash = {})
+      raise ArgumentError.new('Must be a Hash') unless hash.is_a? ::Hash 
+      @values = symbolyze_keys(hash)
+      @errors = []
+    end
+
+    def method_missing(method, *args, &block)
+      return @values[extract_key_from(method)] = args.first if setter? method
+      @values[method]
+    end
+
+    def respond_to?(method)
+      @values.keys.include?(method.to_sym)
+    end
+
+    def success?
+      @errors.empty?
+    end
+
+    def failure(key, value)
+      @errors.push({ key => value })
+    end
+
+    private
+      def setter?(method)
+        !! ((method.to_s) =~ /=$/)
+      end
+
+      def extract_key_from(method)
+        method.to_s[0..-2].to_sym
+      end
+
+      def symbolyze_keys(hash)
+        hash.keys.reduce({ }) do |acc, key|
+          acc[key.to_sym] = hash[key]
+          acc
+        end
+      end
+
+  end
+
+end

data/lib/usecasing/version.rb

@@ -0,0 +1,3 @@
+module Usecasing
+  VERSION = "0.1.0"
+end

data/lib/usecasing.rb

@@ -0,0 +1,6 @@
+require "usecasing/version"
+
+module UseCase
+  autoload :Context,  'usecasing/context'
+  autoload :Base,     'usecasing/base'
+end

data/spec/context_spec.rb

@@ -0,0 +1,59 @@
+require 'spec_helper'
+
+describe UseCase::Context do 
+
+
+  it 'receives a hash and generate setters from key' do 
+    hash = {name: 'thiago', last: 'dantas', github: 'tdantas'}
+    context = described_class.new(hash)
+    expect(context.name).to eql(hash[:name])
+    expect(context.last).to eql(hash[:last])
+    expect(context.github).to eql(hash[:github])
+  end
+
+  it 'initializes without parameters' do 
+    expect(described_class.new).to be_an(described_class)
+  end
+
+  it 'raises exception when argument is not a hash' do 
+    expect {described_class.new(Object.new)}.to raise_error(ArgumentError)
+  end
+
+  it 'assign new values' do 
+    context = described_class.new
+    context.dog_name = 'mali'
+    context.country = 'lisbon'
+    context.age = 1
+
+    expect(context.dog_name).to eql('mali')
+    expect(context.country).to eql('lisbon')
+    expect(context.age).to eql(1)
+  end
+
+  it 'handle hash with indifference' do 
+    hash = { "name" => 'thiago', last: 'dantas'}
+    context = described_class.new(hash)
+    expect(context.name).to eql('thiago')
+    expect(context.last).to eql('dantas')
+  end
+
+  it 'is success when there is no error' do 
+    context = described_class.new({})
+    expect(context.success?).to eql(true)
+  end
+
+  it 'adds error messages to errors' do 
+    context = described_class.new({})
+    context.failure(:email, 'email already exist')
+    expect(context.errors.length).to eql(1)
+    expect(context.errors.first).to eql({ email: 'email already exist' })
+  end
+
+  it 'fails when exist errors' do
+    context = described_class.new({})
+    context.failure(:email, 'email already exist')
+    expect(context.success?).to eql(false)
+  end
+
+end
+

data/spec/spec_helper.rb

@@ -0,0 +1,10 @@
+require 'usecasing'
+
+RSpec.configure do |config|
+  config.treat_symbols_as_metadata_keys_with_true_values = true
+  config.run_all_when_everything_filtered = true
+  config.filter_run :focus
+  config.mock_framework = :mocha
+
+  config.order = 'random'
+end

data/spec/usecase_base_spec.rb

@@ -0,0 +1,268 @@
+require 'spec_helper'
+
+describe UseCase::Base do
+
+  context "depends" do 
+
+    it 'initialize without any dependency' do 
+      AppUseCaseInitialize = Class.new(UseCase::Base)
+      expect(AppUseCaseInitialize.dependencies).to be_empty
+    end
+
+    it "adds usecase dependency" do
+      AppOtherUseCase = Class.new
+      AppUseCase = Class.new(UseCase::Base) do 
+        depends AppOtherUseCase
+      end
+
+      expect(AppUseCase.dependencies).to eql([AppOtherUseCase])
+    end
+
+
+    it 'subclass adds dependency from subclass to superclass' do
+
+      SuperClassDependency =  Class.new(UseCase::Base)
+      UseCaseSuperClass = Class.new(UseCase::Base) do 
+        depends SuperClassDependency
+      end
+
+      SubClassDependency = Class.new(UseCase::Base)
+      UseCaseSubClass = Class.new(UseCaseSuperClass) do 
+        depends SubClassDependency
+      end
+
+      expect(UseCaseSubClass.dependencies).to eql([SubClassDependency, SuperClassDependency])
+      #idempotent operation
+      expect(UseCaseSubClass.dependencies).to eql([SubClassDependency, SuperClassDependency])
+
+    end
+
+
+  end
+
+
+  context '##perform' do 
+
+    it 'call instance #perform method' do 
+      AppUseCaseInstance = Class.new(UseCase::Base) do 
+        def perform
+          #some business rule here
+        end
+      end
+      AppUseCaseInstance.any_instance.expects(:perform).once
+      AppUseCaseInstance.perform
+    end
+
+    it 'receives receives a hash and create a execution context' do 
+
+      SendEmailUseCase = Class.new(UseCase::Base) do 
+        def perform
+          context.sent = 'sent'
+        end
+      end
+
+      ctx = SendEmailUseCase.perform({email: 'thiago.teixeira.dantas@gmail.com' })
+      expect(ctx.sent).to eql('sent')
+      expect(ctx.email).to eql('thiago.teixeira.dantas@gmail.com')
+    end
+
+    it 'must receive an hash' do 
+      UseCaseArgumentException = Class.new(UseCase::Base)
+      expect{ UseCaseArgumentException.perform(Object.new) }.to raise_error(ArgumentError)
+    end
+
+    it 'with success when usecase do not register failure' do 
+      pending
+    end
+
+    it 'fail when usecase register failure' do 
+      pending
+    end
+
+
+    it 'detects cyclic' do 
+
+      CyclicFirst = Class.new(UseCase::Base) 
+      CyclicSecond = Class.new(UseCase::Base) do 
+        depends CyclicFirst
+      end
+
+      CyclicFirst.instance_eval do
+        depends CyclicSecond
+      end
+
+      FinalUseCase = Class.new(UseCase::Base) do 
+        depends CyclicSecond
+      end
+
+      expect { FinalUseCase.perform }.to raise_error(StandardError, /cyclic detected/)
+
+    end
+   
+  end
+
+  context '##perfoms execution chain' do 
+    it 'executes in lexical order cascading context among usecases' do
+      
+      FirstUseCase = Class.new(UseCase::Base) do 
+        def perform
+          context.first = context.first_arg
+        end
+      end
+      
+      SecondUseCase = Class.new(UseCase::Base) do 
+        def perform
+          context.second = context.second_arg
+        end
+      end 
+
+      UseCaseChain = Class.new(UseCase::Base) do 
+        depends FirstUseCase, SecondUseCase
+      end
+
+      ctx = UseCaseChain.perform({:first_arg => 1, :second_arg => 2})
+      expect(ctx.first).to  eql(1)
+      expect(ctx.second).to eql(2)
+    end
+
+
+    it 'stops the flow when failure happen' do 
+
+      FirstUseCaseFailure = Class.new(UseCase::Base) do 
+        def perform
+          context.first = context.first_arg
+        end
+      end
+      
+      SecondUseCaseFailure = Class.new(UseCase::Base) do 
+        
+        def perform
+          context.second = context.second_arg
+          failure(:second, 'next will not be called')
+        end
+
+      end
+
+      ThirdUseCaseFailure = Class.new(UseCase::Base) do 
+        def perform
+          context.third = true
+        end
+      end
+
+      UseCaseFailure = Class.new(UseCase::Base) do
+        depends FirstUseCaseFailure, SecondUseCaseFailure, ThirdUseCaseFailure
+      end
+
+      ThirdUseCaseFailure.any_instance.expects(:perform).never
+      UseCaseFailure.perform
+      
+    end
+  end
+
+  context '#perform' do
+    it 'receive an Context instance' do 
+      InstanceUseCase = Class.new(UseCase::Base) do 
+        def perform
+          context.executed = true
+        end
+      end
+      ctx = UseCase::Context.new
+      InstanceUseCase.new(ctx).perform
+      expect(ctx.executed).to be_true
+    end 
+  end
+
+
+  context 'rolling back the flow' do
+
+    it 'rollback without dependencies' do
+
+      UseCaseWithRollback = Class.new(UseCase::Base) do
+
+        def perform
+          failure(:rollback, 'must be called')
+        end
+
+        def rollback
+          context.rollback_executed = 'true'
+        end
+
+      end
+
+      context = UseCaseWithRollback.perform
+      expect(context.rollback_executed).to eql('true')
+
+    end
+
+    it 'in reverse order of execution' do
+      order = 0
+      
+      UseCaseWithRollbackOrderDepdens = Class.new(UseCase::Base) do 
+        define_method :rollback do
+          order += 1
+          context.first_rollback = order
+        end
+
+      end
+
+      UseCaseWithRollbackOrder = Class.new(UseCase::Base) do
+        depends UseCaseWithRollbackOrderDepdens
+
+        def perform
+          failure(:rollback, 'error')
+        end
+
+        define_method :rollback do 
+          order += 1
+          context.second_rollback = order
+        end
+      end
+
+      context = UseCaseWithRollbackOrder.perform
+      expect(context.first_rollback).to  eql(1)
+      expect(context.second_rollback).to  eql(2)
+    end
+
+
+    it 'only rollbacks usecase that ran' do 
+      
+      UseCaseFailRanThird = Class.new(UseCase::Base) do 
+ 
+        def rollback
+          context.should_not_appear = 'true'
+        end
+
+      end
+
+      UseCaseFailRanSecond = Class.new(UseCase::Base) do 
+        
+        def perform
+          failure(:rollback, 'error')
+        end
+
+
+        def rollback
+          context.rollback_second 'true_2'
+        end
+
+      end      
+
+      UseCaseFailRanFirst = Class.new(UseCase::Base) do 
+
+        def rollback
+          context.rollback_first = 'true_1'
+        end
+
+      end
+
+      UseCaseFailRan = Class.new(UseCase::Base) do
+        depends UseCaseFailRanFirst, UseCaseFailRanSecond, UseCaseFailRanThird
+      end
+
+      context = UseCaseFailRan.perform
+      expect(context.should_not_appear).to be_nil
+
+    end
+  end
+
+end

data/usecasing.gemspec

@@ -0,0 +1,26 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'usecasing/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = "usecasing"
+  gem.version       = Usecasing::VERSION
+  gem.authors       = ["Thiago Dantas"]
+  gem.email         = ["thiago.teixeira.dantas@gmail.com"]
+  gem.description   = %q{UseCase Driven approach to your code}
+  gem.summary       = %q{UseCase Driven Approach}
+  gem.homepage      = ""
+
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ["lib"]
+
+
+  #development dependecy
+  gem.add_development_dependency "rspec"
+  gem.add_development_dependency "rake"
+  gem.add_development_dependency "mocha"
+  
+end

metadata

@@ -0,0 +1,117 @@
+--- !ruby/object:Gem::Specification
+name: usecasing
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Thiago Dantas
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-12-20 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: UseCase Driven approach to your code
+email:
+- thiago.teixeira.dantas@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rspec
+- .travis.yml
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/usecasing.rb
+- lib/usecasing/base.rb
+- lib/usecasing/context.rb
+- lib/usecasing/version.rb
+- spec/context_spec.rb
+- spec/spec_helper.rb
+- spec/usecase_base_spec.rb
+- usecasing.gemspec
+homepage: ''
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: 2175319097785181606
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: 2175319097785181606
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: UseCase Driven Approach
+test_files:
+- spec/context_spec.rb
+- spec/spec_helper.rb
+- spec/usecase_base_spec.rb