Ash.Error (ash v3.24.5)

Tools and utilities used by Ash to manage and conform errors

Summary

Types

ash_error()

ash_error_subject()

class()

class_module()

error_class()

error_input()

error_keyword()

error_keyword_option()

path()

path_input()

t()

Functions

ash_error?(value)

Returns whether or not a term is an Ash.Error type.

error_descriptions(errors)

Converts errors into a single String.t.

set_path(errors, path)

This function prepends the provided path to any existing path on the errors.

splode_error?(arg1, splode)

to_ash_error(value, stacktrace \\ nil, opts \\ [])

Converts a value to an Ash exception.

to_error_class(value, opts \\ [])

Converts a value to an Ash.Error type.

traverse_errors(error_or_errors, fun)

Traverses errors, calling fun for each leaf error, and returns a nested map of results grouped by each error's path.

unwrap!(result, opts \\ nil)

Raises an error if the result is an error, otherwise returns the result

Types

ash_error()

@type ash_error() :: Exception.t()

ash_error_subject()

@type ash_error_subject() :: Ash.Changeset.t() | Ash.Query.t() | Ash.ActionInput.t()

class()

@type class() :: %{
  :__struct__ => class_module(),
  :__exception__ => true,
  :errors => [t()],
  :class => error_class(),
  :bread_crumbs => [String.t()],
  :vars => Keyword.t(),
  :stacktrace => Splode.Stacktrace.t() | nil,
  :context => map(),
  optional(atom()) => any()
}

class_module()

@type class_module() ::
  Ash.Error.Unknown
  | Ash.Error.Framework
  | Ash.Error.Invalid
  | Ash.Error.Forbidden

error_class()

@type error_class() :: :unknown | :framework | :invalid | :forbidden

error_input()

@type error_input() ::
  ash_error()
  | error_keyword()
  | String.t()
  | ash_error_subject()
  | Exception.t()
  | any()

error_keyword()

@type error_keyword() :: [error_keyword_option()]

error_keyword_option()

@type error_keyword_option() ::
  {:field, atom()}
  | {:fields, [atom()]}
  | {:value, term()}
  | {:message, String.t()}
  | {:path, [atom() | String.t()]}

path()

@type path() :: [String.t() | atom() | integer()]

path_input()

@type path_input() ::
  [String.t() | atom() | integer()] | String.t() | atom() | integer()

t()

@type t() :: %{
  :__struct__ => module(),
  :__exception__ => true,
  :class => error_class(),
  :bread_crumbs => [String.t()],
  :vars => Keyword.t(),
  :stacktrace => Splode.Stacktrace.t() | nil,
  :context => map(),
  optional(atom()) => any()
}

Functions

ash_error?(value)

@spec ash_error?(term()) :: boolean()

Returns whether or not a term is an Ash.Error type.

error_descriptions(errors)

@spec error_descriptions(term() | [term()]) :: String.t()

Converts errors into a single String.t.

set_path(errors, path)

@spec set_path(ash_error() | [ash_error()], path_input()) ::
  ash_error() | [ash_error()]

@spec set_path(ash_error_subject(), path_input()) :: ash_error_subject()

This function prepends the provided path to any existing path on the errors.

splode_error?(arg1, splode)

to_ash_error(value, stacktrace \\ nil, opts \\ [])

@spec to_ash_error(
  error_input() | [error_input()],
  Exception.stacktrace() | nil,
  Keyword.t()
) :: ash_error() | [ash_error()]

Converts a value to an Ash exception.

The supported inputs to this function can be provided to various places, like Ash.Query.add_error/2, Ash.Changeset.add_error/2 and Ash.ActionInput.add_error/2.

Additionally, any place that you can return an error you can return instead a valid error input.

See the error handling guide for more.

to_error_class(value, opts \\ [])

@spec to_error_class(
  ash_error_subject() | term() | [ash_error_subject()] | [term()],
  Keyword.t()
) :: t()

Converts a value to an Ash.Error type.

traverse_errors(error_or_errors, fun)

Traverses errors, calling fun for each leaf error, and returns a nested map of results grouped by each error's path.

See Splode.traverse_errors/2 for full documentation.

Example

iex> Elixir.Ash.Error.traverse_errors(error, fn error ->
...>   Exception.message(error)
...> end)
%{name: ["name is required"]}

unwrap!(result, opts \\ nil)

Raises an error if the result is an error, otherwise returns the result

Alternatively, you can use the defsplode macro, which does this automatically.

Options

:error_opts - Options to pass to to_error/2 when converting the returned error
:unknown_error_opts - Options to pass to the unknown error if the function returns only :error. not necessary if your function always returns {:error, error}.

Examples

def function(arg) do

case do_something(arg) do
  :success -> :ok
  {:success, result} -> {:ok, result}
  {:error, error} -> {:error, error}
end

end

def function!(arg) do

YourErrors.unwrap!(function(arg))

end