RestMyCase

Light Ruby gem with everything you need in a "The Clean Architecture" use case scenario.

Many thanks to @tdantas and @junhanamaki and a shout-out to @joaquimadraz and his compel ruby validations gem.

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

Your business logic goes into separated use cases...

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.

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.

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.

Organize your use cases by single responsibilities and establish your use case flow through "dependencies".

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"

Methods: #setup, #perform, #rollback and #final

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.

Default behaviour is to run your dependencies (#setup, #perform, #rollback and #final) methods, first.

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.

#skip, #abort, #error and #invoke have a "bang!" version that will raise a controlled exception, preventing the remaining lines of code from running.

class UseCase1 < RestMyCase::Base
  def perform
    puts 'before #error!'
    error!
    puts 'after #error!'
  end
end

irb> UseCase1.perform #will print only
"before #error!"

The returning object is an instance of RestMyCase::Context::Base class that inherits from OpenStruct and implements the following methods:

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.

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:

UseCase2#setup -> UseCase3#setup -> UseCase1#setup ->
UseCase2#perform -> UseCase3#perform -> UseCase1#perform ->
UseCase2#final -> UseCase3#final -> UseCase1#final

UseCase2#setup -> UseCase3#setup -> UseCase1#setup ->
UseCase2#perform -> UseCase1#perform ->
UseCase2#final -> UseCase3#final -> UseCase1#final

UseCase2#setup -> UseCase3#setup ->
UseCase3#rollback -> UseCase2#rollback ->
UseCase2#final -> UseCase3#final -> UseCase1#final

UseCase2#setup -> UseCase3#setup -> UseCase1#setup ->
UseCase2#perform -> UseCase3#perform ->
UseCase3#rollback -> UseCase2#rollback ->
UseCase2#final -> UseCase3#final -> UseCase1#final

WIP

class UseCase1 < RestMyCase::Base
  include RestMyCase::Status
end

Adds following methods:

#failure! is also present and does the same as the other flow control "bang!" methods (see section 5).

WIP

class UseCase1 < RestMyCase::Base
  include RestMyCase::HttpStatus
end

Includes the module RestMyCase::Status and #context becomes an instance of RestMyCase::Context::HttpStatus.

WIP