Search documentation of ash

# Ash.Error (ash v3.4.71)

View Source

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.

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.

# 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