module Interactor

Public: Interactor methods. Because Interactor is a module, custom Interactor classes should include Interactor rather than inherit from it.

Examples

class MyInteractor
  include Interactor

  def call
    puts context.foo
  end
end

Public Class Methods

included(base) click to toggle source

Internal: Install Interactor's behavior in the given class.

# File lib/interactor.rb, line 20
def self.included(base)
  base.class_eval do
    extend ClassMethods
    include Hooks

    # Public: Gets the Interactor::Context of the Interactor instance.
    attr_reader :context
  end
end

new(context = {}) click to toggle source

Internal: Initialize an Interactor.

context - A Hash whose key/value pairs are used in initializing the

interactor's context. An existing Interactor::Context may also be
given. (default: {})

Examples

MyInteractor.new(foo: "bar")
# => #<MyInteractor @context=#<Interactor::Context foo="bar">>

MyInteractor.new
# => #<MyInteractor @context=#<Interactor::Context>>

# File lib/interactor.rb, line 93
def initialize(context = {})
  @context = Context.build(context)
end

Public Instance Methods

call() click to toggle source

Public: Invoke an Interactor instance without any hooks, tracking, or rollback. It is expected that the “call” instance method is overwritten for each interactor class.

Returns nothing.

# File lib/interactor.rb, line 156
def call
end

rollback() click to toggle source

Public: Reverse prior invocation of an Interactor instance. Any interactor class that requires undoing upon downstream failure is expected to overwrite the “rollback” instance method.

Returns nothing.

# File lib/interactor.rb, line 164
def rollback
end

run() click to toggle source

Internal: Invoke an interactor instance along with all defined hooks. The “run” method is used internally by the “call” class method. The following are equivalent:

MyInteractor.call(foo: "bar")
# => #<Interactor::Context foo="bar">

interactor = MyInteractor.new(foo: "bar")
interactor.run
interactor.context
# => #<Interactor::Context foo="bar">

After successful invocation of the interactor, the instance is tracked within the context. If the context is failed or any error is raised, the context is rolled back.

Returns nothing.

# File lib/interactor.rb, line 114
def run
  run!
rescue Failure
end

run!() click to toggle source

Internal: Invoke an Interactor instance along with all defined hooks. The “run!” method is used internally by the “call!” class method. The following are equivalent:

MyInteractor.call!(foo: "bar")
# => #<Interactor::Context foo="bar">

interactor = MyInteractor.new(foo: "bar")
interactor.run!
interactor.context
# => #<Interactor::Context foo="bar">

After successful invocation of the interactor, the instance is tracked within the context. If the context is failed or any error is raised, the context is rolled back.

The “run!” method behaves identically to the “run” method with one notable exception. If the context is failed during invocation of the interactor, the Interactor::Failure is raised.

Returns nothing. Raises Interactor::Failure if the context is failed.

# File lib/interactor.rb, line 141
def run!
  with_hooks do
    call
    context.called!(self)
  end
rescue
  context.rollback!
  raise
end