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

end

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

effect_result()

@type effect_result() :: {:ok, map() | Jido.Action.Output.t(), effects()}

A successful output with optional deferred effect requests.

effects()

@type effects() :: [term()]

An ordered list of opaque effect requests. Exec does not dispatch them.

result()

@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.

schema()

@type schema() :: Zoi.schema() | []

A static Action input or output schema.

Callbacks

on_before_validate_params(params)

(optional)
@callback on_before_validate_params(params :: map()) :: {:ok, map()} | {:error, term()}

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.

run(params, context)

@callback run(params :: map(), context :: map()) :: result()

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} where result is a map or a Jido.Action.Output value.
  • {:ok, result, effects} where effects is 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} where reason describes 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

__using__(opts_ast)

(macro)

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