@spec cond_log(Logger.level(), Logger.level(), Logger.message(), keyword()) :: :ok

Conditionally logs a message based on comparing threshold and message log levels.

This function provides a way to conditionally log messages by comparing a threshold level against the message's intended log level. The message will only be logged if the threshold level is less than or equal to the message level.

Parameters

• threshold_level: The minimum log level threshold (e.g. :debug, :info, etc)
• message_level: The log level for this specific message
• message: The message to potentially log
• opts: Additional options passed to Logger.log/3

Returns

• :ok in all cases

Examples

# Will log since :info >= :info
iex> cond_log(:info, :info, "test message")
:ok

# Won't log since :info > :debug
iex> cond_log(:info, :debug, "test message")
:ok

# Will log since :debug <= :info
iex> cond_log(:debug, :info, "test message")
:ok

@spec convert_nested_opt({atom(), any()}) :: {atom(), any()}

Converts nested keyword lists to maps for specific option keys.

Used during Action configuration to convert nested keyword lists (e.g., compensation) into maps for Zoi validation.

Examples

iex> convert_nested_opt({:compensation, [enabled: true, max_retries: 3]})
{:compensation, %{enabled: true, max_retries: 3}}

iex> convert_nested_opt({:name, "my_action"})
{:name, "my_action"}

@spec default_log_level() :: Logger.level()

Returns the default execution log threshold for Jido.

This reads :jido_action, :default_log_level and falls back to :info when the config value is missing or invalid.

@spec normalize_result(any()) :: {:ok, any()} | {:error, any()}

Normalizes nested result tuples to single-level tuples.

This function handles cases where callbacks or functions return nested tuples like {:ok, {:ok, value}} or {:error, {:error, reason}}, flattening them to proper single-level result tuples.

Examples

iex> normalize_result({:ok, {:ok, "value"}})
{:ok, "value"}

iex> normalize_result({:ok, {:error, "reason"}})
{:error, "reason"}

iex> normalize_result({:ok, "value"})
{:ok, "value"}

iex> normalize_result("value")
{:ok, "value"}

@spec resolve_log_level(keyword()) :: Logger.level()

Resolves the execution log threshold for a call.

Precedence:

1. opts[:log_level]
2. config :jido_action, default_log_level: ...
3. built-in :info

@spec validate_name(
  any(),
  keyword()
) :: :ok | {:error, String.t()}

Validates the name of a Action.

The name must contain only letters, numbers, and underscores.

Parameters

• name: The name to validate.

Returns

• :ok if the name is valid.
• {:error, reason} if the name is invalid.

Examples

iex> Jido.Action.validate_name("valid_name_123")
:ok

iex> Jido.Action.validate_name("invalid-name")
{:error, "The name must contain only letters, numbers, and underscores."}

@spec wrap_error(any()) :: {:error, any()}

Wraps value in error tuple.

Examples

iex> wrap_error({:error, "reason"})
{:error, "reason"}

iex> wrap_error("reason")
{:error, "reason"}

@spec wrap_ok(any()) :: {:ok, any()} | {:error, any()}

Wraps value in success tuple if not already a result tuple.

Examples

iex> wrap_ok({:ok, "value"})
{:ok, "value"}

iex> wrap_ok({:error, "reason"})
{:error, "reason"}

iex> wrap_ok("value")
{:ok, "value"}