Jido. Action behaviour
(Jido Action v3.0.0-beta.12)
View Source
Defines one named, validated unit of work.
Use Jido.Action in a module, declare static input and output schemas, and
implement run/2:
defmodule MyAction do
use Jido.Action,
name: "my_action",
description: "Performs my action",
schema: Zoi.object(%{input: Zoi.string()}),
output_schema: Zoi.object(%{result: Zoi.string()})
@impl true
def run(params, _context) do
# Your action logic here
{:ok, %{result: String.upcase(params.input)}}
endend
Validation and execution
The generated validate_params/1 and validate_output/1 functions apply the
declared schemas. An Action can implement on_before_validate_params/1 to
prepare raw input before its schema runs. Object schemas are open: declared
fields are validated and unknown fields stay in the returned map.
A direct callback call does not add validation. Validate both boundaries
explicitly when you call run/2 yourself:
{:ok, params} = MyAction.validate_params(%{input: "hello"})
{:ok, result} = MyAction.run(params, %{})
{:ok, result} = MyAction.validate_output(result)Use Jido.Exec.run/4 when you want the public validation and error boundary.
It validates input, calls the Action, validates normal output, and normalizes
failures.
Every Action must implement run/2. A missing implementation stops compilation.
Effects and policy
run/2 can be pure or can perform I/O. Keep one Action focused on one unit
of work. The caller selects retry, timeout, scheduling, cancellation, and
persistence policy. Return an optional effect list with {:ok, output, requests};
Exec carries the requests without dispatch. Jido.Exec enforces a requested execution timeout and
owns process cleanup. It does not retry an Action automatically.
Summary
Types
A successful output with optional deferred effect requests.
An ordered list of opaque effect requests. Exec does not dispatch them.
A supported Action callback result.
A static Action input or output schema.
Callbacks
Prepares raw input parameters before schema validation.
Executes the Action with the given parameters and context.
Functions
Defines a new Action module.
Types
@type effect_result() :: {:ok, map() | Jido.Action.Output.t(), effects()}
A successful output with optional deferred effect requests.
@type effects() :: [term()]
An ordered list of opaque effect requests. Exec does not dispatch them.
@type result() :: effect_result() | {:ok, map() | Jido.Action.Output.t()} | {:continue, map(), Jido.Executable.target()} | {:error, term()} | {:error, term(), effects()}
A supported Action callback result.
@type schema() :: Zoi.schema() | []
A static Action input or output schema.
Callbacks
Prepares raw input parameters before schema validation.
Use this callback only for deterministic input preparation that must happen before Zoi can parse the value. Prefer Zoi coercion, defaults, enums, and refinements when they can express the required rule.
Executes the Action with the given parameters and context.
This callback must be implemented by modules using Jido.Action.
Parameters
params: A map of validated input parameters.context: A map that contains caller-owned execution data.
Returns
{:ok, result}whereresultis a map or aJido.Action.Outputvalue.{:ok, result, effects}whereeffectsis a proper list of effect requests.{:continue, continuation_input, continuation_target}where the current executable ends and the target becomes the next executable.{:error, reason}wherereasondescribes why the Action failed.{:error, reason, effects}is accepted, but Exec discards the effects.
Effects are optional for both maps and Output values. An empty list returns the two-element success form. Exec carries each request as opaque data and never dispatches it. Flow collects requests from every successful executed component in canonical dependency order, then component name. Nested Flows use their parent position; collections use input or iteration order. Failed execution or output validation returns no effect list.
The third success element is reserved for effect requests. Put metadata in
the result map or in Jido.Action.Output metadata. A value that is not a
proper list fails with :invalid_effects in direct and Flow execution.
A continuation does not resume this Action. Its input must be a map, not a
Jido.Action.Output envelope. Put an output envelope in a map field when the
next executable must receive it. The target must be an Action module, Flow
module, or Jido.Flow value. The final executable owns output validation,
errors, and its own effects.
Functions
Defines a new Action module.
This macro sets up the necessary structure and callbacks for an Action, including configuration validation and default implementations.
Options
name(required) - The non-blank metadata name of the Action.description(optional) - A description of what the Action does.schema(optional, default:[]) - A Zoi schema for Action input.output_schema(optional, default:[]) - A Zoi schema for Action output.
Schemas must be static module data. Use named MFA tuples for Zoi refinements, transforms, and other effects. Anonymous functions and lazy schemas are not supported because they can change the schema after compile-time validation.
Examples
defmodule MyAction do
use Jido.Action,
name: "my_action",
description: "Performs a specific task",
schema:
Zoi.object(%{
input:
Zoi.string()
|> Zoi.refine({__MODULE__, :not_blank, []})
})
def not_blank(value, _opts) do
if String.trim(value) == "", do: {:error, "cannot be blank"}, else: :ok
end
@impl true
def run(params, _context) do
{:ok, %{result: String.upcase(params.input)}}
end
end