Support for creating custom error types, which can either be returned as error values or raised as exceptions.

Errata errors can be defined by creating an Elixir module that uses the Errata.Error module. Error types defined in this way are Elixir Exception structs with the following keys:

• message - human readable string describing the nature of the error
• reason - an atom describing the reason for the error, which can be used for pattern matching or classifying the error
• context - a map containing arbitrary contextual information or metadata about the error

Note the distinction between two ways of rendering an error as a string. Exception.message/1 (and the String.Chars implementation) return a developer-oriented message that combines message and reason (for example, "the requested order does not exist: :not_found") — useful in logs and raised-exception output. Errata.display_message/1 returns just the human-readable message, intended for rendering to end users.

Because these error types are defined with defexception/1, they can be raised as exceptions with raise/2. However, because they implement the Errata.Error behaviour, it is also possible to create instances of these error structs using the generated implementations of Errata.Error.new/1 or Errata.Error.create/1 and use them as return values from functions, either directly or wrapped in an error tuple such as {:error, my_error}.

Error types defined with Errata.Error are of kind :general by default. Since most errors are either domain errors or infrastructure errors, prefer Errata.DomainError or Errata.InfrastructureError (which share all of the functionality described here) when defining custom error types, and use Errata.Error directly only for general errors that fit neither category, such as errors originating in library code.

Usage

To define a new custom error type, use/2 the Errata.Error module in your own error module:

defmodule MyApp.UnexpectedError do
  use Errata.Error,
    default_message: "an unexpected error occurred"
end

use Errata.Error

When you use Errata.Error, the Errata.Error module will define an exception struct with defexception/1 and will generate an implementation of the Errata.Error behaviour.

The following options may be provided to use Errata.Error:

• :default_reason - the default value to use for the :reason field if it is not provided
• :default_message - the default value to use for the :message field if it is not provided
• :reasons - an optional list of atoms enumerating the valid reasons for this error type. When given, creating an error (via new/1, create/1, wrap/2, or raise/2) with a :reason outside this set raises an ArgumentError. A nil (unspecified) reason is always allowed, and a :default_reason, if also given, must be one of the declared :reasons. Declaring reasons also generates a reason/0 type enumerating them, so the valid reasons are visible in the generated documentation.
• :http_status - the HTTP status code to associate with this error type, returned by the generated http_status/1 function (and Errata.http_status/1). When omitted, the status defaults off the error's kind (:domain → 422, :infrastructure → 503, :general → 500). The generated http_status/1 is overridable, so it can instead be defined to compute a status from the error's :reason or :context.
• :kind - the "kind" of Errata error to create, one of :domain, :infrastructure, or :general (which is the default)

The :kind option

Although it is possible to define domain error types or infrastructure error types by using :domain or :infrastructure as the :kind option, it is preferred to instead define these types of errors with use Errata.DomainError or use Errata.InfrastructureError. This approach is more explicit and allows for easier identification of domain errors and infrastructure errors within an application.

To create instances of the error--to use as an error return value from a function, say--you can use either new/1 or create/1, passing params with extra information as desired. Note that if you use create/1, you must first require the error module, since this callback is implemented as a macro. For example:

defmodule MyApp.SomeModule do
  require MyApp.UnexpectedError, as: UnexpectedError

  def some_function(arg) do
    {:error, UnexpectedError.create(reason: :unexpected, context: %{arg: arg})}
  end
end

To raise errors as exceptions, simply use raise/2 passing extra params as the second argument if desired:

defmodule MyApp.SomeModule do
  require MyApp.UnexpectedError, as: UnexpectedError

  def some_function!(arg) do
    raise UnexpectedError, reason: :unexpected, context: %{arg: arg}
  end
end