Iterate And State

View Source

Overview

Iterate runs one Action as a bounded local state transition. It is one Flow component and one native Runic Step.

Run the cells from top to bottom.

Install The Package

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

Define The Body Action

defmodule FlowIterate.Increment do
  use Jido.Action, name: "flow_iterate_increment"

  @impl true
  def run(%{count: count, index: index}, _context) do
    {:ok, %{count: count + 1, index: index}}
  end
end

Repeat A Fixed Count

defmodule FlowIterate.RepeatThree do
  use Jido.Flow, name: "flow_iterate_repeat_three"

  flow do
    iterate "counter" do
      state(
        Zoi.object(%{count: Zoi.integer()}),
        initial: %{count: 0}
      )

      action(FlowIterate.Increment)
      params(%{
        count: state(:count),
        index: iteration_index()
      })

      update(%{count: body_result(:count)})
      repeat(3)
    end

    output(%{counter: result("counter")})
  end
end
{:ok,
 %{
   counter: %{
     kind: :jido_flow_iterate_result,
     iterations: 3,
     state: %{count: 3},
     output: %{count: 3, index: 2}
   }
 }} = Jido.Exec.run(FlowIterate.RepeatThree)

The result contains the completed iteration count, final State, and latest body output.

Continue While A Condition Is True

while is a head condition. If it is false for the initial State, the body does not run. A while form must also set max_iterations.

iterate "counter" do
  state(Zoi.object(%{count: Zoi.integer()}), initial: %{count: 0})
  action(FlowIterate.Increment)
  params(%{count: state(:count), index: iteration_index()})
  update(%{count: body_result(:count)})
  while(state(:count) < 3)
  max_iterations(10)
end

If the condition remains true at the bound, the Iterate fails with a Flow execution error. The maximum can be from 1 through 10,000.

State Update

The State update expression runs after each successful body Action. The default update is the complete body result. Use update when the body result has a different shape.

The State schema validates the initial State and each candidate replacement. State is replaced, not merged.

These references have Iterate-local scope:

  • state(path);
  • iteration_index(); and
  • body_result(path) in the update expression.

The Iterate target must be an Action. Nested Flow execution is not supported in the body target slot.

Iterate uses an Action module for its body. Put state, iteration_index, and body_result references in params. In params, body_result() is nil before the first body call and holds the previous body result on later calls. In the update expression, it holds the current body result. The Action schema validates body params. The State schema separately validates each replacement State.

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.