Inline Actions

View Source

An 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
end

The 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}}
end

The valid inline: settings are:

  • name
  • description
  • schema
  • output_schema
  • context

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:

HeaderParameters passed to the Action
value <- source%{value: resolved_source}
[left <- source, right <- other]A map with both resolved values.
%{name: name} <- sourceThe 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}}
end

Use 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
end

Flow 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)}
end

Choice 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.