ExcError

A common way to represent errors in elixir is to return tuples of format {:error, term}. However term is often a simple atom (or another tuple with simple atom). I believe that a better way to represent errors is to use elixir Structs.

They bring some advantages:

• Structure of the error is enforced by compiler
• It is easier to deal with additional error context (Structs have fields)
• Structs can implement protocols
• Specifically: Structs can implement String.Chars protocol - a nice way to get a friendly formatted error message
• Structs can implement behaviours
• Specifically: Structs can implement Exception behaviour. Client code can just raise error Struct as exception if it deems it sensible

This library is a thin wrapper to reduce boilerplate for defining Error structs that implement String.Chars protocol and Exception behaviour.

Feel free to use this “Structs as Errors” pattern but please do not use this Library. You do not need any libs to use some architectural pattern. I have made this library to get rid of annoying duplication in internal company projects. I recommend you to tinker your own version tailored to your specific needs.

However some usage examples:

# Basic Usage

module SomeModule do
  require ExcError

  ExcError.define(SomeError)

  def some_method
    {:error, %SomeError{}}
  end
end

{:error, %SomeError{} = my_error} = SomeModule.some_method()

# You can format error as string
to_string(my_error)

some_text = "error #{my_error}"

# You can raise error as exception
raise my_error

# default type for struct is declared for you
@spec some_function() :: :ok | {:error, SomeError.t()}

# You can define some custom fields for your struct (just like in defstruct)

ExcError.define SomeError, :some_field, other_field: "default_value"

def my_method
  {:error, %SomeError{some_field: "some-field-value"}}
end

# You can define methods for your struct

ExcError.define SomeError do
  def some_method do
    :ok
  end
end

:ok = SomeError.some_method()

# You can define custom implementation for `String.Chars` protocol

ExcError.define HttpError, [:method, :url, :code] do
  @impl true
  def message(exc), do: "HTTP error method:#{exc.method} url:#{exc.url} code:#{exc.code}"
end

# If no custom fields are provided for your struct, ExcError defines :message field by default:

ExcError.define SomeError

"some message" = to_string(%SomeError{message: "some message"})

# You can define custom type for your struct

ExcError.define SomeError, [:custom_field] do
    @type t :: %__MODULE__{
            custom_field: atom
          }
end

# All defined structs have :cause field by default
# Use it to wrap other errors

ExcError.define SomeError

error_struct = SomeError.wrap({:error, :other_error})
:other_error = error_struct.cause

error_struct = SomeError.wrap(%SomeStruct{})
%SomeStruct{} = error_struct.cause

ExcError.define SomeOtherError, [:some_field]

error_struct = SomeOtherError.wrap({:error, :other_error}, some_field: "some-value")
:other_error = error_struct.cause
"some-value" = error_struct.some_field