Reactor

reactor

The top-level reactor DSL

Nested DSLs

• middlewares

  • middleware

• around

  • argument
  • wait_for
  • where
  • guard

• collect

  • argument
  • wait_for
  • where
  • guard

• compose

  • argument
  • wait_for
  • where
  • guard

• debug

  • argument
  • wait_for
  • where
  • guard

• flunk

  • argument
  • wait_for
  • where
  • guard

• group

  • argument
  • wait_for
  • where
  • guard

• input

• map

  • argument
  • wait_for
  • where
  • guard

• recurse

  • argument
  • wait_for
  • where
  • guard

• step

  • argument
  • wait_for
  • where
  • guard

• switch

  • matches?

  • default

• template

  • argument
  • wait_for
  • where
  • guard

Options

reactor.middlewares

Middleware to be added to the Reactor

Nested DSLs

• middleware

reactor.middlewares.middleware

middleware module

Name a middleware to be added to the Reactor.

Arguments

Options

Introspection

Target: Reactor.Dsl.Middleware

reactor.around

around name, fun \\ nil

Wrap a function around a group of steps.

Nested DSLs

• argument
• wait_for
• where
• guard

Arguments

Options

reactor.around.argument

argument name, source \\ nil

Specifies an argument to a Reactor step.

Each argument is a value which is either the result of another step, or an input value.

Individual arguments can be transformed with an arbitrary function before being passed to any steps.

Examples

argument :name, input(:name)

argument :year, input(:date, [:year])

argument :user, result(:create_user)

argument :user_id, result(:create_user) do
  transform & &1.id
end

argument :user_id, result(:create_user, [:id])

argument :three, value(3)

Arguments

Options

Introspection

Target: Reactor.Dsl.Argument

reactor.around.wait_for

wait_for names

Wait for the named step to complete before allowing this one to start.

Desugars to argument :_, result(step_to_wait_for)

Examples

wait_for :create_user

Arguments

Options

Introspection

Target: Reactor.Dsl.WaitFor

reactor.around.where

where predicate

Only execute the surrounding step if the predicate function returns true.

This is a simple version of guard which provides more flexibility at the cost of complexity.

Examples

step :read_file do
  argument :path, input(:path)
  run &File.read(&1.path)
  where &File.exists?(&1.path)
end

Arguments

Options

Introspection

Target: Reactor.Dsl.Where

reactor.around.guard

guard fun

Provides a flexible method for conditionally executing a step, or replacing it's result.

Expects a two arity function which takes the step's arguments and context and returns one of the following:

• :cont - the guard has passed.
• {:halt, result} - the guard has failed - instead of executing the step use the provided result.

Examples

step :read_file_via_cache do
  argument :path, input(:path)
  run &File.read(&1.path)
  guard fn %{path: path}, %{cache: cache} ->
    case Cache.get(cache, path) do
      {:ok, content} -> {:halt, {:ok, content}}
      _ -> :cont
    end
  end
end

Arguments

Options

Introspection

Target: Reactor.Dsl.Guard

Introspection

Target: Reactor.Dsl.Around

reactor.collect

collect name

A Reactor step which simply collects and returns it's arguments.

Arguments can optionally be transformed before returning.

Nested DSLs

• argument
• wait_for
• where
• guard

Examples

collect :latest_release_uri do
  argument :repository, input(:repository)
  argument :organisation, input(:organisation)

  transform fn inputs ->
    %{uri: "https://api.github.com/repos/#{inputs.organisation}/#{inputs.repository}/releases/latest"}
  end
end

Arguments

Options

reactor.collect.argument

argument name, source \\ nil

Specifies an argument to a Reactor step.

Each argument is a value which is either the result of another step, or an input value.

Individual arguments can be transformed with an arbitrary function before being passed to any steps.

Examples

argument :name, input(:name)

argument :year, input(:date, [:year])

argument :user, result(:create_user)

argument :user_id, result(:create_user) do
  transform & &1.id
end

argument :user_id, result(:create_user, [:id])

argument :three, value(3)

Arguments

Options

Introspection

Target: Reactor.Dsl.Argument

reactor.collect.wait_for

wait_for names

Wait for the named step to complete before allowing this one to start.

