Inline Actions
View SourceAn inline Action keeps a small operation in the Flow Step that owns it. Its
body is normal Elixir code, but it compiles to an ordinary Jido.Action.
Flow supports inline Actions only for Step. Map, Reduce, Choice targets, Iterate, and Dispatch use Action modules. This keeps advanced Flow blocks declarative.
The separate Jido.Action.Inline API remains available to downstream packages
that want inline Actions in their own compile-time DSLs. See
Building DSLs With Inline Actions.
Write An Inline Step
Bind Flow data in the Step header and write the Action body directly:
defmodule MyApp.Flows.Greeting do
use Jido.Flow, name: "greeting"
flow do
step "normalize", name <- input(:name) do
{:ok, %{name: String.trim(name)}}
end
step "greet", name <- result("normalize", :name) do
{:ok, %{message: "Hello, " <> name <> "!"}}
end
output result("greet")
end
endThe binding expression is Flow data. The body is normal Elixir. The body can call functions, use pipes, match values, and call private functions in the owner module.
Configure An Inline Step
Use inline: for Action settings. Keep Step fields such as needs: and
meta: at the Step level:
step "greet", name <- result("normalize", :name),
needs: ["normalize"],
meta: %{kind: "message"},
inline: [
name: "build_greeting",
description: "Build a greeting",
schema: Zoi.object(%{name: Zoi.string()}),
output_schema: Zoi.object(%{message: Zoi.string()}),
context: ctx
] do
{:ok, %{message: ctx.prefix <> ", " <> name}}
endThe valid inline: settings are:
namedescriptionschemaoutput_schemacontext
All settings are optional. Omitted schemas are []. Bindings do not infer
fields, types, or defaults.
context: ctx binds the second Action callback argument. It does not add a
parameter. Bind ctx <- context() only when context must become part of the
Action parameter map.
Do not add action: or params: to an inline Step. A named Action Step uses
those fields and has no inline body:
step "greet",
action: MyApp.Actions.Greet,
params: %{name: result("normalize", :name)},
needs: ["normalize"],
meta: %{kind: "message"}Bind Inputs
Bound inline Steps resolve direct Flow references or data into an atom-keyed parameter map:
| Header | Parameters passed to the Action |
|---|---|
value <- source | %{value: resolved_source} |
[left <- source, right <- other] | A map with both resolved values. |
%{name: name} <- source | The complete resolved source map. |
[] | %{} |
Examples:
step "double", value <- input(:value) do
{:ok, %{value: value * 2}}
end
step "add", [left <- input(:left), right <- input(:right)] do
{:ok, %{total: left + right}}
end
step "normalize", %{name: name} <- input(:person) do
{:ok, %{name: String.trim(name)}}
end
step "ready", [] do
{:ok, %{ready: true}}
endUse one binding argument. Two or more named bindings require a list. Do not
mix a map binding with named bindings. A map binding must be the only
binding. Pins, header guards, top-level struct patterns, duplicate names, and
bare _ bindings are not supported. Flow operations are not supported in
binding sources. Bind the required data and put calculations in the body.
Match Values Inside The Body
Use an ordinary case expression when a Step must select between input values:
step "divide", operand <- input(:operand),
inline: [schema: Zoi.object(%{operand: Zoi.number()})] do
case operand do
0 -> {:error, Jido.Action.Error.validation_error("Cannot divide by zero")}
operand -> {:ok, %{value: 100 / operand}}
end
endFlow does not accept top-level clause bodies. Nested case, fn, and other
normal Elixir expressions remain available. Downstream DSLs can still use
clause bodies through the separate Jido.Action.Inline host API.
Use Action Modules In Advanced Components
Advanced components use Action modules and canonical parameter expressions:
map "doubled" do
collection input(:values)
action MyApp.Actions.DoubleValue
params %{value: item()}
end
reduce "total" do
collection result("doubled")
initial %{total: 0}
action MyApp.Actions.AddValue
params %{total: accumulator(:total), value: item(:value)}
endChoice options, Choice fallback, Iterate, and Dispatch follow the same rule. Their target fields accept Action modules only.
An Action module can be handwritten or generated by another compile-time DSL. The restriction applies to inline body declarations inside Flow components, not to how a valid Action module was created.
An advanced component can reuse an Action that was compiled from an inline Step after the owner Flow has compiled:
action = MyApp.Flows.Greeting.step_action("normalize")
Jido.Flow.new!(%{
name: "normalize_names",
components: [
%{
kind: :map,
name: "names",
collection: Jido.Flow.Ref.input(:people),
action: action,
params: %{name: Jido.Flow.Ref.item()}
}
],
output: Jido.Flow.Ref.result("names")
})This is normal Action reuse. It is not an inline Map body.
Return Values
An inline Step uses the same return forms as a named Action:
{:ok, result}
{:ok, result, effects}
{:error, reason}
{:error, reason, effects}A normal success result is a map. Use Jido.Action.Output for an intentional
raw, stream, batch, or opaque value.
Flow components collect effect lists and require a proper list for the third success element. A root Action can return
{:continue, input, target}. A Step cannot continue to another target.
Reuse A Compiled Inline Step
An inline body compiles with its owner module. Reuse its Action target without using the generated module name:
target = MyApp.Flows.Greeting.step_action("normalize")
{:ok, %{name: "Ada"}} =
Jido.Exec.run(target, %{name: " Ada "})step_action/1 works for inline and explicit Action-backed Steps. It does not
work for Subflows or other component types.
The target does not retain the original Flow binding expressions. Supply a new parameter map when you run it or place it in a data-defined Flow.
Register a reused target under an application-owned stable identifier. Do not store its generated module name. JSON stores target identifiers and data, not inline bodies.
Compile-Time Limits
An inline body can use the owner module's private helpers, aliases, imports,
module attributes, and __MODULE__. It cannot capture runtime variables from
outside its declaration.
Inline Actions are compile-time code. Direct constructors, data definitions, and stored JSON cannot accept body code, anonymous functions, or MFAs. Deploy the owner module and its generated Action modules together.
Use a named Action module when the work needs independent reuse, lifecycle hooks, a public module API, or a separate deployment boundary.