Flow DSL

View Source

Overview

The Flow DSL is compile-time Elixir syntax for canonical Flow data. Its data expressions are restricted. An inline Action body is normal Elixir code that compiles to an Action.

Run the cells from top to bottom.

Install The Package

Inline Steps require 3.0.0-beta.5 or later.

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

Define Small Actions

defmodule FlowLanguage.Echo do
  use Jido.Action, name: "flow_language_echo"

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

defmodule FlowLanguage.Append do
  use Jido.Action, name: "flow_language_append"

  @impl true
  def run(%{values: values, item: item}, _context) do
    {:ok, %{values: values ++ [item]}}
  end
end

defmodule FlowLanguage.Increment do
  use Jido.Action, name: "flow_language_increment"

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

Declare The Graph

The seven component forms are step, choice, map, reduce, iterate, dispatch, and a Flow-derived subflow. A child Flow is written as a step whose target is a Flow module. Dispatch can only appear at the end of a run-to-completion Flow.

defmodule FlowLanguage.Example do
  use Jido.Flow, name: "flow_language_example"

  flow do
    step "seed", value <- input(:value) do
      {:ok, %{value: value}}
    end

    choice "route" do
      option "fast",
        condition: input(:mode) == :fast,
        action: FlowLanguage.Echo,
        params: %{route: :fast, value: result("seed", :value)}

      otherwise action: FlowLanguage.Echo, params: %{route: :standard, value: result("seed", :value)}
    end

    map "mapped",
      collection: input(:items),
      action: FlowLanguage.Echo,
      params: %{value: item(), index: item_index()}

    reduce "collected" do
      collection(result("mapped"))
      initial(%{values: value([])})
      action(FlowLanguage.Append)
      params(%{
        values: accumulator(:values),
        item: item(:value)
      })
    end

    iterate "counter" do
      state(Zoi.object(%{count: Zoi.integer()}), initial: %{count: 0})
      action(FlowLanguage.Increment)
      params(%{count: state(:count)})
      update(%{count: body_result(:count)})
      repeat(2)
    end

    output(%{
      route: result("route"),
      values: result("collected", :values),
      counter: result("counter", :state)
    })
  end
end
{:ok, result} =
  Jido.Exec.run(FlowLanguage.Example, %{
    value: 10,
    mode: :fast,
    items: [1, 2, 3]
  })

result

Keep Headers And Output As Data

An inline binding source can contain:

  • nil, Boolean values, numbers, strings, and atoms;
  • proper lists;
  • maps with supported data keys; and
  • Flow references.

Inline binding sources do not accept Jido.Expr operations. Bind the required data and put calculations in the inline body. Other Flow data fields accept fixed portable operations. See Expressions. It requires 3.0.0-beta.6 or later.

These forms are not Flow expressions:

function calls
anonymous functions
pipes
pattern matches
tuples
keyword lists
struct construction

Use value/1 when you want to mark one supported literal explicitly. Use select/2 to append a path to a reference. The Reduce example uses value([]) to mark its empty-list accumulator as literal data.

These restrictions do not apply inside an inline Action body. It can call functions, use pipes, match patterns, and create local anonymous functions. Those functions are not Flow targets. Flow reference helpers have no runtime meaning in the body; bind their data in the header first. See Steps And Output for the binding forms.

An inline body has the owning Flow module's function scope. It can use private helpers, aliases, available imports, declaration-time module attributes, and __MODULE__. It does not capture runtime variables outside the declaration. Jido removes its declaration imports inside the body. Spark can also remove an outer import that conflicts with a DSL name. Use a qualified call such as MyApp.Helpers.output(value), or import that helper inside the body.

Only step accepts an inline Action body. Use inline: on that Step for Action settings. Map, Reduce, Choice targets, Iterate, and Dispatch use named Action modules. See Inline Actions for the Flow syntax. See Building DSLs With Inline Actions for the separate public downstream host API.

Use Closed Conditions

The DSL supports these condition forms:

input(:status) == :ready
input(:count) >= 3
input(:tier) in [:gold, :silver]
input(:enabled) == true and input(:blocked) != true
not (input(:status) == :closed)

The canonical operators are eq, neq, lt, lte, gt, gte, in, all, any, and not.

Declare Output

The module DSL requires an explicit output as the final declaration. Normal Flow output must be a map. An explicit Jido.Action.Output envelope can carry a non-map result.

Continue with Steps And Output and References And Data.