Skip to content
<awesome-gh-repos>
vic

expede/exceptional

Helpers for Elixir exceptions
Source code at GitHub https://hex.pm/packages/exceptional
expede/exceptional.json
{
  "createdAt": "2016-08-28T10:38:08Z",
  "defaultBranch": "master",
  "description": "Helpers for Elixir exceptions",
  "fullName": "expede/exceptional",
  "homepage": "https://hex.pm/packages/exceptional",
  "language": "Elixir",
  "name": "exceptional",
  "pushedAt": "2023-07-28T11:56:15Z",
  "stargazersCount": 294,
  "topics": [
    "convenient",
    "elixir",
    "elixir-exceptions",
    "exception-flow",
    "exception-handler",
    "exceptions",
    "macros"
  ],
  "updatedAt": "2025-10-26T13:43:24Z",
  "url": "https://github.com/expede/exceptional"
}

Exceptional: Helpers for Elixir exceptions

Section titled “Exceptional: Helpers for Elixir exceptions”

Build Status Inline docs hex.pm version API Docs license

Table of Contents

Section titled “Table of Contents”

Installation

Section titled “Installation”

Add exceptional to your list of dependencies in mix.exs:

def deps do
  [{:exceptional, "~> 2.1"}]
end

About

Section titled “About”

Exceptional is an Elixir library providing helpers for working with exceptions. It aims to make working with plain old (unwrapped) Elixir values more convenient, and to give full control back to calling functions.

See the Medium article for more

Prior Art

Section titled “Prior Art”

Tagged Status

Section titled “Tagged Status”

The tagged status pattern ({:ok, _}, {:error, _}, etc)has been the bread and butter of Erlang since the beginning. While this makes it very easy to track the meaning of an expression, two things can happen:

  1. The tag becomes out of sync
  • ex. {:ok, "and yet not ok"}
  1. Pattern matching becomes challenging when different lengths exist
  • ex. {:error, "oopsie"}, {:error, "oopsie", %{original: :data, for: "handling"}}

Optimistic Flow

Section titled “Optimistic Flow”

The other alternative is to be optimistic returns, generally seen with bang patterns. Ex. doc = File.read! path instead of {:ok, doc} = File.read path". This is more convenient, but will raise, robbing the caller of control without try/catch.

Error Monad

Section titled “Error Monad”

Currently a very undersused pattern in the Erlang/Elixir ecosystem, this is probably “the right way” to do general error handling (or at last the most theoretically pure one). Essentially, wrap your computation in an ADT struct, paired with a binding function (super-powered |>), that escapes the pipe flow if it encounters an Exception.

The downside is of course that people are generally afraid of introducing monads into their Elixir code, as understanding it requires some theoretical understanding.

Exceptional

Section titled “Exceptional”

Exceptional takes a hybrid approach. The aim is to behave similar to an error monad, but in a more Elixir-y way. This is less powerful than the monad solution, but simpler to understand fully, and cleaner than optimistic flow, and arguably more convenient than the classic tagged status.

This is a classic inversion of control, and allows for very flexible patterns. For example, using >>> (ie: raise if exception, otherwise continue) sidesteps the need for separate bang functions.

Just like the classic FP wisdom: if it doubt, pass it back to the caller to handle.

Examples

Section titled “Examples”

Make Safe

Section titled “Make Safe”

A simple way to declaw a function that normally raises. (Does not change the behaviour of functions that don’t raise).

toothless_fetch = safe(&Enum.fetch!/2)
[1,2,3] |> toothless_fetch.(1)
#=> 2


toothless = safe(&Enum.fetch!/2)
[1,2,3] |> toothless.(999)
#=> %Enum.OutOfBoundsError{message: "out of bounds error"}


safe(&Enum.fetch!/2).([1,2,3], 999)
#=> %Enum.OutOfBoundsError{message: "out of bounds error"}

Escape Hatch

Section titled “Escape Hatch”
[1,2,3] ~> Enum.sum()
#=> 6


Enum.OutOfBoundsError.exception("exception") ~> Enum.sum
#=> %Enum.OutOfBoundsError{message: "exception"}


[1,2,3]
|> hypothetical_returns_exception()
~> Enum.map(fn x -> x + 1 end)
~> Enum.sum()
#=> %Enum.OutOfBoundsError{message: "exception"}


