Trogon.Result (Trogon.Result v1.0.1)

When the value contained in an err/0 result then applies a function or returns the mapped value, wrapping the returning value in a err/0, propagating the ok/0 result as it is.

map_ok(error, on_ok)

When the value contained in an ok/0 result then applies a function or returns the mapped value, wrapping the returning value in a ok/0, propagating the err/0 result as it is.

map_ok_or(arg, on_ok, on_error)

Applies a on_ok function to the contained value if ok/0 otherwise applies a on_err function or return the on_err value if err/0.

ok(value)

Wraps a value into an ok/1 result.

ok?(arg)

Returns true if the argument is a ok/0.

ok_and?(arg, func)

Returns true if the result is ok/0 and the value inside of it matches a predicate.

reject_nil(response, on_nil)

When nil is passed then calls the on_nil function and wrap the result into a err/0. When t/0 is passed then returns it as it is. Otherwise, wraps the value into a ok/0.

tap_err(result, func)

Tap into err/0 results.

tap_ok(result, func)

Tap into ok/0 results.

unwrap(arg)

Returns the contained ok/0 value or t:error/0 value from a t/0.

unwrap_err!(arg)

Unwrap an err/0 result, or raise an exception.

unwrap_ok(arg, on_error)

Returns the contained ok/0 value or a provided default.

unwrap_ok!(arg)

Unwrap an ok/0 result, or raise an exception.

when_err(resp, on_err)

Applies a function or returns the value if the result is err/0, otherwise returns the ok/0 value.

when_ok(error, on_ok)

Applies a function or returns the value when a ok/0 is given, or propagates the error.

Types

err()

@type err() :: err(any())

An Error result with any reason type.

err(reason)

@type err(reason) :: {:error, reason}

An Error result with a specific reason type.

lazy(a)

@type lazy(a) :: (-> a)

A lazy function that produces a value when called with no arguments.

mapper(a, b)

@type mapper(a, b) :: (a -> b)

A mapper function that transforms a value from type a to type b.

ok()

@type ok() :: ok(any())

An Ok result with any value type.

ok(value)

@type ok(value) :: {:ok, value}

An Ok result with a specific value type.

predicate(a)

@type predicate(a) :: (a -> boolean())

A predicate function that takes a value and returns a boolean.

t()

@type t() :: t(any(), any())

A Result Tuple with any value types.

t(ok_value, err_reason)

@type t(ok_value, err_reason) :: ok(ok_value) | err(err_reason)

A Result Tuple with specific ok and error types.

Examples

@type fetch_user_error :: :not_found | :db_error
@spec fetch_user(integer()) :: Trogon.Result.t(User.t(), fetch_user_error())
def fetch_user(id), do: ...

tap_func(a)

@type tap_func(a) :: (a -> any())

A side-effect function used for tapping into values without transforming them.

Functions

and_err(first_result, second_result)

@spec and_err(first_result :: t(a, any()), second_result :: t(a, e)) :: t(a, e)
when a: any(), e: any()

Do an and with a err/0.

When passing any ok/0 result, it returns the first ok/0 value. Otherwise, when passing two err/0 results, then returns the second err/0.

iex> 21
...> |> Trogon.Result.ok()
...> |> Trogon.Result.and_err(Trogon.Result.ok(42))
{:ok, 21}

iex> 42
...> |> Trogon.Result.ok()
...> |> Trogon.Result.and_err(Trogon.Result.err("something went wrong"))
{:ok, 42}

iex> "something went wrong"
...> |> Trogon.Result.err()
...> |> Trogon.Result.and_err(Trogon.Result.ok(42))
{:ok, 42}

iex> "something went wrong"
...> |> Trogon.Result.err()
...> |> Trogon.Result.and_err(Trogon.Result.err("late error"))
{:error, "late error"}

and_ok(first_result, second_result)

@spec and_ok(first_result :: t(any(), e), second_result :: t(b, e)) :: t(b, e)
when b: any(), e: any()

Do an and with a ok/0.

When passing two ok/0 result, it returns the second ok/0 value. When a ok/0 and a err/0 result, then returns the err/0. Otherwise, when passing two err/0 result, it returns the earliest err/0.

iex> 21
...> |> Trogon.Result.ok()
...> |> Trogon.Result.and_ok(Trogon.Result.ok(42))
{:ok, 42}

