Foundation.Error (foundation v0.1.0)

Enhanced error handling with hierarchical error codes and comprehensive error management.

Phase 1 Implementation:

  • Hierarchical error code system (C000-C999, S000-S999, etc.)
  • Enhanced error context and recovery strategies
  • Standardized error propagation patterns
  • Error metrics and analysis capabilities

All errors must have a code, error_type, message, and severity. Other fields provide additional context and are optional.

See @type t for the complete type specification.

Examples

iex> error = Foundation.Error.new(:config_not_found, "Config missing")
iex> error.error_type
:config_not_found

iex> error = Foundation.Error.new(:network_error, nil, context: %{url: "http://example.com"})
iex> is_map(error.context)
true

Summary

Types

error_category()

High-level error category

error_code()

Specific error type identifier

error_context()

Additional context information for the error

error_severity()

Error severity level

error_subcategory()

Specific error subcategory within a category

retry_strategy()

Strategy for retrying failed operations

stacktrace_info()

Stack trace information as a list of maps

t()

Functions

collect_error_metrics(error)
error_result(error_type, message \\ nil, opts \\ [])

Create an error result tuple.

is_retryable?(error)
new(error_type, message \\ nil, opts \\ [])

Create a new error with the given error type and optional message.

retry_delay(error, attempt)
should_escalate?(error)
to_string(error)
wrap_error(result, error_type, message \\ nil, opts \\ [])

Wrap an existing result with additional error context.

Types

error_category()

@type error_category() :: :config | :system | :data | :external

High-level error category

error_code()

@type error_code() :: atom()

Specific error type identifier

error_context()

@type error_context() :: map()

Additional context information for the error

error_severity()

@type error_severity() :: :low | :medium | :high | :critical

Error severity level

error_subcategory()

@type error_subcategory() :: :structure | :validation | :access | :runtime

Specific error subcategory within a category

retry_strategy()

@type retry_strategy() :: :no_retry | :immediate | :fixed_delay | :exponential_backoff

Strategy for retrying failed operations

stacktrace_info()

@type stacktrace_info() :: [map()]

Stack trace information as a list of maps

t()

@type t() :: %Foundation.Error{
  category: error_category() | nil,
  code: pos_integer(),
  context: error_context() | nil,
  correlation_id: String.t() | nil,
  error_type: error_code(),
  message: String.t(),
  recovery_actions: [String.t()] | nil,
  retry_strategy: retry_strategy() | nil,
  severity: error_severity(),
  stacktrace: stacktrace_info() | nil,
  subcategory: error_subcategory() | nil,
  timestamp: DateTime.t() | nil
}

Functions

collect_error_metrics(error)

error_result(error_type, message \\ nil, opts \\ [])

@spec error_result(error_code(), String.t() | nil, keyword()) :: {:error, t()}

Create an error result tuple.

Parameters

  • error_type: The specific error type atom
  • message: Custom error message (optional)
  • opts: Additional options

Examples

iex> Foundation.Error.error_result(:data_not_found)
{:error, %Foundation.Error{error_type: :data_not_found, ...}}

is_retryable?(error)

new(error_type, message \\ nil, opts \\ [])

@spec new(error_code(), String.t() | nil, keyword()) :: t()

Create a new error with the given error type and optional message.

Parameters

  • error_type: The specific error type atom
  • message: Custom error message (optional, will use default if nil)
  • opts: Additional options including context, correlation_id, stacktrace

Examples

iex> error = Foundation.Error.new(:config_not_found)
iex> error.error_type
:config_not_found

iex> error = Foundation.Error.new(:timeout, "Request timed out", context: %{timeout: 5000})
iex> error.message
"Request timed out"

Raises

retry_delay(error, attempt)

should_escalate?(error)

to_string(error)

wrap_error(result, error_type, message \\ nil, opts \\ [])

@spec wrap_error(term(), error_code(), String.t() | nil, keyword()) :: term()

Wrap an existing result with additional error context.

Parameters

  • result: The result to potentially wrap
  • error_type: The wrapper error type
  • message: Custom error message (optional)
  • opts: Additional options

Examples

iex> result = {:error, :timeout}
iex> Foundation.Error.wrap_error(result, :external_service_error)
{:error, %Foundation.Error{...}}