0..10
|> Enum.take(3)
~> Enum.map(fn x -> x + 1 end)
~> Enum.sum()
#=> 6

Normalize Errors

Section titled “Normalize Errors”

Elixir and Erlang interoperate, but represent errors differently. normalize normalizes values into exceptions or plain values (no {:error, _} tuples). This can be seen as the opposite of the functions that convert back to tagged status. Some error types may not be detected; but you may pass a custom converter (see examples below).

normalize(42)
#=> 42


normalize(%Enum.OutOfBoundsError{message: "out of bounds error"})
#=> %Enum.OutOfBoundsError{message: "out of bounds error"}


normalize(:error)
#=> %ErlangError{original: nil}


normalize({:error, "boom"})
#=> %ErlangError{original: "boom"}


normalize({:error, {1, 2, 3}})
#=> %ErlangError{original: {1, 2, 3}}


normalize({:error, "boom with stacktrace", ["trace"]})
#=> %ErlangError{original: "boom with stacktrace"}


normalize({:good, "tuple", ["value"]})
#=> {:good, "tuple", ["value"]}


{:oh_no, {"something bad happened", %{bad: :thing}}}
|> normalize(fn
  {:oh_no, {message, _}} -> %File.Error{reason: message} # This case
  {:bang, message}       -> %File.CopyError{reason: message}
  otherwise              -> otherwise
end)
#=> %File.Error{message: msg}


{:oh_yes, {1, 2, 3}}
|> normalize(fn
  {:oh_no, {message, _}} -> %File.Error{reason: message}
  {:bang, message}       -> %File.CopyError{reason: message}
  otherwise              -> otherwise # This case
end)
#=> {:oh_yes, {1, 2, 3}}

Back to Tagged Status

Section titled “Back to Tagged Status”
[1,2,3]
|> hypothetical_returns_exception()
~> Enum.map(fn x -> x + 1 end)
~> Enum.sum()
#=>  {:error, "exception"}


0..10
|> Enum.take(3)
~> Enum.map(fn x -> x + 1 end)
~> Enum.sum()
|> to_tagged_status()
#=> {:ok, 6}




0..10
|> hypothetical_returns_exception()
~> Enum.map(fn x -> x + 1 end)
~> Enum.sum()
|> ok()
#=>  {:error, "exception"}




maybe_sum =
  0..10
  |> hypothetical_returns_exception()
  ~> Enum.map(fn x -> x + 1 end)
  ~> Enum.sum()


~~~maybe_sum
#=>  {:error, "exception"}

Finally Raise

Section titled “Finally Raise”

Note that this does away with the need for separate foo and foo! functions, thanks to the inversion of control.

[1,2,3] >>> Enum.sum()
#=> 6


%ArgumentError{message: "raise me"} >>> Enum.sum()
#=> ** (ArgumentError) raise me


ensure!([1, 2, 3])
#=> [1, 2, 3]


ensure!(%ArgumentError{message: "raise me"})
#=> ** (ArgumentError) raise me


defmodule Foo do
  use Exceptional


  def! foo(a), do: a
end


Foo.foo([1, 2, 3])
#=> [1, 2, 3]


Foo.foo(%ArgumentError{message: "raise me"})
#=> %ArgumentError{message: "raise me"}


Foo.foo!([1, 2, 3])
#=> [1, 2, 3]


Foo.foo!(%ArgumentError{message: "raise me"})
#=> ** (ArgumentError) raise me

Manually Branch

Section titled “Manually Branch”
Exceptional.Control.branch 1,
  value_do: fn v -> v + 1 end.(),
  exception_do: fn %{message: msg} -> msg end.()
#=> 2


ArgumentError.exception("error message"),
|> Exceptional.Control.branch(value_do: fn v -> v end.(), exception_do: fn %{message: msg} -> msg end.())
#=> "error message"


if_exception 1, do: fn %{message: msg} -> msg end.(), else: fn v -> v + 1 end.(),
#=> 2


ArgumentError.exception("error message")
|> if_exception do
  fn %{message: msg} -> msg end.())
else
  fn v -> v end.()
end
#=> "error message"
Section titled “Related Packages”