Flow Modules
View SourceA Flow module is the primary source-code authoring API. Spark parses the DSL at
compile time and lowers it once to a canonical %Jido.Flow{}.
The DSL field reference is generated from the Spark schemas. It includes nested Choice targets and Iterate state.
Define A Module
defmodule MyApp.Flows.Greeting do
use Jido.Flow,
name: "greeting",
description: "Creates one greeting",
schema: Zoi.object(%{name: Zoi.string()}),
output_schema: Zoi.object(%{message: Zoi.string()})
flow do
step "greet", name <- input(:name), meta: %{owner: "communications"} do
{:ok, %{message: "Hello, " <> name <> "!"}}
end
output result("greet")
end
endThe DSL validates syntax, Flow structure, reference scope, graph cycles, and
target contracts during compilation. Compile errors use DSL source locations.
This inline form requires 3.0.0-beta.5 or later.
An inline body becomes an ordinary Action. The Flow owns the body, so it can call the module's private helpers. Headers use direct references or data; the body is normal Elixir and owns calculations. See Steps And Output for the full syntax.
Add Authoring Macros
Use a Flow extension when several Flow modules need the same declarative shorthand. An extension macro must expand to normal Flow declarations.
defmodule MyApp.Flows.Helpers do
use Jido.Flow.Extension
defmacro notify(name, address) do
quote do
step unquote(name),
action: MyApp.Actions.Notify,
params: %{address: unquote(address)}
end
end
endAdd the extension through a static module list:
defmodule MyApp.Flows.Welcome do
use Jido.Flow,
name: "welcome",
extensions: [MyApp.Flows.Helpers]
flow do
notify "welcome", input(:address)
output result("welcome")
end
endThe extension runs only during compilation. Its macros can expand to core declarations, including inline Action forms. Core lowering then applies the same validation, source mapping, canonical data, and execution rules.
An extension does not add a new component type or runtime. Put domain work in Actions or Flows. Keep runtime input in Flow input or context. The extension module must compile before each Flow that configures it.
Use Helpers With Other Authoring Forms
Extensions apply only to the compile-time module DSL. The extension module and
macro calls are not part of the canonical %Jido.Flow{} value.
For data authoring, use normal functions that return component maps or complete
Flow definitions. Validate the complete definition with Jido.Flow.new/1.
The module DSL loads compile-time extensions. Data definitions do not load
extensions or execute authoring macros. If an application owns another stored
format, translate it to data definitions or Registry-backed Codec documents.
Format The DSL
Add :jido_action to the import_deps list in your project's .formatter.exs.
Keep all existing formatter options and imported dependencies.
[
import_deps: [:jido_action],
inputs: ["{mix,.formatter}.exs", "{config,lib,test}/**/*.{ex,exs}"]
]The package exports locals_without_parens for Flow declarations and block
fields. Standard mix format then keeps forms such as step "greet", ...
and output result("greet"). No formatter plugin is required.
Reference calls such as input(:name), result("greet"), and state(:count)
keep their parentheses. The formatter also preserves explicit parentheses on
declarations. Remove those parentheses once if you want the form shown above.
Generated API
A Flow module exposes its definition, validation, metadata, and convenience functions:
MyApp.Flows.Greeting.name()
MyApp.Flows.Greeting.description()
MyApp.Flows.Greeting.schema()
MyApp.Flows.Greeting.output_schema()
MyApp.Flows.Greeting.validate_params(%{name: "Ada"})
MyApp.Flows.Greeting.validate_output(%{message: "Hello"})
MyApp.Flows.Greeting.flow()
MyApp.Flows.Greeting.compiled()
MyApp.Flows.Greeting.step_action("greet")
MyApp.Flows.Greeting.run(%{name: "Ada"}, %{})flow/0 returns the same canonical value for the life of the loaded module
version. Put changing values in input or context, not in module construction.
compiled/0 returns derived Jido.Flow.Compiled data. It includes a native
Runic workflow and the source map. It is not a storage format.
run/2 delegates to Jido.Exec.run/4 with default options. Use Jido.Exec
directly when you need runtime options. Exec uses the descriptor to select
native Flow execution; it does not call this convenience function.
Reuse A Step Target
step_action/1 returns the Action module for an inline or explicit
Action-backed Step. It accepts an atom or string name. Invalid or unknown
names and non-Step components, including Subflows, raise ArgumentError.
Lookup does not execute the body or create atoms.
The helper returns only the target. It does not copy the Step's parameters,
needs, or meta. Supply those fields for the new graph. Call the helper
after its Flow module has compiled, not from that module's unfinished flow
block. See data definitions reuse and
JSON storage.
Context bindings are also Step parameters. For example, ctx <- context()
puts the Flow context in the generated Action's :ctx parameter. If you call
that Action directly, supply :ctx in its input map. Passing only the Exec
context does not recreate the binding. Reuse through a new Step also needs an
explicit context reference in that Step's parameters.
The Step inline: settings also accept context: ctx, which binds actual
execution context without adding a parameter. step_action/1 stays Step-only.
Convert An Action To An Inline Step
Inline bodies reduce source code for small transformations. They do not infer
field types or defaults from bindings. Use Step inline: settings to declare
static input and output schemas, defaults, descriptions, and Action names.
The inline Action does not inherit the owning Flow's schemas or the validation
hooks of an Action that it replaces.
Tools and routers can read declared Action schemas. Binding names alone do not provide them. Keep a named Action for custom lifecycle hooks or a separate public module API. See Inline Actions.
The owning Flow still validates its input and final output. Those schemas do
not validate each intermediate Step result. Calling an extracted target with
step_action/1 also bypasses the owning Flow's validation and defaults. A
missing binding can then fail as a function-clause error during execution
unless the target's own schema rejects it or supplies a default first.
Explicit effect lists survive composition in explicit and inline Steps. Untagged success extras fail with migration guidance. See Results And Errors.
Source Metadata
The compiler stores file, line, and available column data in a source map
outside the canonical Flow value. Component meta remains portable author
data. This separation keeps direct, data definitions, DSL, and Codec values equal.
Inline body warnings and errors retain source locations. Runtime stacktraces include the body in its owning Flow module. Do not depend on the generated function or Action module names; they are internal.
Deploy Inline Steps
Normal source compilation writes the owner and generated Action BEAM files. Deploy them together in the same application build. Lookup, Flow inspection, Codec operations, and execution do not compile stored code.
The target identity depends on the owner module and the typed path
[host: Jido.Flow, step: name, role: :action], not the body.
A body-only edit can keep the same semantic Flow identity. That identity
describes graph data, not a code version or a durable code snapshot. Use an
application release version when you need to identify deployed behavior.
Use The Flow Facade
Inspection functions belong to Jido.Flow, not to each generated module.
flow = MyApp.Flows.Greeting.flow()
Jido.Flow.validate(flow)
Jido.Flow.dependencies(flow)
Jido.Flow.explain(flow)
Jido.Flow.semantic_identity(flow)