References And Data
View SourceOverview
A Jido.Flow.Ref reads data when a Flow executes. References are also the
source of inferred graph dependencies.
Run the cells from top to bottom.
Install The Package
Mix.install([{:jido_action, "~> 3.0.0-beta.11"}])Define An Action And Flow
defmodule FlowReferences.Echo do
use Jido.Action, name: "flow_references_echo"
@impl true
def run(params, _context), do: {:ok, params}
end
defmodule FlowReferences.Example do
use Jido.Flow, name: "flow_references_example"
flow do
step "profile",
action: FlowReferences.Echo,
params: %{
user: input([:request, :user]),
actor_id: context(:actor_id),
literal: value("profile")
}
step "summary",
action: FlowReferences.Echo,
params: %{
name: result("profile", [:user, :name]),
actor_id: select(result("profile"), [:actor_id])
}
output(%{summary: result("summary")})
end
end{:ok, output} =
Jido.Exec.run(
FlowReferences.Example,
%{request: %{user: %{name: "Ada"}}},
%{actor_id: "user-1"}
)
outputGlobal References
| DSL helper | Canonical source | Reads |
|---|---|---|
input(path) | :input | Validated Flow input. |
context(path) | :context | Caller context. |
result(name, path) | :result | Named component output. |
select(ref, path) | same as source | A deeper path on a reference. |
A path can be one atom, string, non-negative integer, or a list of these
segments. String segments must contain valid UTF-8. A path list must be proper
and must not contain nil. Constructors, data definitions, the DSL, and Codec reject
invalid paths before execution. An empty path selects the complete source
value. The nil path argument is also an empty path; it is different from
[nil], which is invalid.
A valid path can select a present nil value. Missing keys and invalid list
indexes return structured execution errors.
Jido.Flow.Ref.select/2 validates its source reference before it appends a path.
An invalid source raises Jido.Flow.Error.InvalidDefinitionError. The next
component or Flow constructor validates the complete selected path.
A result reference creates an inferred dependency on the named component. Input and context references do not.
References can appear inside Jido.Expr operations. Their scopes and graph
dependencies do not change. See
Expressions
for the
new calculation syntax and its version requirement.
Local References
Local helpers are valid only in their component scope.
| Scope | Helpers |
|---|---|
| Map params | item, item_index, item_id |
| Reduce params | item, item_index, item_id, accumulator |
| Iterate params | state, iteration_index |
| Iterate State update | state, iteration_index, body_result |
| Iterate completion | state, iteration_index |
The validator rejects a local reference outside its scope. This keeps the data grammar explicit before execution.
Portable Literals
Flow literals are nil, Boolean values, numbers, strings, and registered
atoms. Lists must be proper lists. Use maps, not keyword lists. Stored JSON
uses a trusted Registry for atoms and atom map keys.
An empty list is valid data: use [] directly, including in nested values
such as %{items: []} or a condition such as input(:items) == [].
value([]) has the same meaning. This does not make a bare list a valid normal
Flow output, Reduce accumulator, or Iterate State. Use a map such as
%{items: []} for those values. The existing explicit Jido.Action.Output
forms for Flow output and Reduce accumulators remain available.