Jido.Action.Error (Jido Action v2.0.0-rc.0)

View Source

Centralized error handling for Jido Actions using Splode.

This module provides a consistent way to create, aggregate, and handle errors within the Jido Action system. It uses the Splode library to enable error composition and classification.

Error Classes

Errors are organized into the following classes, in order of precedence:

  • :invalid - Input validation, bad requests, and invalid configurations
  • :execution - Runtime execution errors and action failures
  • :config - System configuration and setup errors
  • :internal - Unexpected internal errors and system failures

When multiple errors are aggregated, the class of the highest precedence error determines the overall error class.

Usage

Use this module to create and handle errors consistently:

# Create a specific error
{:error, error} = Jido.Action.Error.validation_error("must be a positive integer", field: :user_id)

# Create timeout error
{:error, timeout} = Jido.Action.Error.timeout_error("Action timed out after 30s", timeout: 30000)

# Convert any value to a proper error
{:error, normalized} = Jido.Action.Error.to_error("Something went wrong")

Summary

Types

class()
class_module()
error_class()
t()

Functions

config_error(message, details \\ %{})

Creates a configuration error.

execution_error(message, details \\ %{})

Creates an execution error for runtime failures.

format_nimble_config_error(error, module_type, module)

Formats a NimbleOptions configuration error for display. Used when configuration validation fails during compilation.

format_nimble_validation_error(error, module_type, module)

Formats a NimbleOptions validation error for parameter validation. Used when validating runtime parameters.

internal_error(message, details \\ %{})

Creates an internal server error.

splode_error?(arg1, splode)
timeout_error(message, details \\ %{})

Creates a timeout error.

unwrap!(result, opts \\ nil)

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

validation_error(message, details \\ %{})

Creates a validation error for invalid input parameters.

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

error_class()

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

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 \\ %{})

@spec config_error(String.t(), map()) :: Jido.Action.Error.ConfigurationError.t()

Creates a configuration error.

execution_error(message, details \\ %{})

@spec execution_error(String.t(), map()) ::
  Jido.Action.Error.ExecutionFailureError.t()

Creates an execution error for runtime failures.

format_nimble_config_error(error, module_type, module)

@spec format_nimble_config_error(
  NimbleOptions.ValidationError.t() | any(),
  String.t(),
  module()
) :: String.t()

Formats a NimbleOptions configuration error for display. Used when configuration validation fails during compilation.

format_nimble_validation_error(error, module_type, module)

@spec format_nimble_validation_error(
  NimbleOptions.ValidationError.t() | any(),
  String.t(),
  module()
) :: String.t()

Formats a NimbleOptions validation error for parameter validation. Used when validating runtime parameters.

internal_error(message, details \\ %{})

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

Creates an internal server error.

splode_error?(arg1, splode)

timeout_error(message, details \\ %{})

@spec timeout_error(String.t(), map()) :: Jido.Action.Error.TimeoutError.t()

Creates a timeout error.

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 \\ %{})

@spec validation_error(String.t(), map()) :: Jido.Action.Error.InvalidInputError.t()

Creates a validation error for invalid input parameters.