iex> 21
...> |> Trogon.Result.ok()
...> |> Trogon.Result.and_ok(Trogon.Result.err("something went wrong"))
{:error, "something went wrong"}

iex> "something went wrong"
...> |> Trogon.Result.err()
...> |> Trogon.Result.and_ok(Trogon.Result.ok(42))
{:error, "something went wrong"}

iex> "something went wrong"
...> |> Trogon.Result.err()
...> |> Trogon.Result.and_ok(Trogon.Result.err("late error"))
{:error, "something went wrong"}

collect(result_list)

@spec collect(Enumerable.t(t(a, e))) :: t([a], e) when a: any(), e: any()

Iterate over t/0 list unwrapping the ok/0 values. It fails at the first err/0.

iex> Trogon.Result.collect([
...>   Trogon.Result.ok(21),
...>   Trogon.Result.ok(42),
...>   Trogon.Result.ok(84),
...> ])
{:ok, [21,42,84]}

iex> Trogon.Result.collect([
...>   Trogon.Result.ok(21),
...>   Trogon.Result.err("oops"),
...>   Trogon.Result.ok(84),
...> ])
{:error, "oops"}

contains_err?(arg, value)

@spec contains_err?(result :: t(any(), e), value :: e) :: boolean() when e: any()

Returns true if the err/0 result contains the given value.

iex> "oops"
...> |> Trogon.Result.err()
...> |> Trogon.Result.contains_err?("oops")
true

iex> "oops"
...> |> Trogon.Result.err()
...> |> Trogon.Result.contains_err?("nop")
false

iex> 42
...> |> Trogon.Result.ok()
...> |> Trogon.Result.contains_err?("ops")
false

contains_ok?(arg, value)

@spec contains_ok?(result :: t(a, any()), value :: a) :: boolean() when a: any()

Returns true if the ok/0 result contains the given value.

iex> 42
...> |> Trogon.Result.ok()
...> |> Trogon.Result.contains_ok?(42)
true

iex> 21
...> |> Trogon.Result.ok()
...> |> Trogon.Result.contains_ok?(42)
false

iex> "oops"
...> |> Trogon.Result.err()
...> |> Trogon.Result.contains_ok?(42)
false

err(reason)

@spec err(reason) :: err(reason) when reason: any()

Wraps a value into an err/1 result.

iex> Trogon.Result.err("oops")
{:error, "oops"}

err?(arg)

@spec err?(value :: t()) :: boolean()

Returns true if the argument is an err/0.

iex> 42
...> |> Trogon.Result.ok()
...> |> Trogon.Result.err?()
false

iex> "oops"
...> |> Trogon.Result.err()
...> |> Trogon.Result.err?()
true

err_and?(arg, func)

@spec err_and?(value :: t(any(), e), predicate :: predicate(e)) :: boolean()
when e: any()

Returns true if the result is err/0 and the value inside of it matches a predicate.

iex> is_not_found = fn err -> err == :not_found end
...> 42
...> |> Trogon.Result.ok()
...> |> Trogon.Result.err_and?(is_not_found)
false

iex> is_not_found = fn err -> err == :not_found end
...> :not_found
...> |> Trogon.Result.err()
...> |> Trogon.Result.err_and?(is_not_found)
true

expect_err!(arg, message)

@spec expect_err!(result :: t(any(), e), message :: String.t()) :: e | no_return()
when e: any()

Returns the contained ok/0 value, or raise an exception with the given error message.

iex> try do
...>   42
...>   |> Trogon.Result.ok()
...>   |> Trogon.Result.expect_err!("expected a oops")
...> rescue
...>   e -> e.message
...> end
"expected a oops"

iex> try do
...>   "oops"
...>   |> Trogon.Result.err()
...>   |> Trogon.Result.expect_err!("expected a oops")
...> rescue
...>   _ -> "was a unwrap failure"
...> end
"oops"

expect_ok!(arg, message)

@spec expect_ok!(result :: t(a, any()), message :: String.t()) :: a | no_return()
when a: any()

Returns the contained ok/0 value, or raise an exception with the given error message.

iex> try do
...>   21
...>   |> Trogon.Result.err()
...>   |> Trogon.Result.expect_ok!("expected 42")
...> rescue
...>   e -> e.message
...> end
"expected 42"

iex> try do
...>   42
...>   |> Trogon.Result.ok()
...>   |> Trogon.Result.expect_ok!("expected 42")
...> rescue
...>   _ -> "was a unwrap failure"
...> end
42