Desugars to argument :_, result(step_to_wait_for)

Examples

wait_for :create_user

Arguments

Options

Introspection

Target: Reactor.Dsl.WaitFor

reactor.collect.where

where predicate

Only execute the surrounding step if the predicate function returns true.

This is a simple version of guard which provides more flexibility at the cost of complexity.

Examples

step :read_file do
  argument :path, input(:path)
  run &File.read(&1.path)
  where &File.exists?(&1.path)
end

Arguments

Options

Introspection

Target: Reactor.Dsl.Where

reactor.collect.guard

guard fun

Provides a flexible method for conditionally executing a step, or replacing it's result.

Expects a two arity function which takes the step's arguments and context and returns one of the following:

• :cont - the guard has passed.
• {:halt, result} - the guard has failed - instead of executing the step use the provided result.

Examples

step :read_file_via_cache do
  argument :path, input(:path)
  run &File.read(&1.path)
  guard fn %{path: path}, %{cache: cache} ->
    case Cache.get(cache, path) do
      {:ok, content} -> {:halt, {:ok, content}}
      _ -> :cont
    end
  end
end

Arguments

Options

Introspection

Target: Reactor.Dsl.Guard

Introspection

Target: Reactor.Dsl.Collect

reactor.compose

compose name, reactor

Compose another Reactor into this one.

Allows place another Reactor into this one as if it were a single step.

Example

compose :create_user, UserReactor do argument :name, input(:user_name) argument :email, input(:user_email) allow_async? false end

Nested DSLs

• argument
• wait_for
• where
• guard

Arguments

Options

reactor.compose.argument

argument name, source \\ nil

Specifies an argument to a Reactor step.

Each argument is a value which is either the result of another step, or an input value.

Individual arguments can be transformed with an arbitrary function before being passed to any steps.

Examples

argument :name, input(:name)

argument :year, input(:date, [:year])

argument :user, result(:create_user)

argument :user_id, result(:create_user) do
  transform & &1.id
end

argument :user_id, result(:create_user, [:id])

argument :three, value(3)

Arguments

Options

Introspection

Target: Reactor.Dsl.Argument

reactor.compose.wait_for

wait_for names

Wait for the named step to complete before allowing this one to start.

Desugars to argument :_, result(step_to_wait_for)

Examples

wait_for :create_user

Arguments

Options

Introspection

Target: Reactor.Dsl.WaitFor

reactor.compose.where

where predicate

Only execute the surrounding step if the predicate function returns true.

This is a simple version of guard which provides more flexibility at the cost of complexity.

Examples

step :read_file do
  argument :path, input(:path)
  run &File.read(&1.path)
  where &File.exists?(&1.path)
end

Arguments

Options

Introspection

Target: Reactor.Dsl.Where

reactor.compose.guard

guard fun

Provides a flexible method for conditionally executing a step, or replacing it's result.

Expects a two arity function which takes the step's arguments and context and returns one of the following:

• :cont - the guard has passed.
• {:halt, result} - the guard has failed - instead of executing the step use the provided result.

Examples

step :read_file_via_cache do
  argument :path, input(:path)
  run &File.read(&1.path)
  guard fn %{path: path}, %{cache: cache} ->
    case Cache.get(cache, path) do
      {:ok, content} -> {:halt, {:ok, content}}
      _ -> :cont
    end
  end
end

Arguments

Options

Introspection

Target: Reactor.Dsl.Guard

Introspection

Target: Reactor.Dsl.Compose

reactor.debug

debug name

Inserts a step which will send debug information to the Logger.

Nested DSLs

• argument
• wait_for
• where
• guard

Examples

debug :debug do
  argument :suss, result(:suss_step)
end

Arguments

Options

reactor.debug.argument

argument name, source \\ nil

Specifies an argument to a Reactor step.

Each argument is a value which is either the result of another step, or an input value.

Individual arguments can be transformed with an arbitrary function before being passed to any steps.

Examples

argument :name, input(:name)

argument :year, input(:date, [:year])

argument :user, result(:create_user)

argument :user_id, result(:create_user) do
  transform & &1.id
end

argument :user_id, result(:create_user, [:id])

