Jido.Action.Error (Jido Action v3.0.0-beta.12)

View Source

Defines and normalizes errors produced by Jido Actions.

The public boundary is intentionally small. Concrete Action errors keep their canonical type, details, and retry policy. Any unsupported value becomes a non-retryable execution error with no structured details.

Errors are non-retryable by default. Set details.retry to true only when another attempt is safe. Jido does not perform an automatic retry.

Summary

Functions

Creates an Action configuration error.

Creates an Action execution error.

Creates an internal Action error.

Returns whether a concrete Action error is retryable.

Creates an Action timeout error.

Converts an Action error into its public map.

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

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

Creates an invalid-input error.

Types

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() ::
  Jido.Action.Error.Internal
  | Jido.Action.Error.Config
  | Jido.Action.Error.Execution
  | Jido.Action.Error.Invalid
  | Splode.Error.Unknown

details_input()

@type details_input() :: map() | keyword()

error_class()

@type error_class() :: :internal | :config | :execution | :invalid | :unknown

error_map()

@type error_map() :: %{
  type: atom(),
  message: String.t(),
  details: map(),
  retryable?: boolean()
}

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

config_error(message, details \\ %{})

Creates an Action configuration error.

execution_error(message, details \\ %{})

Creates an Action execution error.

internal_error(message, details \\ %{})

@spec internal_error(String.t(), details_input()) ::
  Jido.Action.Error.InternalError.t()

Creates an internal Action error.

retryable?(arg1)

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

Returns whether a concrete Action error is retryable.

A Boolean details.retry value controls the result for execution and timeout errors. All errors are non-retryable by default. Unsupported values are never retryable.

splode_error?(arg1, splode)

timeout_error(message, details \\ %{})

Creates an Action timeout error.

to_map(error)

@spec to_map(term()) :: error_map()

Converts an Action error into its public map.

Unsupported values become conservative execution errors. They cannot select a canonical type, add structured details, or request a retry.

Detail values stay unchanged. A caller that sends the map through JSON or another transport must convert its own detail values for that transport. The map omits the exception's top-level stacktrace.

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.Jido.Action.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

validation_error(message, details \\ %{})

Creates an invalid-input error.