module Interactor::Contracts::DSL

Defines the class-level DSL that enables Interactor contracts.

Attributes

defined_expectations_hook[R]

Flags whether the expectations hook has been defined

@api private @return [TrueClass, FalseClass] true if the hook is defined

defined_expectations_hook?[R]

Flags whether the expectations hook has been defined

@api private @return [TrueClass, FalseClass] true if the hook is defined

defined_promises_hook[R]

Flags whether the promises hook has been defined

@api private @return [TrueClass, FalseClass] true if the hook is defined

defined_promises_hook?[R]

Flags whether the promises hook has been defined

@api private @return [TrueClass, FalseClass] true if the hook is defined

Public Instance Methods

assures(&block)
Alias for: promises
config(&block) click to toggle source

Sends configuration set up to the underlying contracts in the terms

@example

class CreatePerson
  include Interactor
  include Interactor::Contracts

  config do
    messages.backend = :i18n
    messages.top_namespace = :my_app
    messages.load_paths << File.join(__dir__, '..', 'errors.yml')
  end
end

@api public @param [Block] block the block to execute for the underlying contracts @return [void]

# File lib/interactor/contracts/dsl.rb, line 51
def config(&block)
  contract.config(&block)
end
contract() click to toggle source

The Contract to enforce on calls to the Interactor

@example

class CreatePerson
  include Interactor
  include Interactor::Contracts

  promises do
    required(:person).filled
  end

  contracts  #=> <#Interactor::Contracts::Contract>
end

@api semipublic @return [Contract]

# File lib/interactor/contracts/dsl.rb, line 71
def contract
  @contract ||= Contract.new
end
expects(&block) click to toggle source

Defines the expectations of an Interactor and creates a before hook

@example

class CreatePerson
  include Interactor
  include Interactor::Contracts

  expects do
    required(:name).filled
  end

  def call
    context.person = Person.create!(:name => context.name)
  end
end

CreatePerson.call(:first_name => "Billy").success?  #=> false
CreatePerson.call(:name => "Billy").success?        #=> true

@api public @param [Block] block the block defining the expectations @return [void]

# File lib/interactor/contracts/dsl.rb, line 97
def expects(&block)
  contract.add_expectation(&block)
  define_expectations_hook
end
inherit_contract(contract) click to toggle source

Allows for the inheritance of contracts in subclasses

@api private @param [Contract] contract @return [void]

# File lib/interactor/contracts/dsl.rb, line 107
def inherit_contract(contract)
  @contract = Contract.new(
    promises: contract.promises.clone,
    expectations: contract.expectations.clone,
    consequences: contract.consequences.clone
  )
  define_promises_hook
  define_expectations_hook
end
on_breach(&block) click to toggle source

Defines a consequence that is called when a contract is breached

@example

class CreatePerson
  include Interactor
  include Interactor::Contracts

  expects do
    required(:name).filled
  end

  on_breach do |breaches|
    context.fail!(:message => "invalid_#{breaches.first.property}")
  end

  def call
    context.person = Person.create!(:name => context.name)
  end
end

CreatePerson.call(:first_name => "Billy").message  #=> "invalid_name"

@api public @param [Block] block the consequence as a block of arity 1. @return [void]

# File lib/interactor/contracts/dsl.rb, line 142
def on_breach(&block)
  contract.add_consequence(block)
end
promises(&block) click to toggle source

Defines the promises of an Interactor and creates an after hook

@example

class CreatePerson
  include Interactor
  include Interactor::Contracts

  promises do
    required(:person).filled
  end

  def call
    context.person = Person.new
  end
end

@api public @param [Block] block the block defining the promises @return [void]

# File lib/interactor/contracts/dsl.rb, line 28
def promises(&block)
  contract.add_promise(&block)
  define_promises_hook
end
Also aliased as: assures

Private Instance Methods

define_expectations_hook() click to toggle source

Defines a before hook that validates the Interactor's input

@api private @raise [Interactor::Failure] if the input fails to meet its contract. @return [void]

# File lib/interactor/contracts/dsl.rb, line 180
def define_expectations_hook
  return if defined_expectations_hook?

  before { enforce_contracts(contract.expectations) }

  @defined_expectations_hook = true
end
define_promises_hook() click to toggle source

Defines an after hook that validates the Interactor's output

@api private @raise [Interactor::Failure] if the input fails to meet its contract. @return [void]

# File lib/interactor/contracts/dsl.rb, line 167
def define_promises_hook
  return if defined_promises_hook?

  after { enforce_contracts(contract.promises) }

  @defined_promises_hook = true
end
inherited(child) click to toggle source

Defines a callback for class inheritance

@api private @param [Class] child a child of inherited class @return [void]

# File lib/interactor/contracts/dsl.rb, line 193
def inherited(child)
  child.inherit_contract(contract)
end