argument :three, value(3)

Arguments

Options

Introspection

Target: Reactor.Dsl.Argument

reactor.debug.wait_for

wait_for names

Wait for the named step to complete before allowing this one to start.

Desugars to argument :_, result(step_to_wait_for)

Examples

wait_for :create_user

Arguments

Options

Introspection

Target: Reactor.Dsl.WaitFor

reactor.debug.where

where predicate

Only execute the surrounding step if the predicate function returns true.

This is a simple version of guard which provides more flexibility at the cost of complexity.

Examples

step :read_file do
  argument :path, input(:path)
  run &File.read(&1.path)
  where &File.exists?(&1.path)
end

Arguments

Options

Introspection

Target: Reactor.Dsl.Where

reactor.debug.guard

guard fun

Provides a flexible method for conditionally executing a step, or replacing it's result.

Expects a two arity function which takes the step's arguments and context and returns one of the following:

• :cont - the guard has passed.
• {:halt, result} - the guard has failed - instead of executing the step use the provided result.

Examples

step :read_file_via_cache do
  argument :path, input(:path)
  run &File.read(&1.path)
  guard fn %{path: path}, %{cache: cache} ->
    case Cache.get(cache, path) do
      {:ok, content} -> {:halt, {:ok, content}}
      _ -> :cont
    end
  end
end

Arguments

Options

Introspection

Target: Reactor.Dsl.Guard

Introspection

Target: Reactor.Dsl.Debug

reactor.flunk

flunk name, message

Creates a step which will always cause the Reactor to exit with an error.

This step will flunk with a Reactor.Error.Invalid.ForcedFailureError with it's message set to the provided message. Additionally, any arguments to the step will be stored in the exception under the arguments key.

Nested DSLs

• argument
• wait_for
• where
• guard

Examples

flunk :outaroad, "Ran out of road before reaching 88Mph"

Arguments

Options

reactor.flunk.argument

argument name, source \\ nil

Specifies an argument to a Reactor step.

Each argument is a value which is either the result of another step, or an input value.

Individual arguments can be transformed with an arbitrary function before being passed to any steps.

Examples

argument :name, input(:name)

argument :year, input(:date, [:year])

argument :user, result(:create_user)

argument :user_id, result(:create_user) do
  transform & &1.id
end

argument :user_id, result(:create_user, [:id])

argument :three, value(3)

Arguments

Options

Introspection

Target: Reactor.Dsl.Argument

reactor.flunk.wait_for

wait_for names

Wait for the named step to complete before allowing this one to start.

Desugars to argument :_, result(step_to_wait_for)

Examples

wait_for :create_user

Arguments

Options

Introspection

Target: Reactor.Dsl.WaitFor

reactor.flunk.where

where predicate

Only execute the surrounding step if the predicate function returns true.

This is a simple version of guard which provides more flexibility at the cost of complexity.

Examples

step :read_file do
  argument :path, input(:path)
  run &File.read(&1.path)
  where &File.exists?(&1.path)
end

Arguments

Options

Introspection

Target: Reactor.Dsl.Where

reactor.flunk.guard

guard fun

Provides a flexible method for conditionally executing a step, or replacing it's result.

Expects a two arity function which takes the step's arguments and context and returns one of the following:

• :cont - the guard has passed.
• {:halt, result} - the guard has failed - instead of executing the step use the provided result.

Examples

step :read_file_via_cache do
  argument :path, input(:path)
  run &File.read(&1.path)
  guard fn %{path: path}, %{cache: cache} ->
    case Cache.get(cache, path) do
      {:ok, content} -> {:halt, {:ok, content}}
      _ -> :cont
    end
  end
end

Arguments

Options

Introspection

Target: Reactor.Dsl.Guard

Introspection

Target: Reactor.Dsl.Flunk

reactor.group

group name

Call functions before and after a group of steps.

Nested DSLs

• argument
• wait_for
• where
• guard

Arguments

Options

reactor.group.argument

argument name, source \\ nil

Specifies an argument to a Reactor step.

Each argument is a value which is either the result of another step, or an input value.

Individual arguments can be transformed with an arbitrary function before being passed to any steps.

Examples

argument :name, input(:name)

