Flow DSL
View SourceOverview
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}}
endDeclare 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]
})
resultKeep 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 constructionUse 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.