Getting Started
View SourceOverview
This Livebook introduces the three basic Jido values:
- an Action defines one validated unit of work;
- an Instruction describes one call; and
Jido.Execruns the call through the public error boundary.
Run the cells from top to bottom.
Install The Package
Mix.install([{:jido_action, "~> 3.0.0-beta.11"}])Define An Action
An Action receives validated parameters and a caller-owned context map. A normal successful result is a map.
defmodule GettingStarted.Add do
use Jido.Action,
name: "add",
description: "Adds two integers",
schema:
Zoi.object(%{
left: Zoi.integer(),
right: Zoi.integer()
}),
output_schema: Zoi.object(%{result: Zoi.integer()})
@impl true
def run(%{left: left, right: right}, _context) do
{:ok, %{result: left + right}}
end
endThe generated validation functions are useful in focused Action tests.
{:ok, params} = GettingStarted.Add.validate_params(%{left: 2, right: 3})
{:ok, %{result: 5}} = GettingStarted.Add.run(params, %{})Run Through Jido.Exec
Jido.Exec.run/4 validates input, isolates the callback, validates normal
output, and returns structured errors.
{:ok, %{result: 5}} =
Jido.Exec.run(
GettingStarted.Add,
%{left: 2, right: 3},
%{request_id: "req-1"}
)Invalid input does not call the Action.
{:error, %Jido.Action.Error.InvalidInputError{} = error} =
Jido.Exec.run(GettingStarted.Add, %{left: "2", right: 3})
Exception.message(error)Create An Instruction
An Instruction stores a target, parameters, context, and caller metadata. It does not run work.
instruction =
Jido.Instruction.new!(
target: GettingStarted.Add,
params: %{left: 10, right: 4},
context: %{request_id: "req-2"},
metadata: %{source: "example"}
)
{:ok, %{result: 14}} = Jido.Exec.run(instruction)Call-site parameters and context override keys in the Instruction.
{:ok, %{result: 16}} =
Jido.Exec.run(instruction, %{right: 6}, %{request_id: "req-3"})Next
Continue with Build Your First Flow to compose Actions as data.