`Ash.Reactor` is an extension for [`Reactor`](https://github.com/ash-project/reactor) which adds explicit support for interacting with resources via their defined actions.
See [Getting started with Reactor](https://hexdocs.pm/reactor/getting-started-with-reactor.html) for more information about Reactor.
## Usage
You can either add the `Ash.Reactor` extension to your existing reactors eg:
```elixir
defmodule MyExistingReactor do
use Reactor, extensions: [Ash.Reactor]
end
```
or for your convenience you can use `use Ash.Reactor` which expands to exactly the same as above.
For each action type there is a corresponding step DSL, which needs a name (used
to refer to the result of the step by other steps), a resource and optional
action name (defaults to the primary action if one is not provided).
Actions have several common options and some specific to their particular type.
See the [DSL documentation](dsl-ash-reactor.html) for
details.
### Action inputs
Ash actions take a map of input parameters which are usually a combination of
resource attributes and action arguments. You can provide these values as a
single map using the [`inputs` DSL entity](dsl-ash-reactor.html#reactor-action-inputs) with a map or keyword list which refers to Reactor inputs, results and hard-coded values via Reactor's [predefined template functions](https://hexdocs.pm/reactor/Reactor.Dsl.Argument.html#functions).
For action types that act on a specific resource (ie `update` and `destroy`) you can provide the value using the [`initial` DSL option](dsl-ash-reactor.html#reactor-update-initial).
#### Example
```elixir
input :blog_title
input :blog_body
input :author_email
read :get_author, MyBlog.Author, :get_author_by_email do
inputs %{email: input(:author_email)}
end
create :create_post, MyBlog.Post, :create do
inputs %{
title: input(:blog, [:title]),
body: input(:blog, [:body]),
author_id: result(:get_author, [:email])
}
end
update :author_post_count, MyBlog.Author, :update_post_count do
wait_for :create_post
initial result(:get_author)
end
return :create_post
```
## Handling failure.
Reactor is a saga executor, which means that when failure occurs it tries to
clean up any intermediate state left behind. By default the `create`, `update`
and `destroy` steps do not specify any behaviour for what to do when there is a
failure downstream in the reactor. This can be changed by providing both an
`undo_action` and changing the step's `undo` option to either
`:outside_transaction` or `:always` depending on your resource and datalayer
semantics.
### The `undo` option.
-`:never` - this is the default, and means that the reactor will never try and
undo the action's work. This is the most performant option, as it means that
the reactor doesn't need to store as many intermediate values.
-`:outside_transaction` - this option allows the step to decide at runtime
whether it should support undo based on whether the action is being run within
a transaction. If it is, then no undo is required because the transaction
will rollback.
-`:always` - this forces the step to always undo it's work on failure.