@spec error_then(result(), (any() -> any())) :: result()

For dealing with :error cases, passing :ok results through unchanged.

When given result is {:error, reason}, the reason is passed into the callback function. The callback function can then return a new reason which will be returned from error_then wrapped in an {:error, _} tuple.

If :error is the given result, nil will be given to the callback function.

The callback function can also return :ok or {:ok, any()} to have the error be ignored and the :ok result will be returned instead.

Examples

iex> ping_account_server() |> Triage.error_then(fn _ -> :account_server_failure end)
{:error, :account_server_failure}

iex> Triage.error_then({:error, :unknown}, fn :unknown -> {:ok, @default_value} end)
{:ok, ...}

iex> Triage.error_then(:ok, fn _ -> :not_used end)
:ok

iex> Triage.error_then({:ok, ...}, fn _ -> :not_used end)
{:ok, 42}

iex> Triage.error_then(:error, fn nil -> :handled end)
{:error, :handled}

@spec ok_then(result(), (any() -> any()), [{:retries, non_neg_integer()}]) :: result()

Executes a function with a previous result value, with exception handling.

Takes a result and, if :ok, passes the value from the tuple to the provided function. If the previous result was an error, short-circuits and returns the error.

If the function raises an exception, it catches it and returns {:error, %Triage.WrappedError{}} with details about the exception.

Parameters

• result - The previous result (:ok, {:ok, value}, :error, or {:error, reason})
• func - A function that takes the unwrapped value and returns a result

Examples

iex> ok_then({:ok, 5}, fn x -> {:ok, x * 2} end)
{:ok, 10}

iex> ok_then({:ok, 5}, fn _x -> raise "boom" end)
{:error, %Triage.WrappedError{}}

@spec ok_then!(result(), (any() -> any()), [{:retries, non_neg_integer()}]) ::
  result()

Executes a function with a previous result value, without exception handling.

Takes a result and, if it's an :ok, passes the value from the tuple to the provided function. If the result was an error, short-circuits and returns the error without calling the function.

This is the "unsafe" version that doesn't catch exceptions. Use ok_then/2 for exception handling.

Parameters

• result - The previous result (:ok, {:ok, value}, :error, or {:error, reason})
• func - A function that takes the unwrapped value and returns a result

Examples

iex> ok_then!({:ok, 5}, fn x -> {:ok, x * 2} end)
{:ok, 10}

iex> ok_then!({:error, :not_found}, fn x -> {:ok, x * 2} end)
{:error, :not_found}

@spec run((-> any()), [{:retries, non_neg_integer()}]) :: result()

Executes a function that returns a result tuple, with exception handling.

Calls the provided zero-arity function and ensures it returns a valid result. If the function raises an exception, it catches it and returns {:error, %Triage.WrappedError{}} with details about the exception.

Parameters

• func - A zero-arity function that returns a result

Examples

iex> run(fn -> {:ok, 42} end)
{:ok, 42}

iex> run(fn -> raise "boom" end)
{:error, %Triage.WrappedError{}}

@spec run!((-> any()), [{:retries, non_neg_integer()}]) :: result()

Executes a function that returns a result tuple, without exception handling.

Calls the provided zero-arity function and checks that it returns a result (:ok, {:ok, value}, :error, or {:error, reason}). If the function returns any other value, it wraps it in {:ok, value}.

This is the "unsafe" version that doesn't catch exceptions. Use run/1 for exception handling.

Parameters

• func - A zero-arity function that returns a result

Examples

iex> run!(fn -> 42 end)
{:ok, 42}

iex> run!(fn -> {:ok, 42} end)
{:ok, 42}

iex> run!(fn -> {:error, :not_found} end)
{:error, :not_found}

iex> run!(fn -> :error end)
:error

iex> run!(&function_to_try, retries: 2)
:error

@spec tap_error(result(), (any() -> any())) :: result()

Executes a side-effect function when the result is an error, passing the result through unchanged.

Takes a result and, if it's :error or {:error, reason}, calls the provided function with the unwrapped reason (or nil for :error). The result is always returned unchanged, making this useful for side effects like logging or debugging errors.

If the result is :ok, the function is not called and the :ok result is returned unchanged.

Examples

# Monitor payment failures and send alerts
iex> process_payment(order)
...> |> tap_error(fn reason ->
...>   ErrorTracker.report(reason, context: %{order_id: order.id})
...>   if reason == :payment_gateway_down, do: PagerDuty.alert("Gateway down")
...> end)
{:error, :payment_gateway_down}

# Track metrics for failed operations
iex> update_inventory(product_id, quantity)
...> |> tap_error(fn reason ->
...>   ErrorTracker.report(reason, context: %{product_id: product_id})
...>   Metrics.increment("inventory.update.failed", tags: %{reason: reason})
...> end)
{:error, :insufficient_stock}

# Success results pass through without calling the function
iex> tap_error({:ok, user}, fn _ -> ErrorTracker.report("Won't be called") end)
{:ok, %User{}}

@spec tap_ok(result(), (any() -> any())) :: result()

Executes a side-effect function when the result is :ok, passing the result through unchanged.

Takes a result and, if it's :ok or {:ok, value}, calls the provided function with the unwrapped value (or nil for :ok). The result is always returned unchanged, making this useful for side effects like logging or debugging.

If the result is an error, the function is not called and the error is returned unchanged.

Examples

# Track analytics for successful user registrations
iex> register_user(params)
...> |> tap_ok(fn user -> Analytics.track("user_registered", %{user_id: user.id}) end)
{:ok, %User{email: "user@example.com"}}

# Cache API responses while continuing the pipeline
iex> fetch_product_from_api(product_id)
...> |> tap_ok(fn product -> Cache.put("product:#{product_id}", product) end)
{:ok, %Product{id: 123, name: "Widget"}}

# Errors pass through without calling the function
iex> tap_ok({:error, :not_found}, fn user -> send_notification(user) end)
{:error, :not_found}