argument :year, input(:date, [:year])

argument :user, result(:create_user)

argument :user_id, result(:create_user) do
  transform & &1.id
end

argument :user_id, result(:create_user, [:id])

argument :three, value(3)

Arguments

Options

Introspection

Target: Reactor.Dsl.Argument

reactor.group.wait_for

wait_for names

Wait for the named step to complete before allowing this one to start.

Desugars to argument :_, result(step_to_wait_for)

Examples

wait_for :create_user

Arguments

Options

Introspection

Target: Reactor.Dsl.WaitFor

reactor.group.where

where predicate

Only execute the surrounding step if the predicate function returns true.

This is a simple version of guard which provides more flexibility at the cost of complexity.

Examples

step :read_file do
  argument :path, input(:path)
  run &File.read(&1.path)
  where &File.exists?(&1.path)
end

Arguments

Options

Introspection

Target: Reactor.Dsl.Where

reactor.group.guard

guard fun

Provides a flexible method for conditionally executing a step, or replacing it's result.

Expects a two arity function which takes the step's arguments and context and returns one of the following:

• :cont - the guard has passed.
• {:halt, result} - the guard has failed - instead of executing the step use the provided result.

Examples

step :read_file_via_cache do
  argument :path, input(:path)
  run &File.read(&1.path)
  guard fn %{path: path}, %{cache: cache} ->
    case Cache.get(cache, path) do
      {:ok, content} -> {:halt, {:ok, content}}
      _ -> :cont
    end
  end
end

Arguments

Options

Introspection

Target: Reactor.Dsl.Guard

Introspection

Target: Reactor.Dsl.Group

reactor.input

input name

Specifies an input to the Reactor.

An input is a value passed in to the Reactor when executing. If a Reactor were a function, these would be it's arguments.

Inputs can be transformed with an arbitrary function before being passed to any steps.

Examples

input :name

input :age do
  transform &String.to_integer/1
end

Arguments

Options

Introspection

Target: Reactor.Dsl.Input

reactor.map

map name

Execute nested steps for every item of an iterator.

Allows you to "map over" a collection applying a some steps to each element, returning a list of new values. The input collection must be bounded - ie you cannot pass infinite streams into this step or it will just loop forever - and because it has to keep the results from each batch will eventually just use up all available RAM.

Under the hood we use Iter to handle lazy iteration of the collection. This means that you can pass an Iter.t or any value for which Iter.IntoIterable is implemented.

Nested DSLs

• argument
• wait_for
• where
• guard

Examples

map :double_numbers do
  source input(:numbers)

  step :double do
    argument :number, element(:double_numbers)

    run fn %{number: number}, _ ->
      {:ok, number * 2}
    end
  end
end

step :get_subscriptions do
  run fn _, _ ->
    Stripe.Subscription.list()
  end
end

map :cancel_subscriptions do
  source result(:get_subscriptions)

  step :cancel do
    argument :sub_id, element(:cancel_subscriptions, [:id])

    run fn args, _ ->
      Stripe.Subscription.cancel(arg.sub_id, %{prorate: true, invoice_now: true})
    end
  end

  return :cancel
end

Arguments

Options

reactor.map.argument

argument name, source \\ nil

Specifies an argument to a Reactor step.

Each argument is a value which is either the result of another step, or an input value.

Individual arguments can be transformed with an arbitrary function before being passed to any steps.

Examples

argument :name, input(:name)

argument :year, input(:date, [:year])

argument :user, result(:create_user)

argument :user_id, result(:create_user) do
  transform & &1.id
end

argument :user_id, result(:create_user, [:id])

argument :three, value(3)

Arguments

Options

Introspection

Target: Reactor.Dsl.Argument

reactor.map.wait_for

wait_for names

Wait for the named step to complete before allowing this one to start.

Desugars to argument :_, result(step_to_wait_for)

Examples

wait_for :create_user

Arguments

Options

Introspection

Target: Reactor.Dsl.WaitFor

reactor.map.where

where predicate

Only execute the surrounding step if the predicate function returns true.

This is a simple version of guard which provides more flexibility at the cost of complexity.

Examples

