<!--
SPDX-FileCopyrightText: 2019 ash contributors <https://github.com/ash-project/ash/graphs.contributors>

SPDX-License-Identifier: MIT
-->

# Generic Actions

Generic actions are so named because there are no special rules about how they work. A generic action takes arguments and returns a value. The struct used for building input for a generic action is `Ash.ActionInput`.

```elixir
action :say_hello, :string do
  argument :name, :string, allow_nil?: false

  run fn input, _ ->
    {:ok, "Hello: #{input.arguments.name}"}
  end
end
```

A generic action declares its arguments, return type, and implementation, as illustrated above.

> ### No return? No problem! {: .tip}
>
> Generic actions can omit a return type, in which case running them returns `:ok` if successful.
>
> ```elixir
> action :schedule_job do
>   argument :job_name, :string, allow_nil?: false
>   run fn input, _ ->
>     # Schedule the job
>     :ok
>   end
> end
> ```

For a full list of all of the available options for configuring generic actions, see [the Ash.Resource.Dsl documentation](dsl-ash-resource.html#actions-action).

## Calling Generic Actions

The basic formula for calling a generic action looks like this:

```elixir
Resource
|> Ash.ActionInput.for_action(:action_name, %{argument: :value}, ...opts)
|> Ash.run_action!()
```

See the [code interface guide](/documentation/topics/code-interfaces.md) guide for how to
define idiomatic and convenient functions that call your actions.

## Why use generic actions?

The example above could be written as a normal function in elixir, i.e

```elixir
def say_hello(name), do: "Hello: #{name}"
```

The benefit of using generic actions instead of defining normal functions:

- They can be used with api extensions like `ash_json_api` and `ash_graphql`
- Their inputs are type checked and casted
- They support Ash authorization patterns (i.e policies)
- They can be included in the code interface of a resource
- They can be made transactional with a single option (`transaction? true`)

If you don't need any of the above, then there is no problem with writing regular Elixir functions!

## Return types and constraints

Generic actions do not cast their return types. It is expected that the action return a valid value for the type that they declare. However, declaring additional constraints can inform API usage, and make the action more clear. For example:

```elixir
action :priority, :integer do
  constraints [min: 1, max: 3]
  argument :status, :atom, constraints: [one_of: [:high, :medium, :low]]

  run fn input, _ ->
    case input.arguments.status do
      :high -> {:ok, 3}
      :medium -> {:ok, 2}
      :low -> {:ok, 1}
    end
  end
end
```

> #### Returning resource instances {: .info}
>
> It sometimes happens that you want to make a generic action which returns an
> instance or instances of the resource. It's natural to assume that you can
> set your action's return type to the name of your resource. This won't work
> as resources do not define a type, unless they are embedded. In embedded resources, this won't work because the module is still being compiled, so referencing yourself as a type causes a compile error. Instead, use the `:struct` type and the `instance_of` constraint, like so:
>
> ```elixir
> action :get, :struct do
>   constraints instance_of: __MODULE__
>
>   run # ...
> end
> ```
>
> For returning many instances of the resource, you can set your action's return type to
> `{:array, :struct}` and set the `items` constraint to the name of your resource.
>
> ```elixir
>  action :list_resources, {:array, :struct} do
>    constraints items: [instance_of: __MODULE__]
>
>    run # ...
>  end
> ```

## Calling Generic Actions

To execute a generic action in Ash, follow these steps:

1. **Prepare the action input:** Use `Ash.ActionInput.for_action/4` to specify the resource, the action and its arguments.
2. **Run the action:** Use `Ash.run_action/2` to execute the action with the prepared input.

### Example Usage

Consider an `Ash.Resource` with the action `:say_hello`:

```elixir
action :say_hello, :string do
  argument :name, :string, allow_nil?: false

  run fn input, _ ->
    {:ok, "Hello: #{input.arguments.name}"}
  end
end
```

Call this action:

```elixir
{:ok, greeting} = Resource
|> Ash.ActionInput.for_action(:say_hello, %{name: "Alice"})
|> Ash.run_action()

IO.puts(greeting)  # Output: Hello: Alice
```

### Using Code Interface

You can also use [Code Interfaces](documentation/topics/resources/code-interfaces.md) to call actions:

Given a definition like:

```elixir
define :say_hello, args: [:name]
```

```elixir
{:ok, greeting} = Resource.say_hello("Alice")
greeting = Resource.say_hello!("Alice")
```

## Validations and Preparations

Generic actions support validations and preparations, allowing you to add business logic and input validation to your actions.

### Validations

Validations in generic actions work similarly to those in other action types. They validate the action input before the action logic runs.

```elixir
action :create_user, :struct do
  constraints instance_of: __MODULE__

  argument :name, :string, allow_nil?: false
  argument :email, :string, allow_nil?: false
  argument :age, :integer

  validate present([:name, :email])
  validate match(:email, ~r/@/)
  validate compare(:age, greater_than: 13) do
    message "Must be at least 13 years old"
  end

  run fn input, _ ->
    # Create user logic here
    {:ok, %__MODULE__{
      name: input.arguments.name,
      email: input.arguments.email,
      age: input.arguments.age
    }}
  end
end
```

You can also use custom validation modules:

```elixir
action :transfer_funds, :boolean do
  argument :from_account, :string, allow_nil?: false
  argument :to_account, :string, allow_nil?: false
  argument :amount, :decimal, allow_nil?: false

  validate {MyApp.Validations.SufficientFunds, field: :amount}

  run fn input, _ ->
    # Transfer logic here
    {:ok, true}
  end
end
```

### Preparations

Preparations allow you to modify the action input before the action runs. This is useful for setting computed values or applying business logic.

```elixir
action :audit_log, :string do
  argument :action, :string, allow_nil?: false
  argument :details, :map, default: %{}

  prepare fn input, _context ->
    # Add timestamp and actor information
    updated_details = Map.merge(input.arguments.details, %{
      timestamp: DateTime.utc_now(),
      actor_id: input.context[:actor]&.id
    })

    Ash.ActionInput.set_argument(input, :details, updated_details)
  end

  run fn input, _ ->
    # Log the action
    log_entry = "#{input.arguments.action}: #{inspect(input.arguments.details)}"
    {:ok, log_entry}
  end
end
```

You can also use the built-in `build` preparation:

```elixir
action :search_with_defaults do
  argument :query, :string
  argument :filters, :map, default: %{}

  prepare build(
    arguments: %{
      filters: expr(Map.merge(^arg(:filters), %{active: true}))
    }
  )

  run fn input, _ ->
    # Search logic with default filters applied
    {:ok, perform_search(input.arguments.query, input.arguments.filters)}
  end
end
```

## Action Hooks

Generic actions support action-level hooks that run before and after the action execution.

### Before Action Hooks

Before action hooks run immediately before the action logic executes:

```elixir
action :process_payment, :boolean do
  argument :amount, :decimal, allow_nil?: false
  argument :payment_method, :string, allow_nil?: false

  validate present([:amount, :payment_method])

  # Using a function
  prepare before_action(fn input, _context ->
    # Log the payment attempt
    Logger.info("Processing payment of #{input.arguments.amount}")

    # Validate payment method
    if input.arguments.payment_method not in ["credit_card", "bank_transfer"] do
      Ash.ActionInput.add_error(input, "Invalid payment method")
    else
      input
    end
  end)

  run fn input, _ ->
    # Process payment logic
    {:ok, true}
  end
end
```

### After Action Hooks

After action hooks run after successful action execution:

```elixir
action :send_notification, :boolean do
  argument :message, :string, allow_nil?: false
  argument :recipient, :string, allow_nil?: false

  prepare after_action(fn input, result, _context ->
    # Log successful notification
    Logger.info("Notification sent to #{input.arguments.recipient}")

    # Could perform additional side effects here
    {:ok, result}
  end)

  run fn input, _ ->
    # Send notification logic
    send_notification(input.arguments.recipient, input.arguments.message)
    {:ok, true}
  end
end
```

### Using Custom Preparation Modules

You can also create reusable preparation modules for generic actions:

```elixir
defmodule MyApp.Preparations.AuditAction do
  use Ash.Resource.Preparation

  def prepare(input, _opts, context) do
    Ash.ActionInput.before_action(input, fn input ->
      # Log the action attempt
      MyApp.AuditLog.log_action(input.action.name, input.arguments, context.actor)
      input
    end)
    |> Ash.ActionInput.after_action(fn input, result ->
      # Log successful completion
      MyApp.AuditLog.log_success(input.action.name, result, context.actor)
      {:ok, result}
    end)
  end
end
```

Then use it in your action:

```elixir
action :sensitive_operation, :boolean do
  argument :data, :map, allow_nil?: false

  prepare MyApp.Preparations.AuditAction

  run fn input, _ ->
    # Sensitive operation logic
    {:ok, true}
  end
end
```

## Global Validations and Preparations

Generic actions also support global validations and preparations defined at the resource level:

```elixir
defmodule MyApp.MyResource do
  use Ash.Resource

  # Global preparations that apply to all actions
  preparations do
    prepare fn input, _context ->
      # Add tenant information to all actions
      Ash.ActionInput.set_context(input, %{tenant: "default"})
    end do
      # Only apply to generic actions
      on: [:action]
    end
  end

  # Global validations that apply to all actions
  validations do
    validate present(:actor) do
      message "Authentication required"
      on: [:action]  # Only apply to generic actions
    end
  end

  actions do
    action :my_action do
      # Action-specific logic
    end
  end
end
```

## Execution Order

For generic actions, the execution order is:

1. Global preparations/validations (in order of definition)
2. Action preparations/validations (in order of definition)
3. `before_action` hooks
4. Action logic execution
5. `after_action` hooks (success only)

This order ensures that global business logic runs first, followed by action-specific logic, and finally the action hooks.