Finitomata.Error (Finitomata v0.41.0)

The canonical representation of a failure that happened while processing a transition.

Historically Finitomata stored the last error as an ad-hoc map and returned a handful of different error shapes ({:error, atom}, {:error, tuple}, keyword-tagged tuples like {:error, transition: …, persistency: …}.) This struct unifies them.

It is intentionally a superset of the legacy %{state:, event:, error:} map, so existing code that reads last_error.error, last_error.state or last_error.event, or pattern matches on %{error: …}, keeps working. New code should prefer the canonical fields:

stage — where the failure originated (:on_transition, :persistency, …)
reason — the normalized reason (the value unwrapped from a leading {:error, _})
state/event/event_payload — the transition context
error — the raw value as it was produced (kept for backward compatibility)
context — any extra information (e.g. the originating transition error for a persistency failure)

Summary

Types

stage()

The stage of the FSM lifecycle the error originated from

t()

Functions

wrap(error, context \\ [])

Wraps an arbitrary transition failure into a canonical Finitomata.Error.t/0.

Types

stage()

(since 0.36.0)

@type stage() :: :on_transition | :persistency | :not_allowed | :unknown

The stage of the FSM lifecycle the error originated from

t()

(since 0.36.0)

@type t() :: %Finitomata.Error{
  context: map(),
  error: any(),
  event: Finitomata.Transition.event() | nil,
  event_payload: Finitomata.event_payload() | nil,
  reason: any(),
  stage: stage(),
  state: Finitomata.Transition.state() | nil
}

Functions

wrap(error, context \\ [])

(since 0.36.0)

@spec wrap(
  any(),
  keyword()
) :: t()

Wraps an arbitrary transition failure into a canonical Finitomata.Error.t/0.

context is a keyword list providing the transition context (:state, :event, :event_payload). Already-wrapped errors are returned untouched.