# `Ash.Resource.Change`
[🔗](https://github.com/ash-project/ash/blob/v3.17.0/lib/ash/resource/change/change.ex#L5)

The behaviour for an action-specific resource change.

`c:init/1` is defined automatically by `use Ash.Resource.Change`, but can be implemented if you want to validate/transform any
options passed to the module.

The main function is `c:change/3`. It takes the changeset, any options that were provided
when this change was configured on a resource, and the context, which currently only has
the actor.

# `context`

```elixir
@type context() :: Ash.Resource.Change.Context.t()
```

# `ref`

```elixir
@type ref() :: {module(), Keyword.t()} | module()
```

# `t`

```elixir
@type t() :: %Ash.Resource.Change{
  __spark_metadata__: Spark.Dsl.Entity.spark_meta(),
  always_atomic?: term(),
  change: term(),
  description: term(),
  on: term(),
  only_when_valid?: term(),
  where: term()
}
```

# `after_batch`
*optional* 

```elixir
@callback after_batch(
  changesets_and_results :: [{Ash.Changeset.t(), Ash.Resource.record()}],
  opts :: Keyword.t(),
  context :: Ash.Resource.Change.Context.t()
) ::
  :ok
  | Enumerable.t(
      {:ok, Ash.Resource.record()}
      | {:error, Ash.Error.t()}
      | Ash.Notifier.Notification.t()
    )
```

Runs on each batch result after it is dispatched to the data layer.

# `atomic`
*optional* 

```elixir
@callback atomic(
  changeset :: Ash.Changeset.t(),
  opts :: Keyword.t(),
  context :: Ash.Resource.Change.Context.t()
) ::
  {:ok, Ash.Changeset.t()}
  | {:atomic, %{optional(atom()) => Ash.Expr.t() | {:atomic, Ash.Expr.t()}}}
  | {:atomic, Ash.Changeset.t(), %{optional(atom()) => Ash.Expr.t()}}
  | {:atomic, Ash.Changeset.t(), %{optional(atom()) => Ash.Expr.t()},
     [
       {:atomic, involved_fields :: [atom()] | :*,
        condition_expr :: Ash.Expr.t(), error_expr :: Ash.Expr.t()}
     ]}
  | {:atomic, %{optional(atom()) => Ash.Expr.t()},
     [
       {:atomic, involved_fields :: [atom()] | :*,
        condition_expr :: Ash.Expr.t(), error_expr :: Ash.Expr.t()}
     ]}
  | {:atomic_set, %{optional(atom()) => Ash.Expr.t() | {:atomic, Ash.Expr.t()}}}
  | [
      atomic: %{optional(atom()) => Ash.Expr.t() | {:atomic, Ash.Expr.t()}},
      atomic_set: %{optional(atom()) => Ash.Expr.t() | {:atomic, Ash.Expr.t()}}
    ]
  | {:not_atomic, String.t()}
  | :ok
  | {:error, term()}
```

The atomic version of a change. This is called instead of `c:change/3` when running
atomically. Atomic changes are expressed as maps of attribute names to expressions
that will be evaluated in the data layer.

## Return Values

- `{:atomic, atomics}` - A map of attribute names to expressions for updating existing records.
  Used during the UPDATE phase (for updates or the ON CONFLICT clause of upserts).
  The expression can reference existing values using `atomic_ref(:field)`.

- `{:atomic_set, atomics}` - A map of attribute names to expressions for creating records.
  Used during the INSERT phase of create actions. Cannot use `atomic_ref/1` since there
  is no existing row to reference. For update actions, behaves the same as `{:atomic, ...}`.

- A list containing both `{:atomic, ...}` and `{:atomic_set, ...}` tuples when you need
  to set values for both the INSERT and UPDATE phases (useful for upserts).

- `{:ok, changeset}` - Return a modified changeset (the change was applied in-memory).

- `{:not_atomic, reason}` - Indicates the change cannot run atomically.

- `:ok` - No changes needed.

- `{:error, term}` - An error occurred.

## Examples

    # Simple atomic update (increment counter)
    def atomic(_changeset, _opts, _context) do
      {:atomic, %{counter: expr(counter + 1)}}
    end

    # Atomic set for creates (set timestamp)
    def atomic(_changeset, _opts, _context) do
      {:atomic_set, %{created_at: expr(now())}}
    end

    # Both insert and update values (for upserts)
    def atomic(_changeset, _opts, _context) do
      [
        {:atomic_set, %{created_at: expr(now())}},
        {:atomic, %{updated_at: expr(now())}}
      ]
    end

# `atomic?`

```elixir
@callback atomic?() :: boolean()
```

# `batch_callbacks?`

```elixir
@callback batch_callbacks?(
  changesets_or_query :: [Ash.Changeset.t()] | Ash.Query.t(),
  opts :: Keyword.t(),
  context :: Ash.Resource.Change.Context.t()
) :: boolean()
```

Whether or not batch callbacks should be run (if they are defined). Defaults to `true`.

# `batch_change`
*optional* 

```elixir
@callback batch_change(
  changesets :: [Ash.Changeset.t()],
  opts :: Keyword.t(),
  context :: Ash.Resource.Change.Context.t()
) :: Enumerable.t(Ash.Changeset.t())
```

Replaces `change/3` for batch actions, allowing to optimize changes for bulk actions.

You can define only `batch_change/3`, and it will be used for both single and batch actions.
It cannot, however, be used in place of the `atomic/3` callback.

# `before_batch`
*optional* 

```elixir
@callback before_batch(
  changesets :: [Ash.Changeset.t()],
  opts :: Keyword.t(),
  context :: Ash.Resource.Change.Context.t()
) :: Enumerable.t(Ash.Changeset.t() | Ash.Notifier.Notification.t())
```

Runs on each batch before it is dispatched to the data layer.

# `change`
*optional* 

```elixir
@callback change(
  changeset :: Ash.Changeset.t(),
  opts :: Keyword.t(),
  context :: Ash.Resource.Change.Context.t()
) :: Ash.Changeset.t()
```

# `has_after_batch?`

```elixir
@callback has_after_batch?() :: boolean()
```

# `has_batch_change?`

```elixir
@callback has_batch_change?() :: boolean()
```

# `has_before_batch?`

```elixir
@callback has_before_batch?() :: boolean()
```

# `has_change?`

```elixir
@callback has_change?() :: boolean()
```

# `init`

```elixir
@callback init(opts :: Keyword.t()) :: {:ok, Keyword.t()} | {:error, term()}
```

# `change`

---

*Consult [api-reference.md](api-reference.md) for complete listing*