flatten(value)

@spec flatten(result :: t(t(a, e), e)) :: t(a, e) when a: any(), e: any()

Converts from a nested t/0 to flatten t/0.

iex> 42
...> |> Trogon.Result.ok()
...> |> Trogon.Result.ok()
...> |> Trogon.Result.flatten()
{:ok, 42}

iex> 42
...> |> Trogon.Result.ok()
...> |> Trogon.Result.err()
...> |> Trogon.Result.flatten()
{:error, {:ok, 42}}

iex> "oops"
...> |> Trogon.Result.err()
...> |> Trogon.Result.ok()
...> |> Trogon.Result.flatten()
{:error, "oops"}

iex> "oops"
...> |> Trogon.Result.err()
...> |> Trogon.Result.err()
...> |> Trogon.Result.flatten()
{:error, {:error, "oops"}}

is_err_result(val)

(macro)

@spec is_err_result(value :: any()) :: Macro.t()

Is valid if and only if an err/0 is supplied.

iex> check = fn
...>   val when Trogon.Result.is_err_result(val) -> true
...>   _ -> false
...> end
...> 42
...> |> Trogon.Result.ok()
...> |> check.()
false

iex> check = fn
...>   val when Trogon.Result.is_err_result(val) -> true
...>   _ -> false
...> end
...> "oops"
...> |> Trogon.Result.err()
...> |> check.()
true

is_ok_result(val)

(macro)

@spec is_ok_result(value :: any()) :: Macro.t()

Is valid if and only if an ok/0 is supplied.

iex> check = fn
...>   val when Trogon.Result.is_ok_result(val) -> true
...>   _ -> false
...> end
...> 42
...> |> Trogon.Result.ok()
...> |> check.()
true

iex> check = fn
...>   val when Trogon.Result.is_ok_result(val) -> true
...>   _ -> false
...> end
...> "oops"
...> |> Trogon.Result.err()
...> |> check.()
false

map_err(result, on_error)

@spec map_err(result :: t(a, e1), on_error :: mapper(e1, e2)) :: t(a, e2)
when a: any(), e1: any(), e2: any()

@spec map_err(result :: t(a, e1), on_error :: e2) :: t(a, e2)
when a: any(), e1: any(), e2: any()

When the value contained in an err/0 result then applies a function or returns the mapped value, wrapping the returning value in a err/0, propagating the ok/0 result as it is.

Avoid Wrapping

If you want to avoid the wrap then use Trogon.Result.when_err/2 instead.

  iex> 21
  ...> |> Trogon.Result.err()
  ...> |> Trogon.Result.map_err("must be 42")
  {:error, "must be 42"}

  iex> 42
  ...> |> Trogon.Result.ok()
  ...> |> Trogon.Result.map_err("must be 42")
  {:ok, 42}

You can also pass a function to achieve lazy evaluation:

iex> meaning_of_life = fn x -> "must be 42 instead of #{x}" end
...> 21
...> |> Trogon.Result.err()
...> |> Trogon.Result.map_err(meaning_of_life)
{:error, "must be 42 instead of 21"}

map_ok(error, on_ok)

@spec map_ok(result :: t(a, e), on_ok :: mapper(a, b)) :: t(b, e)
when a: any(), b: any(), e: any()

@spec map_ok(result :: t(a, e), on_ok :: b) :: t(b, e)
when a: any(), b: any(), e: any()

When the value contained in an ok/0 result then applies a function or returns the mapped value, wrapping the returning value in a ok/0, propagating the err/0 result as it is.

Avoid Wrapping

If you want to avoid the wrap then use Trogon.Result.when_ok/2 instead.

iex> 21
...> |> Trogon.Result.ok()
...> |> Trogon.Result.map_ok(42)
{:ok, 42}

iex> "oops"
...> |> Trogon.Result.err()
...> |> Trogon.Result.map_ok(42)
{:error, "oops"}

You can also pass a function to achieve lazy evaluation:

iex> meaning_of_life = fn x -> x * 2 end
...> 21
...> |> Trogon.Result.ok()
...> |> Trogon.Result.map_ok(meaning_of_life)
{:ok, 42}

map_ok_or(arg, on_ok, on_error)

