module Interaktor

When the Interaktor module is included in a class, add the relevant class methods and hooks to that class.

@param base [Class] the class which is including the Interaktor module

# File lib/interaktor.rb, line 12
def self.included(base)
  base.class_eval do
    extend ClassMethods
    include Hooks
    include Callable
  end
end

@param context [Hash, Interaktor::Context] the context object as a hash

with attributes or an already-built context

# File lib/interaktor.rb, line 25
def initialize(context = {})
  @context = Interaktor::Context.build(context)
end

Invoke an Interaktor instance without any hooks, tracking, or rollback. It is expected that the `#call` instance method is overwritten for each interaktor class.

@return [void]

# File lib/interaktor.rb, line 65
def call; end

Fail the current interaktor.

@param failure_attributes [Hash{Symbol=>Object}] the context attributes

@return [void]

# File lib/interaktor.rb, line 34
def fail!(failure_attributes = {})
  # Silently remove any attributes that are not included in the schema
  allowed_keys = self.class.failure_schema.key_map.keys.map { |k| k.name.to_sym }
  failure_attributes.select! { |k, _| allowed_keys.include?(k.to_sym) }

  self.class.validate_failure_schema(failure_attributes)

  @context.fail!(failure_attributes)
end

Reverse prior invocation of an Interaktor instance. Any interaktor class that requires undoing upon downstream failure is expected to overwrite the `#rollback` instance method.

@return [void]

# File lib/interaktor.rb, line 72
def rollback; end

Invoke an interaktor instance along with all defined hooks. The `run` method is used internally by the `call` class method. After successful invocation of the interaktor, the instance is tracked within the context. If the context is failed or any error is raised, the context is rolled back.

@return [void]

# File lib/interaktor.rb, line 81
def run
  run!
rescue Interaktor::Failure # rubocop:disable Lint/SuppressedException
end

Invoke an Interaktor instance along with all defined hooks, typically used internally by `.call!`. After successful invocation of the interaktor, the instance is tracked within the context. If the context is failed or any error is raised, the context is rolled back. This method behaves identically to `#run` with one notable exception - if the context is failed during the invocation of the interaktor, `Interaktor::Failure` is raised.

@raises [Interaktor::Failure]

@return [void]

# File lib/interaktor.rb, line 96
def run!
  with_hooks do
    catch(:early_return) do
      call
    end

    if !@context.early_return? && self.class.required_success_attributes.any?
      raise Interaktor::Error::MissingExplicitSuccessError.new(self, self.class.required_success_attributes)
    end

    @context.called!(self)
  end
rescue StandardError
  @context.rollback!
  raise
end

Terminate execution of the current interaktor and copy the success attributes into the context.

@param success_attributes [Hash{Symbol=>Object}] the context attributes

@return [void]

# File lib/interaktor.rb, line 50
def success!(success_attributes = {})
  # Silently remove any attributes that are not included in the schema
  allowed_keys = self.class.success_schema.key_map.keys.map { |k| k.name.to_sym }
  success_attributes.select! { |k, _| allowed_keys.include?(k.to_sym) }

  self.class.validate_success_schema(success_attributes)

  @context.success!(success_attributes)
end