Jido.Executable behaviour (Jido Action v3.0.0-beta.12)

View Source

Defines the common executable contract for Jido Actions and Jido Flows.

An executable target is one of these values:

  • an Action module with __jido_executable__/0;
  • a Flow module with __jido_executable__/0; or
  • a Jido.Flow value.

Resolution returns the target kind and the exact target:

{:ok, %Jido.Executable{kind: :action, target: MyApp.SendEmail}} =
  Jido.Executable.resolve(MyApp.SendEmail)

resolve/1 keeps the exact target and returns one small descriptor. A module callback must identify the module that owns the callback.

This behaviour declares the module descriptor and data validation callbacks. Both Action and Flow module generators implement this behaviour. An Action also implements Jido.Action, which requires run/2. A Flow requires flow/0 instead. Its generated run/2 is a convenience call to Jido.Exec. validate/1 checks the required functions for each target kind at runtime; a behaviour declaration alone does not make a module executable.

A Flow module must return one stable %Jido.Flow{} from flow/0 for the life of the loaded module version. Each validation or execution operation materializes the value once.

Jido.Instruction stores one of these target values and resolves it through this module. The target kind selects the Action or Flow execution semantics.

Resolution failures use Jido.Action.Error.ConfigurationError because the resolver does not yet know the target kind. Action or Flow execution owns errors after resolution. This keeps one resolver and avoids a separate executable error model.

This module does not define a map or JSON format for executable targets.

Summary

Types

The executable kind.

t()

The resolved executable descriptor.

An Action module, a Flow module, or a runtime Flow value.

Callbacks

Validates normal output or an explicit output envelope.

Validates input parameters without running executable work.

Functions

Resolves an executable target.

Validates an executable descriptor or target.

Types

kind()

@type kind() :: :action | :flow

The executable kind.

t()

@type t() :: %Jido.Executable{kind: :action | :flow, target: any()}

The resolved executable descriptor.

target()

@type target() :: module() | Jido.Flow.t()

An Action module, a Flow module, or a runtime Flow value.

Callbacks

validate_output(arg1)

@callback validate_output(map() | Jido.Action.Output.t()) ::
  {:ok, map() | Jido.Action.Output.t()} | {:error, term()}

Validates normal output or an explicit output envelope.

validate_params(map)

@callback validate_params(map()) :: {:ok, map()} | {:error, term()}

Validates input parameters without running executable work.

Functions

resolve(flow)

@spec resolve(term()) ::
  {:ok, t()} | {:error, Jido.Action.Error.ConfigurationError.t()}

Resolves an executable target.

Action and Flow modules must return a valid descriptor from __jido_executable__/0. A loaded module without this callback is not an executable target.

validate(executable)

@spec validate(t() | target() | term()) :: :ok | {:error, Exception.t()}

Validates an executable descriptor or target.