Getting Started

View Source

Overview

This Livebook introduces the three basic Jido values:

  1. an Action defines one validated unit of work;
  2. an Instruction describes one call; and
  3. Jido.Exec runs 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
end

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