References And Data

View Source

Overview

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"}
  )

output

Global References

DSL helperCanonical sourceReads
input(path):inputValidated Flow input.
context(path):contextCaller context.
result(name, path):resultNamed component output.
select(ref, path)same as sourceA 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.

ScopeHelpers
Map paramsitem, item_index, item_id
Reduce paramsitem, item_index, item_id, accumulator
Iterate paramsstate, iteration_index
Iterate State updatestate, iteration_index, body_result
Iterate completionstate, 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.