defmodule Mv.Helpers do
  @moduledoc """
  Shared helper functions used across the Mv application.

  Provides utilities that are not specific to a single domain or layer.
  """

  require Ash.Query

  @doc """
  Converts an actor to Ash options list for authorization.
  Returns empty list if actor is nil.

  This helper ensures consistent actor handling across all Ash operations
  in the application, whether called from LiveViews, changes, validations,
  or other contexts.

  ## Examples

      opts = ash_actor_opts(actor)
      Ash.read(query, opts)

      opts = ash_actor_opts(nil)
      # => []
  """
  @spec ash_actor_opts(Mv.Accounts.User.t() | nil) :: keyword()
  def ash_actor_opts(nil), do: []
  def ash_actor_opts(actor) when not is_nil(actor), do: [actor: actor]

  @doc """
  Returns the query unchanged if `exclude_id` is nil; otherwise adds a filter `id != ^exclude_id`.

  Used in uniqueness validations that must exclude the current record (e.g. name uniqueness
  on update, duplicate association checks). Call with the record's primary key to exclude it
  from the result set.

  ## Examples

      query
      |> Ash.Query.filter(name == ^name)
      |> Mv.Helpers.query_exclude_id(current_id)

  """
  @spec query_exclude_id(Ash.Query.t(), String.t() | nil) :: Ash.Query.t()
  def query_exclude_id(query, nil), do: query
  def query_exclude_id(query, id), do: Ash.Query.filter(query, id != ^id)
end
