MscmpSystError behaviour (mscmp_syst_error v0.1.0)

MscmpSystError establishes a common framework for defining and handling errors.

MscmpSystError provides a structured way to define and handle errors within an application. It defines a set of fields that errors should include, such as kind, message, context, and cause. This standardization enables consistent error handling and reporting across different parts of an application.

To create a new Error type implemention, you can use the use MscmpSystError macro in your module.

defmodule Mserror.MyError do
  use MscmpSystError,
    kinds: [my_error: "`:my_error` Error Kind documentation"],
    component: ExampleComponent
end

Options

The use MscmpSystError macro requires that the following options are provided:

  • :kinds - A keyword list of error kinds, where the key is the atom representing the error kind, and the value is a string providing a documentation string for the error kind.

  • :component - This is a reference to the Component where the error type is defined. As errors may be propogated from lower level dependencies to higher level components, this value helps identify the origin of any given error.

Failing to provide these options will result in a compile time error.

use MscmpSystError

When use MscmpSystError is called with the required options, it:

  1. Implements the MscmpSystError behaviour.

  2. Defines a kinds type based on the provided :kinds option.

  3. Creates a struct with fields for kind, message, mserror, component, context, and cause.

  4. Implements defexception with the struct fields.

  5. Defines an exception/1 function that delegates to new/3.

  6. Implements a new/3 function that creates a new error struct with the given kind, message, and options.

Summary

Error Parsing

get_root_cause(error)

Returns the root cause of an error object implementing the MscmpSystError behavior.

Callbacks

new(kind, message, opts)

Defines the callback for creating a new error of the implementing module.

Error Parsing

get_root_cause(error)

@spec get_root_cause(any()) :: any()

Returns the root cause of an error object implementing the MscmpSystError behavior.

The MscmpSystError exception handling framework allows for nested exceptions to be reported stack trace style from lower levels of the application where an exception was caused into higher levels of the application which enter a failure state due to the lower level root cause.

This function will traverse the nesting and return the bottom most Error Struct. If some other object, such as a standard error tuple is passed to the function, the function will simply return that value.

Examples

iex> my_err = %ExampleError{
...>   kind: :example_error,
...>   message: "Outer error message",
...>   cause: %ExampleError{
...>     kind: :example_error,
...>     message: "Intermediate error message",
...>     cause: %ExampleError{
...>       kind: :example_error,
...>       message: "Root error message",
...>       cause: {:error, "Example Error"},
...>     },
...>   },
...> }
iex> MscmpSystError.get_root_cause(my_err)
%ExampleError{
  kind: :example_error,
  message: "Root error message",
  cause: {:error, "Example Error"}
}

iex> MscmpSystError.get_root_cause({:error, "Example Error"})
{:error, "Example Error"}

Callbacks

new(kind, message, opts)

@callback new(kind :: atom(), message :: String.t(), opts :: keyword()) :: Exception.t()

Defines the callback for creating a new error of the implementing module.

This function should be implemented by all modules using MscmpSystError. It creates a new error struct with the given kind, message, and options.

Parameters

  • kind - The kind of error, which should be one of the kinds defined in the implementing module.

  • message - A string describing the error.

  • opts - A keyword list of additional options.

Options

  • :context - A map containing additional context information for the error.

  • :cause - The cause of the error, which can be an exception, an error tuple, or any other term.

  • :parse_error - An error result conforming with MscmpSystError.Types.parsable_error/0 to be parsed overriding certain attributes of the exception struct. When provided the message parameter is treated as a default message which can be overridden by a message supplied by the error result provided to this option. The cause attribute of the exception struct will be set to a value derived from this option's value, ignoring the :cause option if provided; typically you would not provide both :parse_error and :cause in the same call to new/3.

Returns

Returns a struct of the implementing module with the error details.