jonatasdaniel / interaptor

Easy Interactor gem for ruby apps

Interaptor

Installation

Add this line to your application's Gemfile:

gem 'interaptor'

And then execute:

$ bundle

Or install it yourself as:

$ gem install interaptor

Why?

Interactor is a single purpose object used to encapsulate business logic of the application. Inspired by collectiveidea/interactor.

The reason behind creating another Interactor Ruby gem is: I would like to have an object that I could instantiate and pass parameters in, like a PORO object. I'm not a big fan of calling my business objects using class methods.

Usage

• create your interactor class

class CreateBankAccount
  include Interaptor

  def initialize(current_user)
    @current_user = current_user
  end

  def execute(name:, account_number:, routing_number:)
    # do something
    bank_account = BankAccount.create!(
      name: name, account_number: account_number, routing_number: routing_number
    )

    return bank_account
  end
end

and call it

result = CreateBankAccount.new(my_logged_user).call(**bank_account_params)
if result.success?
  result.value # value is the object returned in your interactor, in this case, bank_account
else
  result.errors.each do |error|
    puts "Some error happened related to #{error.source}. Detail: #{error.message}"
  end
end

or you can call! expecting an exception if some error happens

begin
  bank_account = CreateBankAccount.new(my_logged_user).call!(**bank_account_params)
rescue Interaptor::Failure => e
  e.errors.each do |error|
    puts "Some error happened related to #{error.source}. Detail: #{error.message}"
  end
end

To add errors inside your interactor class you have three ways:

• add error and keep with your interactor processing (keep in mind that this option will not raise an exception when calling call! method)

class CreateBankAccount
  include Interaptor

  def execute
    add_error('Some error', source: 'optional source')

    #do something
  end

end

• add error and stop processing

class CreateBankAccount
  include Interaptor

  def execute
    fail!('Some error', source: 'optional source')

    #nothing more will be executed here
  end

end

• add multiple errors and stop processing

class CreateBankAccount
  include Interaptor

  def execute
    add_error('Some error', source: 'optional source')
    add_error('Some error again', source: 'optional source')
    fail!

    #nothing more will be executed here
  end

end

You also have the option to add before/after callbacks like:

class CreateBankAccount
  include Interaptor

  before do
    # execute something before execute method
  end

  after do
    # execute something after execute method if no exception is thrown
  end

  def execute
    #something here
  end

end

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/jonatasdaniel/interaptor. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

To run tests: docker-compose up

To release a new version: docker-compose run --rm -v ~/.gitconfig:/root/.gitconfig -v ~/.ssh/:/root/.ssh/ -v ~/.gem/:/root/.gem/ -v $(pwd):/interaptor/ -w /interaptor interaptor rake release

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the Interaptor project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.

interaptor's Issues

Add the option to customize the call method name

Possibility to call UserCreator.new.some_custom_method instead of UserCreator.new.call

Allow custom exception class on `fail!` method

On fail! method, it should be able to use a custom exception to handle custom errors.

Add the ability to return a block on `call` method

Add the ability to return a block on call method.

MyInteractorClass.new.call do |result|
  if result.success?
    # do something
  else
    # show errors
  end
end

Create sequencial interactors

Open to discuss how to create a feature to have sequencial interactors.

E.G.:
CheckoutOrder has CreateCreditCard, PayOrder and AddToShipQueue as sequencial interactors. If some of these fail, the entire process stops and in some cases, we need rollback.

Points to decide:

• decide when the sequencial will be called (explicit or implicit)
• find a way to pass constructor params to interactor objects
• find a way how to rollback the interactor process (maybe have explicit commit and rollback hooks on each interactor)