step :read_file do
  argument :path, input(:path)
  run &File.read(&1.path)
  where &File.exists?(&1.path)
end

Arguments

Options

Introspection

Target: Reactor.Dsl.Where

reactor.map.guard

guard fun

Provides a flexible method for conditionally executing a step, or replacing it's result.

Expects a two arity function which takes the step's arguments and context and returns one of the following:

• :cont - the guard has passed.
• {:halt, result} - the guard has failed - instead of executing the step use the provided result.

Examples

step :read_file_via_cache do
  argument :path, input(:path)
  run &File.read(&1.path)
  guard fn %{path: path}, %{cache: cache} ->
    case Cache.get(cache, path) do
      {:ok, content} -> {:halt, {:ok, content}}
      _ -> :cont
    end
  end
end

Arguments

Options

Introspection

Target: Reactor.Dsl.Guard

Introspection

Target: Reactor.Dsl.Map

reactor.recurse

recurse name, reactor

Execute a reactor recursively until an exit condition is met or maximum iterations are reached.

Allows the output of one iteration to become the input of the next. The reactor must have input/output compatibility to ensure that the outputs from iteration i can be fed into iteration i+1.

Nested DSLs

• argument
• wait_for
• where
• guard

Arguments

Options

reactor.recurse.argument

argument name, source \\ nil

Specifies an argument to a Reactor step.

Each argument is a value which is either the result of another step, or an input value.

Individual arguments can be transformed with an arbitrary function before being passed to any steps.

Examples

argument :name, input(:name)

argument :year, input(:date, [:year])

argument :user, result(:create_user)

argument :user_id, result(:create_user) do
  transform & &1.id
end

argument :user_id, result(:create_user, [:id])

argument :three, value(3)

Arguments

Options

Introspection

Target: Reactor.Dsl.Argument

reactor.recurse.wait_for

wait_for names

Wait for the named step to complete before allowing this one to start.

Desugars to argument :_, result(step_to_wait_for)

Examples

wait_for :create_user

Arguments

Options

Introspection

Target: Reactor.Dsl.WaitFor

reactor.recurse.where

where predicate

Only execute the surrounding step if the predicate function returns true.

This is a simple version of guard which provides more flexibility at the cost of complexity.

Examples

step :read_file do
  argument :path, input(:path)
  run &File.read(&1.path)
  where &File.exists?(&1.path)
end

Arguments

Options

Introspection

Target: Reactor.Dsl.Where

reactor.recurse.guard

guard fun

Provides a flexible method for conditionally executing a step, or replacing it's result.

Expects a two arity function which takes the step's arguments and context and returns one of the following:

• :cont - the guard has passed.
• {:halt, result} - the guard has failed - instead of executing the step use the provided result.

Examples

step :read_file_via_cache do
  argument :path, input(:path)
  run &File.read(&1.path)
  guard fn %{path: path}, %{cache: cache} ->
    case Cache.get(cache, path) do
      {:ok, content} -> {:halt, {:ok, content}}
      _ -> :cont
    end
  end
end

Arguments

Options

Introspection

Target: Reactor.Dsl.Guard

Introspection

Target: Reactor.Dsl.Recurse

reactor.step

step name, impl \\ nil

Specifies a Reactor step.

Steps are the unit of work in a Reactor. Reactor will calculate the dependencies graph between the steps and execute as many as it can in each iteration.

See the Reactor.Step behaviour for more information.

Nested DSLs

• argument
• wait_for
• where
• guard

Examples

step :create_user, MyApp.Steps.CreateUser do
  argument :username, input(:username)
  argument :password_hash, result(:hash_password)
end

step :hash_password do
  argument :password, input(:password)

  run fn %{password: password}, _ ->
    {:ok, Bcrypt.hash_pwd_salt(password)}
  end
end

Arguments

Options

reactor.step.argument

argument name, source \\ nil

Specifies an argument to a Reactor step.

Each argument is a value which is either the result of another step, or an input value.

Individual arguments can be transformed with an arbitrary function before being passed to any steps.

Examples

argument :name, input(:name)

argument :year, input(:date, [:year])

argument :user, result(:create_user)

argument :user_id, result(:create_user) do
  transform & &1.id
end

