Splode helps you deal with errors and exceptions in your application that are aggregatable and consistent. The general pattern is that you use the Splode module as a top level aggregator of error classes, and whenever you return errors, you return one of your Splode.Error structs, or a string, or a keyword list. Then, if you want to group errors together, you can use your Splode module to do so. You can also use that module to turn any arbitrary value into a splode error.

More documentation for Splode will come in the future. This was extracted from Ash Framework so that it could be standardized across multiple packages. If you use Ash, you can use Ash.Errors to get the benefits of Splode.

For now, here is an example:

defmodule MyApp.Errors do
  use Splode, error_classes: [
    invalid: MyApp.Errors.Invalid,
    unknown: MyApp.Errors.Unknown
  ],
  unknown_error: MyApp.Errors.Unknown.Unknown
end

# Error classes are splode errors with an `errors` key.
defmodule MyApp.Errors.Invalid do
  use Splode.ErrorClass, class: :invalid
end

# You will want to define an unknown error class,
# otherwise splode will use its own
defmodule MyApp.Errors.Unknown do
  use Splode.ErrorClass, class: :unknown
end

# This fallback exception will be used for unknown errors
defmodule MyApp.Errors.Unknown.Unknown do
  use Splode.Error, class: :unknown

  # your unknown message should have an `error` key
  def message(%{error: error}) do
    if is_binary(error) do
      to_string(error)
    else
      inspect(error)
    end
  end
end

# Finally, you can create your own error classes

defmodule MyApp.Errors.InvalidArgument do
  use Splode.Error, fields: [:name, :message], class: :invalid

  def message(%{name: name, message: message}) do
    "Invalid argument #{name}: #{message}"
  end
end

To use these exceptions in your application, the general pattern is to return errors in :ok | :error tuples, like so:

def do_something(argument) do
  if is_valid?(argument) do
    {:ok, do_stuff()}
  else
    {:error,
      MyApp.Errors.InvalidArgument.exception(
        name: :argument,
        message: "is invalid"
      )}
  end
end

Then, you can use to_class, and to_error tools to ensure that you have consistent error structures.

def do_multiple_things(argument) do
  results = [do(), multiple(), things()]
  {results, errors} =
    Enum.reduce(results, {[], []}, fn
      {:ok, result}, {results, errors} ->
        {[result | results], errors}
      {:error, error} ->
        # ensure each error is a splode error
        # technically, `to_class` does this for you,
        # this is just an example
        {results, [MyApp.Errors.to_error(error) | errors]}
    end)

  case {results, errors} do
    {results, []} ->
      {:ok, results}
    {_results, errors} ->
      {:error, MyApp.Errors.to_class(errors)}
  end
end

Error classes

When we combine errors into error classes, we choose the first error class for which there are any errors as the "class" of the combined error. For example, in Ash Framework, we have:

use Splode,
  error_classes: [
    forbidden: Ash.Error.Forbidden,
    invalid: Ash.Error.Invalid,
    framework: Ash.Error.Framework,
    unknown: Ash.Error.Unknown
  ],
  unknown_error: Ash.Error.Unknown.UnknownError

What this means is that if there are any Forbidden errors, then the class is Forbidden. A Forbidden error can contain any of the lower classed errors. This allows people to match on and/or rescue on "the general type of failure" that occurred. Given that you have many varied kinds of errors, you can use this to your advantage to have both detailed errors, but simple to match on errors. Here is an example:

def get(conn, %{"user_id" => user_id}) do
  user = MyApp.Accounts.get_user!()
  render_user(conn, user)
rescue
  e in Ash.Error.Forbidden ->
    render_error(conn, %{error: "You can't do this"})

  e in Ash.Error.Invalid ->
    render_error(conn, %{error: "You did something wrong"})

  e in [Ash.Error.Framework, Ash.Error.Unknown] ->
    render_error(conn, %{error: "Something went wrong"})
end

Or, alternatively, you can pattern match on them given a non-raised error class

def get(conn, %{"user_id" => user_id}) do
  case MyApp.Accounts.get_user() do
    {:ok, user} ->
      render_user(conn, user)

    {:error, %Ash.Error.Forbidden{}} ->
      render_error(conn, %{error: "You can't do this"})

    {:error, %Ash.Error.Invalid{}} ->
      render_error(conn, %{error: "You did something wrong"})

    {:error, %error{}} when error in [Ash.Error.Framework, Ash.Error.Unknown] ->
      render_error(conn, %{error: "Something went wrong"})
  end
end

Raising Exceptions

To make a ! version of a function, use .unwrap!/2 on your splode module.

def get_user!(user_id) do
  user_id
  |> get_user()
  |> MyApp.Errors.unwrap!()
end

def get_user(user_id) do
  case Repo.get(user_id) do
    nil ->
      {:error, MyApp.Error.NotFound.exception(resource: User, key: user_id)}
    user ->
      {:ok, user}
  end
end

Installation

def deps do
  [
    {:splode, "~> 0.1.0"}
  ]
end