@spec map_ok_or(
  result :: t(a, e),
  on_ok :: mapper(a, b),
  on_error :: mapper(e, b) | b
) :: b
when a: any(), b: any(), e: any()

Applies a on_ok function to the contained value if ok/0 otherwise applies a on_err function or return the on_err value if err/0.

iex> meaning_of_life = fn x -> x * 2 end
...> 21
...> |> Trogon.Result.ok()
...> |> Trogon.Result.map_ok_or(meaning_of_life, 84)
42

iex> meaning_of_life = fn x -> x * 2 end
...> "oops"
...> |> Trogon.Result.err()
...> |> Trogon.Result.map_ok_or(meaning_of_life, 84)
84

Lazy Evaluation

It is recommended to pass a function as the default value, which is lazily evaluated.

iex> meaning_of_life = fn x -> x * 2 end
...> went_wrong = fn reason -> "something went wrong because #{reason}" end
...> 21
...> |> Trogon.Result.ok()
...> |> Trogon.Result.map_ok_or(meaning_of_life, went_wrong)
42

iex> meaning_of_life = fn x -> x * 2 end
...> went_wrong = fn reason -> "something went wrong because #{reason}" end
...> "a sleepy bear"
...> |> Trogon.Result.err()
...> |> Trogon.Result.map_ok_or(meaning_of_life, went_wrong)
"something went wrong because a sleepy bear"

ok(value)

@spec ok(value) :: ok(value) when value: any()

Wraps a value into an ok/1 result.

iex> Trogon.Result.ok(42)
{:ok, 42}

ok?(arg)

@spec ok?(value :: t()) :: boolean()

Returns true if the argument is a ok/0.

iex> 42
...> |> Trogon.Result.ok()
...> |> Trogon.Result.ok?()
true

iex> "oops"
...> |> Trogon.Result.err()
...> |> Trogon.Result.ok?()
false

ok_and?(arg, func)

@spec ok_and?(value :: t(a, any()), predicate :: predicate(a)) :: boolean()
when a: any()

Returns true if the result is ok/0 and the value inside of it matches a predicate.

iex> is_meaning_of_life = fn x -> x == 42 end
...> 42
...> |> Trogon.Result.ok()
...> |> Trogon.Result.ok_and?(is_meaning_of_life)
true

iex> is_meaning_of_life = fn x -> x == 42 end
...> "oops"
...> |> Trogon.Result.err()
...> |> Trogon.Result.ok_and?(is_meaning_of_life)
false

reject_nil(response, on_nil)

@spec reject_nil(value :: a | nil | t(a, e), on_nil :: e | lazy(e)) :: t(a, e)
when a: any(), e: any()

When nil is passed then calls the on_nil function and wrap the result into a err/0. When t/0 is passed then returns it as it is. Otherwise, wraps the value into a ok/0.

iex> Trogon.Result.reject_nil(nil, "ooopps")
{:error, "ooopps"}

iex> Trogon.Result.reject_nil(42, "ooopps")
{:ok, 42}

iex> 42
...> |> Trogon.Result.ok()
...> |> Trogon.Result.reject_nil("ooopps")
{:ok, 42}

iex> "my error"
...> |> Trogon.Result.err()
...> |> Trogon.Result.reject_nil("ooopps")
{:error, "my error"}

Lazy Evaluation

It is recommended to pass a function as the default value, which is lazily evaluated.

iex> new_error = fn -> "ooops" end
...> Trogon.Result.reject_nil(nil, new_error)
{:error, "ooops"}

tap_err(result, func)

@spec tap_err(result :: t(a, e), func :: tap_func(e)) :: t(a, e)
when a: any(), e: any()

Tap into err/0 results.

iex> failure_log = fn err -> "Failure because #{err}" end
...> "ooopsy"
...> |> Trogon.Result.err()
...> |> Trogon.Result.tap_err(failure_log)
{:error, "ooopsy"}

tap_ok(result, func)

@spec tap_ok(result :: t(a, e), func :: tap_func(a)) :: t(a, e)
when a: any(), e: any()

Tap into ok/0 results.

iex> success_log = fn x -> "Success #{x}" end
...> 42
...> |> Trogon.Result.ok()
...> |> Trogon.Result.tap_ok(success_log)
{:ok, 42}

unwrap(arg)

@spec unwrap(result :: t(a, a)) :: a when a: any()

Returns the contained ok/0 value or t:error/0 value from a t/0.