argument :user_id, result(:create_user, [:id])

argument :three, value(3)

Arguments

Options

Introspection

Target: Reactor.Dsl.Argument

reactor.step.wait_for

wait_for names

Wait for the named step to complete before allowing this one to start.

Desugars to argument :_, result(step_to_wait_for)

Examples

wait_for :create_user

Arguments

Options

Introspection

Target: Reactor.Dsl.WaitFor

reactor.step.where

where predicate

Only execute the surrounding step if the predicate function returns true.

This is a simple version of guard which provides more flexibility at the cost of complexity.

Examples

step :read_file do
  argument :path, input(:path)
  run &File.read(&1.path)
  where &File.exists?(&1.path)
end

Arguments

Options

Introspection

Target: Reactor.Dsl.Where

reactor.step.guard

guard fun

Provides a flexible method for conditionally executing a step, or replacing it's result.

Expects a two arity function which takes the step's arguments and context and returns one of the following:

• :cont - the guard has passed.
• {:halt, result} - the guard has failed - instead of executing the step use the provided result.

Examples

step :read_file_via_cache do
  argument :path, input(:path)
  run &File.read(&1.path)
  guard fn %{path: path}, %{cache: cache} ->
    case Cache.get(cache, path) do
      {:ok, content} -> {:halt, {:ok, content}}
      _ -> :cont
    end
  end
end

Arguments

Options

Introspection

Target: Reactor.Dsl.Guard

Introspection

Target: Reactor.Dsl.Step

reactor.switch

switch name

Use a predicate to determine which steps should be executed.

Nested DSLs

• matches?

• default

Arguments

Options

reactor.switch.matches?

matches? predicate

A group of steps to run when the predicate matches.

Arguments

Options

Introspection

Target: Reactor.Dsl.Switch.Match

reactor.switch.default

If none of the matches? branches match the input, then the default steps will be run if provided.

Options

Introspection

Target: Reactor.Dsl.Switch.Default

Introspection

Target: Reactor.Dsl.Switch

reactor.template

template name

A step which passes all it's arguments as assigns into an EEx template and returns the result.

Nested DSLs

• argument
• wait_for
• where
• guard

Examples

        template :welcome_message do
          arguments :user
          template """
          Welcome <%= @user.name %>! 🎉
          """
        end
        

Arguments

Options

reactor.template.argument

argument name, source \\ nil

Specifies an argument to a Reactor step.

Each argument is a value which is either the result of another step, or an input value.

Individual arguments can be transformed with an arbitrary function before being passed to any steps.

Examples

argument :name, input(:name)

argument :year, input(:date, [:year])

argument :user, result(:create_user)

argument :user_id, result(:create_user) do
  transform & &1.id
end

argument :user_id, result(:create_user, [:id])

argument :three, value(3)

Arguments

Options

Introspection

Target: Reactor.Dsl.Argument

reactor.template.wait_for

wait_for names

Wait for the named step to complete before allowing this one to start.

Desugars to argument :_, result(step_to_wait_for)

Examples

wait_for :create_user

Arguments

Options

Introspection

Target: Reactor.Dsl.WaitFor

reactor.template.where

where predicate

Only execute the surrounding step if the predicate function returns true.

This is a simple version of guard which provides more flexibility at the cost of complexity.

Examples

step :read_file do
  argument :path, input(:path)
  run &File.read(&1.path)
  where &File.exists?(&1.path)
end

Arguments

Options

Introspection

Target: Reactor.Dsl.Where

reactor.template.guard

guard fun

Provides a flexible method for conditionally executing a step, or replacing it's result.

Expects a two arity function which takes the step's arguments and context and returns one of the following:

• :cont - the guard has passed.
• {:halt, result} - the guard has failed - instead of executing the step use the provided result.

Examples

step :read_file_via_cache do
  argument :path, input(:path)
  run &File.read(&1.path)
  guard fn %{path: path}, %{cache: cache} ->
    case Cache.get(cache, path) do
      {:ok, content} -> {:halt, {:ok, content}}
      _ -> :cont
    end
  end
end

Arguments

Options

Introspection

Target: Reactor.Dsl.Guard

Introspection

Target: Reactor.Dsl.Template