Choices And Conditions

View Source

Overview

A Choice evaluates conditions in author order. It runs the first matching Action. A required fallback handles the no-match case.

Run the cells from top to bottom.

Install The Package

Mix.install([{:jido_action, "~> 3.0.0-beta.11"}])

Define A Routing Action

defmodule FlowChoices.Route do
  use Jido.Action, name: "flow_choices_route"

  @impl true
  def run(params, _context), do: {:ok, params}
end

Declare Ordered Options

defmodule FlowChoices.Example do
  use Jido.Flow, name: "flow_choices_example"

  flow do
    choice "route" do
      option "urgent",
        condition: input(:priority) >= 90,
        action: FlowChoices.Route,
        params: %{queue: :urgent, id: input(:id)}

      option "priority",
        condition: input(:priority) >= 50,
        action: FlowChoices.Route,
        params: %{queue: :priority, id: input(:id)}

      otherwise action: FlowChoices.Route, params: %{queue: :standard, id: input(:id)}
    end

    output(%{route: result("route")})
  end
end
{:ok, urgent} =
  Jido.Exec.run(FlowChoices.Example, %{id: 1, priority: 100})

{:ok, standard} =
  Jido.Exec.run(FlowChoices.Example, %{id: 2, priority: 10})

{urgent, standard}

When two conditions match, only the first option runs. Jido does not evaluate later options after a match.

Result references in every option and in the fallback become static graph dependencies. The referenced components run before Choice selection, even when Jido does not select the option that contains a reference. Put work that must stay lazy inside the selected Action.

Condition Grammar

The DSL accepts:

==  !=  <  <=  >  >=  in
and  or  not
eq  neq  lt  lte  gt  gte
all  any

Conditions compare Flow expressions. They do not call application functions. Put complex or effectful decisions in an Action before the Choice, then test that Action result.

With the expression API, not also accepts a Boolean reference. Direct Boolean references and literals are valid conditions:

condition: not input(:enabled)
# In an Iterate component:
while not state(:done)

Declare the field as a required Zoi.boolean() in the Flow input schema, the producing Action's output schema, or the Iterate State schema. For example, Zoi.object(%{enabled: Zoi.boolean()}) rejects missing and non-Boolean input. The direct condition rejects a non-Boolean value. An explicit comparison such as input(:enabled) == false keeps its existing equality behavior and does not validate the type. A missing reference still fails. The expression API requires 3.0.0-beta.6 or later; see Expressions.

Fallback Is Routing

otherwise is mandatory. It is the normal route when no option matches. It is not an error handler. If a selected Action fails, the Choice fails and does not run the fallback.

Choice option and fallback targets must be Actions. A Choice does not derive a Subflow target.

Choice options and fallback use Action modules. Put their Flow inputs in params. Only the selected Action runs. A fallback remains a normal route, not an error handler.

Route An Expected Failure As Data

Keep expected provider outcomes in the application's result contract. A small Action wrapper can convert a specific error to data that Choice can inspect. Return other errors unchanged. Do not catch all exceptions or use Choice fallback as recovery from a failed target.

This local provider has no external effects:

defmodule FlowChoices.Provider do
  def fetch(:missing),
    do: {:error, Jido.Action.Error.validation_error("not found", code: :not_found)}

  def fetch(:offline),
    do: {:error, Jido.Action.Error.execution_error("offline", retry: true)}

  def fetch(id), do: {:ok, %{id: id}}
end

defmodule FlowChoices.Fetch do
  use Jido.Action, name: "flow_choices_fetch"

  @impl true
  def run(%{id: id}, _context) do
    case FlowChoices.Provider.fetch(id) do
      {:ok, value} ->
        {:ok, %{status: :ok, value: value, error: nil}}

      {:error, %Jido.Action.Error.InvalidInputError{details: %{code: :not_found}} = error} ->
        {:ok, %{status: :error, value: nil, error: Jido.Flow.Error.to_map(error)}}

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

defmodule FlowChoices.ExpectedFailure do
  use Jido.Flow, name: "flow_choices_expected_failure"

  flow do
    step "fetch", action: FlowChoices.Fetch, params: %{id: input(:id)}

    choice "route" do
      option "missing",
        condition: result("fetch", :status) == :error,
        action: FlowChoices.Route,
        params: %{route: :missing, error: result("fetch", :error)}

      otherwise action: FlowChoices.Route, params: %{route: :found, value: result("fetch", :value)}
    end

    output(result("route"))
  end
end
{:ok, %{route: :found, value: %{id: 1}}} =
  Jido.Exec.run(FlowChoices.ExpectedFailure, %{id: 1})

{:ok, %{route: :missing, error: %{type: :validation_error, details: %{code: :not_found}}}} =
  Jido.Exec.run(FlowChoices.ExpectedFailure, %{id: :missing})

{:error, %Jido.Action.Error.ExecutionFailureError{}} =
  Jido.Exec.run(FlowChoices.ExpectedFailure, %{id: :offline})

The wrapper preserves the expected error's mapped type, message, details, and retry flag. This result is successful application data, not a failed Flow node. It does not receive automatic error telemetry or added node/execution identity. Add application correlation data explicitly when needed. A selected route that fails still fails the Flow; it does not run otherwise.

The provider above is an ordinary function. If the provider is another Jido Action, do not call its run/2 callback and assume validation occurred. Use its validation boundary, or move the shared provider operation to an ordinary function. There is no on_error: :capture option on Step or Choice.

Canonical Form

A Jido.Flow.Choice contains ordered Jido.Flow.Choice.Option values and one Jido.Flow.Choice.Fallback. Use their constructors for direct authoring or use option and fallback maps for data authoring.

Expression Result Types

Conditions must produce a Boolean. Native and and or can return their right operand unchanged: true and 123 evaluates to 123 and is rejected at the condition boundary. The same expression is valid inside a data map. See Expressions for the V3 beta behavior corrections.