iex> 42
...> |> Trogon.Result.ok()
...> |> Trogon.Result.unwrap()
42

iex> "oops"
...> |> Trogon.Result.err()
...> |> Trogon.Result.unwrap()
"oops"

unwrap_err!(arg)

@spec unwrap_err!(result :: t(any(), e)) :: e | no_return() when e: any()

Unwrap an err/0 result, or raise an exception.

iex> try do
...>   "oops"
...>   |> Trogon.Result.err()
...>   |> Trogon.Result.unwrap_err!()
...> rescue
...>   Trogon.Result.ErrUnwrapError -> "was a unwrap failure"
...> end
"oops"

iex> try do
...>   42
...>   |> Trogon.Result.ok()
...>   |> Trogon.Result.unwrap_err!()
...> rescue
...>   Trogon.Result.ErrUnwrapError -> "was a unwrap failure"
...> end
"was a unwrap failure"

unwrap_ok(arg, on_error)

@spec unwrap_ok(result :: t(a, e), on_error :: mapper(e, a)) :: a
when a: any(), e: any()

@spec unwrap_ok(result :: t(a, e), on_error :: a) :: a when a: any(), e: any()

Returns the contained ok/0 value or a provided default.

iex> 42
...> |> Trogon.Result.ok()
...> |> Trogon.Result.unwrap_ok(21)
42

iex> "oops"
...> |> Trogon.Result.err()
...> |> Trogon.Result.unwrap_ok(21)
21

Lazy Evaluation

It is recommended to pass a function as the default value, which is lazily evaluated.

iex> say_hello_world = fn _x -> "hello, world!" end
...> 42
...> |> Trogon.Result.ok()
...> |> Trogon.Result.unwrap_ok(say_hello_world)
42

iex> say_hello_world = fn _x -> "hello, world!" end
...> "oops"
...> |> Trogon.Result.err()
...> |> Trogon.Result.unwrap_ok(say_hello_world)
"hello, world!"

unwrap_ok!(arg)

@spec unwrap_ok!(result :: t(a, any())) :: a | no_return() when a: any()

Unwrap an ok/0 result, or raise an exception.

iex> try do
...>   42
...>   |> Trogon.Result.ok()
...>   |> Trogon.Result.unwrap_ok!()
...> rescue
...>   Trogon.Result.OkUnwrapError -> "was a unwrap failure"
...> end
42

iex> try do
...>   "oops"
...>   |> Trogon.Result.err()
...>   |> Trogon.Result.unwrap_ok!()
...> rescue
...>   Trogon.Result.OkUnwrapError -> "was a unwrap failure"
...> end
"was a unwrap failure"

when_err(resp, on_err)

@spec when_err(result :: t(a, e), on_err :: mapper(e, b)) :: ok(a) | b
when a: any(), b: any(), e: any()

@spec when_err(result :: t(a, e), on_err :: b) :: ok(a) | b
when a: any(), b: any(), e: any()

Applies a function or returns the value if the result is err/0, otherwise returns the ok/0 value.

iex> "something wrong happened"
...> |> Trogon.Result.err()
...> |> Trogon.Result.when_err("ooops")
"ooops"

iex> 2
...> |> Trogon.Result.ok()
...> |> Trogon.Result.when_err("ooops")
{:ok, 2}

You can also pass a function to achieve lazy evaluation:

iex> failure = fn _error -> "lazy ooops" end
...> "something wrong happened"
...> |> Trogon.Result.err()
...> |> Trogon.Result.when_err(failure)
"lazy ooops"

when_ok(error, on_ok)

@spec when_ok(result :: t(a, e), on_ok :: mapper(a, b)) :: err(e) | b
when a: any(), b: any(), e: any()

@spec when_ok(result :: t(a, e), on_ok :: b) :: err(e) | b
when a: any(), b: any(), e: any()

Applies a function or returns the value when a ok/0 is given, or propagates the error.

iex> 21
...> |> Trogon.Result.ok()
...> |> Trogon.Result.when_ok(42)
42

iex> "oops"
...> |> Trogon.Result.err()
...> |> Trogon.Result.when_ok(42)
{:error, "oops"}

You can also pass a function to achieve lazy evaluation:

iex> meaning_of_life = fn x -> x * 2 end
...> 21
...> |> Trogon.Result.ok()
...> |> Trogon.Result.when_ok(meaning_of_life)
42