kompass/usecasing

Responsability Centric with use cases. Enjoy your code !

UseCase your code

Installation

Add this line to your application's Gemfile:

gem 'usecasing'

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 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 before
			@user = context.curent_user
		end
		
		def perform
		
			# 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 before
			@invoice = context.invoice
		end
		
		def perform
			@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

Stopping the UseCase dependencies Flow

There are 2 ways to stop the dependency flow.

• stop! ( stop the flow without marking the usecase with error )
• failure ( stop the flow but mark the usecase with errors )

Imagine a Read Through Cache Strategy. How can we stop the usecase flow without marking as failure ?

   class ReadThrough < UseCase::Base
      depends MemCacheReader, DataBaseReader, MemCacheWriter
   end
  
   class MemCacheReader < UseCase::Base
     def perform
       context.data = CacheAdapter.read('key')
       stop! if context.data
     end
   end

   class DataBaseReader < UseCase::Base
     def perform
       context.data = DataBase.find('key')
     end
   end
   
   class MemCacheWriter < UseCase::Base
     def perform
       CacheAdapter.write('key', context.data);
     end
   end

Let me know what do you think about it.

UseCase::Base contract

        # None of those methods are required.
         

	class BusinessRule < UseCase::Base
	  
	  def before
	    # executed before perform
	  end
	  
	  def perform
	    # execute the responsability that you want
	  end
	  
	  def rollback
	   # Will be called only on failure
	  end
	  
	end

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