Triage Elixir Library

Triage Refactoring Assistant

Expert guidance for refactoring Elixir code to use the Triage library - a lightweight error handling library that provides pipeline-based result handling with context wrapping and logging.

Core Triage Concepts

Result Types

Triage works with standard Elixir results:

• :ok and {:ok, value}
• :error and {:error, reason}

Some functions take {:ok, ...} / {:error, ...} tuples with more than two elements, but the philosophy of Triage is to reduce :ok / :error tuples to two elements as much as possible.

Key Functions Overview

Best practice is to never import Triage but always to refer to Triage.function.

Control Flow:

• Triage.ok_then!/2 - Handling :ok results, allows exceptions to raise
• Triage.ok_then/2 - Handling :ok results, catches exceptions and returns {:error, Triage.WrappedError.t()}
• Triage.ok_then/1 - Executes callback function, catches exceptions and returns {:error, Triage.WrappedError.t()}
• Triage.error_then/2 - error_then :error results

VERY IMPORTANT NOTE ABOUT THE ok_then!/2, ok_then/2, and error_then/2 FUNCTIONS

The first argument to these functions must always be a result (:ok, :error, {:ok, ...}, {:error, ...})

The second argument is always a function which is given the value/reason of the :ok/:errortuple. If the callback took_thenreturns something other than a result, it automatically wraps with{:ok, _}. If the callback to error_thenreturns something other than a result, it automaticalyl wraps with{:error, _}`

|> Triage.ok_then!(& &1 + 1)
# If given `:error` result as first argument, the callback isn't executed and the argument is returned
# If given `{:ok, 2}`, returns `{:ok, 3}`

|> Triage.error_then(fn _ -> :operation_failed end)
# If given `:ok` result as first argument, the callback isn't executed and the argument is returned
# If given `{:error, :something}` returns `{:error, :operation_failed}

If the callback to ok_then functions returns an :error result, the :error result is returned without wrapping in {:ok, _}

If the callback to error_then functions returns an :ok result, the :ok result is returned without wrapping in {:error, _}

Context & Debugging

Triage.wrap_context/2,3

Returns a Triage.WrappedContext.t() which stores the original error with a context string and/or metadata

|> Triage.wrap_context("querying user service")
# or...
|> Triage.wrap_context("querying user service", %{user_id: user_id})
# or...
|> Triage.wrap_context(%{user_id: user_id})

Triage.log/1,2

Log results with file/line info. Works especially well when given error tuples with Triage.WrappedError.t() values.

Second argument default to :errors, but can be :all to log :ok results as well.

Triage.user_message/1,2

Takes in an error result ({:error, _}). Extracts user-friendly error messages for returning in HTML/JSON/etc...

If a user-friendly error message can't be made from the error result, will log technical details about the error and provide a unique code for the user to pass onto support to find that log line.

Enumeration

Triage.map_if/2 - Map with error short-circuiting

Triage.find_value/2 - Find first success

Triage.all/1 - Verify all are successful

Important to know

with clauses

It may be tempting to replace all with statements which have {:ok, _} clause patterns, but it's not always a good fit.

Simplifying functions

Sometimes using triage can lead to a function being simplified to a single function call. Often it makes code simpler to remove the function if this happens.

Example:

  with {:ok, nouns} <- cue_transactions(transactions),

  # ... further down ...

  defp cue_transactions(transactions) do
    Enum.reduce_while(transactions, [], fn tx, acc ->
      case cue_transaction(tx) do
        {:ok, noun} ->
          {:cont, acc ++ [noun]}

        {:error, :cue_failed, err} ->
          {:halt, {:error, :cue_failed, err}}
      end
    end)
    |> case do
      {:error, {:cue_failed, err}} ->
        {:error, {:cue_failed, err}}

      txs ->
        {:ok, txs}
    end
  end

Could be simplified to just:

transactions
|> Triage.map_if(&cue_transaction/1)

Handling errors

with ... do
   # ...
else
   {:error, {:cue_failed, err}} ->
      {:error, {:invalid_input, err}}

   {:error, :noun_not_a_valid_transaction} ->
      {:error, :noun_not_a_valid_transaction}

   {:error, :not_enough_transactions} ->
      {:error, :not_enough_transactions}
end

In order to keep the behavior the same you need to preserve that MatchError that might happen on any unspecified errors. So instead of this:

|> Triage.error_then(fn
   {:cue_failed, err} -> {:invalid_input, err}
   reason -> reason
end)

You would do this:

|> Triage.error_then(fn
   {:cue_failed, err} -> {:invalid_input, err}
   :noun_not_a_valid_transaction -> :noun_not_a_valid_transaction
   :not_enough_transactions -> :not_enough_transactions
end)

Critical Rules to Remember

When ok_then / ok_then! receives :ok as an error result, it passes nil to the callback.

When error_then receives :error as an error result, it passes nil to the callback.

Don't always use ok_then (not ok_then!) when function might raise. Sometimes we want to raise an exception if the process should crash in that situation. Default to ok_then! functions, especially when refactoring as it's the same behavior as before.

Context is cumulative: Each wrap_context adds to the error context chain which adds details for Triage.log and Triage.user_message.

Be careful about using wrap_context: refactoring generally needs to be done at a higher level to support the Triage.WrapError.t() value.

Verification Steps

After refactoring:

1. Ensure all result types are standard (:ok, {:ok, ...}, :error, {:error, ...})
2. Verify exception handling requirements (use ok_then vs ok_then! appropriately)
3. Test error paths to ensure proper propagation
4. Check for double-wrapping anti-pattern