Jido. Flow
(Jido Action v3.0.0-beta.12)
View Source
Defines the canonical Jido Flow data artifact and compile-time module DSL.
A Flow contains named canonical components and one required output
expression. Execution is delegated through Jido.Exec.
Flow has three supported authoring inputs:
- the compile-time Flow module DSL;
- map-based data definitions through
new/1and component constructors; and - versioned stored JSON documents through
Jido.Flow.Codec.
Use the Flow module DSL as the primary developer authoring surface:
defmodule MyApp.ProcessOrder do
use Jido.Flow, name: "process_order"
flow do
step "load",
action: MyApp.LoadOrder,
params: %{id: input(:id)}
step "save",
action: MyApp.SaveOrder,
params: %{order: result("load")}
output result("save")
end
endA compile-time extension can add macros that expand to normal Flow declarations. Configure extensions as a static module list:
use Jido.Flow,
name: "process_order",
extensions: [MyApp.Flows.Helpers]Define each extension with Jido.Flow.Extension. Extensions change only
module DSL source authoring. Data definitions and Codec do not load
extensions. The compiled result remains one canonical Flow value.
For a small operation, bind data and write an inline Step body:
defmodule MyApp.Greeting do
use Jido.Flow, name: "greeting"
flow do
step "greet", name <- input(:name) do
{:ok, %{message: "Hello, " <> name <> "!"}}
end
output result("greet")
end
endEvery Flow authoring form requires an explicit, non-nil output. In the
module DSL, it must be the final declaration.
A binding source accepts direct Flow references or data, but not Flow
operations. The body is normal Elixir in the owning module's function scope.
Put calculations in that body. Use ctx <- context() to bind context as a
parameter. Use a binding list for two or more inputs, a sole map pattern
for complete params, or [] for no input. Use one binding argument. Put
pattern selection in a case expression inside the body; top-level clause
bodies are not supported.
Use inline: to set the Action name, description, schemas, or
context: ctx. Keep needs: and meta: at the Step level. Flow supports
inline Actions only for Step. Map, Reduce, Choice targets, Iterate, and
Dispatch use Action modules. All targets use normal Exec validation
and result rules. See Inline Actions.
After the owner compiles, MyApp.Greeting.step_action("greet") returns its
Action target for map-based definitions, direct construction, or trusted Registry reuse.
It does not copy parameters, dependencies, or metadata. Map-based definitions and stored
JSON do not accept body code, anonymous functions, or MFA targets.
step_action/1 stays Step-only, including explicit Action-backed Steps but
excluding Subflows. context: ctx binds the current callback context; it
does not retain the original Flow context in the target's parameters.
Deploy the owning module and generated Action BEAM files together. A body edit can retain the same target and semantic graph identity; graph identity does not identify a deployed code version.
Result references create data dependencies. needs: keeps only explicit
author control order. Source order does not create a dependency. The Spark
compiler keeps source locations outside the canonical Flow value.
Use Jido.Flow.Codec.encode/2 and Jido.Flow.Codec.decode/2 with a trusted
Jido.Flow.Registry for database or transport storage.
A Flow module returns one stable canonical value from flow/0 for the life
of the loaded module version. Each validation, compilation, or execution
operation materializes it once. Put changing runtime data in Flow input or
context.
Flow modules implement Jido.Executable and provide their definition through
flow/0. The generated run/2 delegates to Jido.Exec with default options.
A Choice is one Flow component. It evaluates data-only conditions in authored order, runs the first matching target, and uses a required routing fallback when no option matches.
Flow collects the optional effect list from every successful executed component and returns it with its final output. The third success element must be a proper list. Failed execution returns no effect list. Effect order uses canonical dependency order, then component name. Nested Flows occupy their parent position; collections use input or iteration order.
DSL field reference
These fields describe the module DSL, not the direct constructor or stored JSON. Positional arguments are identified below. Choice and Iterate require field blocks; their nested declarations have their own references. Only Step supports inline Action bodies. The field types, required flags, and defaults come from the Spark schemas; Jido also validates graph and cross-field rules.
Step
Declares one Action call, or a Subflow when the target is a Flow module.
These fields describe module-backed Steps, in keyword or field-block form.
Direct inline bodies use bindings instead of action and params; put
Action settings in inline: and keep needs and meta at Step level.
See Steps And Output and Inline Actions.
:name(String.t/0) - Required. The unique Step name. Pass it first.:action(atom/0) - Required. The Action or Flow module to call.:params(a quoted value) - Required. An expression that supplies the target parameters.:needs(one or a list ofString.t/0) - Explicit control dependencies. The default value is[].:meta(map/0) - Non-semantic node metadata. The default value is%{}.
Choice
Declares ordered options and exactly one otherwise fallback in a block.
Result references in all targets create dependencies, even in unselected
options. See Choices And Conditions.
:name(String.t/0) - Required. The unique component name. Pass it first.:needs(one or a list ofString.t/0) - Explicit control dependencies. The default value is[].:meta(map/0) - Non-semantic node metadata. The default value is%{}.
Option
Declares one named Choice option, in keyword or field-block form. Only the first matching option runs.
:name(String.t/0) - Required. The unique option name within this Choice. Pass it first.:action(atom/0) - Required. The Action module to call when this option matches.:params(a quoted value) - Required. An expression that supplies the selected Action parameters.:condition(a quoted value) - Required. A Boolean Flow expression, tested in option declaration order.
Otherwise
Declares the required unnamed fallback, in keyword or field-block form. It runs when no option matches, not when a selected Action fails.
:action(atom/0) - Required. The Action module to call when no option matches.:params(a quoted value) - Required. An expression that supplies the fallback parameters.
Map
Runs one Action for each collection item, preserving input order. Use keyword or field-block form. See Map And Reduce.
:name(String.t/0) - Required. The unique component name. Pass it as the first positional argument.:collection(a quoted value) - Required. An expression that resolves to the list of items to process.:action(atom/0) - Required. The Action module to call for each item. Inline bodies are not supported.:params(a quoted value) - Required. The parameter expression for each call. Useitem()to read the current item.:on_error- Stop on an item error, or return a success or error record for each item in input order. Valid values are :fail_fast, :collect_errors The default value is:fail_fast.:needs(one or a list ofString.t/0) - Explicit control dependencies. The default value is[].:meta(map/0) - Non-semantic node metadata. The default value is%{}.
Reduce
Folds a list serially through one Action, in keyword or field-block form. An empty list returns the initial accumulator. See Map And Reduce.
:name(String.t/0) - Required. The unique component name. Pass it first.:collection(a quoted value) - Required. An expression that resolves to the list to fold.:initial(a quoted value) - Required. The initial accumulator expression.:action(atom/0) - Required. The Action module to call for each item. Its result becomes the next accumulator.:params(a quoted value) - Required. The call parameter expression. Useitem()andaccumulator()for local values.:needs(one or a list ofString.t/0) - Explicit control dependencies. The default value is[].:meta(map/0) - Non-semantic node metadata. The default value is%{}.
Iterate
Declares one required state and an Action body in a field block.
Choose exactly one termination form: repeat, without max_iterations,
or while with max_iterations. The condition is checked before each call;
if it remains true at the bound, execution fails.
See Iterate And State.
:name(String.t/0) - Required. The unique component name. Pass it first.:action(atom/0) - Required. The Action module for the loop body. Flow targets and inline bodies are not supported.:params(a quoted value) - Required. The body parameter expression. Usestate()anditeration_index()for local values.:update(a quoted value) - The replacement State expression after each successful call. If omitted, Jido uses the completebody_result()instead.:while(a quoted value) - A Boolean head condition. Requiresmax_iterations; cannot be combined withrepeat.:repeat(pos_integer/0) - A fixed count from 1 through 10,000. Cannot be combined withwhileormax_iterations.:max_iterations(pos_integer/0) - The bound from 1 through 10,000 for awhileloop. Required withwhileand forbidden withrepeat.:needs(one or a list ofString.t/0) - Explicit control dependencies. The default value is[].:meta(map/0) - Non-semantic node metadata. The default value is%{}.
State
Declares the required Iterate state, in keyword or field-block form. The schema validates the initial value and every replacement. State is replaced, not merged.
:schema(term/0) - Required. The static State schema, or[]. Pass it first.:initial(a quoted value) - Required. An expression that supplies the initial State.
Dispatch
Declares a decision Action and an expander Action, in keyword or field-block form. Only one Dispatch is allowed. It must be the sole terminal node in the dependency graph, regardless of declaration order. Flow output must be its complete result. See Dynamic Flows.
:name(String.t/0) - Required. The unique component name. Pass it first.:decision(atom/0) - Required. The Action module that receives the Dispatch parameters and returns a decision map.:expander(atom/0) - Required. The Action module that receives the complete decision map. It can return a final result or a continuation.:params(a quoted value) - Required. An expression that supplies the decision Action parameters.:needs(one or a list ofString.t/0) - Explicit control dependencies. The default value is[].:meta(map/0) - Non-semantic node metadata. The default value is%{}.
Output
Declares the required, non-nil Flow output. Pass the value as the only argument; there is no field-block form. Output must be the final declaration. See Steps And Output.
:value(a quoted value) - Required. The Flow result expression. Pass it directly tooutput, not as a keyword field.
Summary
Functions
Compiles a validated Flow to one native Runic workflow.
Compiles a Flow or raises the compilation error.
Returns explicit, reference, and effective dependencies for each component.
Returns the versioned canonical inspection data for a Flow.
Builds and validates one canonical Flow value from a data definition.
Builds one canonical Flow value or raises its validation error.
Returns the deterministic SHA-256 and UUIDv8 identity for a Flow.
Converts a Flow artifact to its deterministic semantic map.
Validates and normalizes the canonical Flow structure.
Validates a canonical Flow and all Action or nested-Flow target contracts.
Types
Functions
@spec compile(t(), keyword() | Jido.Flow.Compiled.source_map()) :: {:ok, Jido.Flow.Compiled.t()} | {:error, Exception.t()}
Compiles a validated Flow to one native Runic workflow.
The returned value contains derived runtime data. It is not an authoring or
storage format. Use Jido.Flow.Codec to store a Flow.
Pass a source map directly, or pass source_map: source_map. source_map
is the only compile option. Unknown options and malformed source locations
return a validation error.
@spec compile!(t(), keyword() | Jido.Flow.Compiled.source_map()) :: Jido.Flow.Compiled.t() | no_return()
Compiles a Flow or raises the compilation error.
@spec dependencies(t()) :: {:ok, %{required(String.t()) => dependency_info()}} | {:error, Jido.Flow.Error.InvalidDefinitionError.t()}
Returns explicit, reference, and effective dependencies for each component.
@spec explain(t()) :: {:ok, map()} | {:error, Jido.Flow.Error.InvalidDefinitionError.t()}
Returns the versioned canonical inspection data for a Flow.
@spec new(map() | keyword() | t()) :: {:ok, t()} | {:error, Exception.t()}
Builds and validates one canonical Flow value from a data definition.
Components accept tagged maps with a kind of :step, :subflow, :choice,
:map, :reduce, :iterate, or :dispatch, or canonical component structs.
Each map uses the corresponding component constructor. Data definitions use
explicit :step/action and :subflow/flow fields. Validation is inert.
Builds one canonical Flow value or raises its validation error.
@spec semantic_identity(t()) :: {:ok, map()} | {:error, Jido.Flow.Error.InvalidDefinitionError.t()}
Returns the deterministic SHA-256 and UUIDv8 identity for a Flow.
Converts a Flow artifact to its deterministic semantic map.
Component order in this view is author declaration order. Use
Jido.Flow.Codec for database storage.
@spec validate(t()) :: {:ok, t()} | {:error, Exception.t()}
Validates and normalizes the canonical Flow structure.
This function checks schemas, components, expressions, references, dependencies,
and graph cycles. It is inert: it does not load or check Action targets. Use
validate_executable/1 when the Flow must be ready for execution.
@spec validate_executable(t()) :: {:ok, t()} | {:error, Exception.t()}
Validates a canonical Flow and all Action or nested-Flow target contracts.
This function performs no Action work. It returns the normalized Flow when both canonical structure and executable target contracts are valid.