View Source SwarmEx.Utils (SwarmEx v0.1.0)

Utility functions for SwarmEx operations. Provides helper functions for common operations across the library.

Summary

Functions

Deep merges two maps recursively. If the same key exists in both maps and both values are maps, they are merged recursively. Otherwise, the value from the second map takes precedence.

Deserializes a string back into a term.

Formats an error tuple into a standardized error structure.

Generates a unique identifier with an optional prefix.

Logs a message with additional context and metadata. Ensures consistent log formatting across the application.

Safely executes a function with timeout and retry logic.

Serializes a term into a string representation.

Validates a map against a schema of required and optional keys.

Types

@type retry_opts() :: [
  timeout: non_neg_integer(),
  retries: non_neg_integer(),
  backoff_base: non_neg_integer(),
  backoff_type: :exponential | :linear
]

Functions

@spec deep_merge(map(), map()) :: map()

Deep merges two maps recursively. If the same key exists in both maps and both values are maps, they are merged recursively. Otherwise, the value from the second map takes precedence.

Examples

iex> deep_merge(%{a: 1, b: %{c: 2}}, %{b: %{d: 3}, e: 4})
%{a: 1, b: %{c: 2, d: 3}, e: 4}

iex> deep_merge(%{a: %{b: 1}}, %{a: 2})
%{a: 2}
@spec deserialize(String.t()) :: {:ok, term()} | {:error, term()}

Deserializes a string back into a term.

Examples

iex> deserialize("{":name":"John",":age":30}")
{:ok, %{name: "John", age: 30}}

iex> deserialize("invalid json")
{:error, :invalid_json}
@spec format_error(term()) :: SwarmEx.Error.AgentError.t()

Formats an error tuple into a standardized error structure.

Examples

iex> format_error({:error, "Something went wrong"})
%SwarmEx.Error.AgentError{message: "Something went wrong", reason: :unknown}

iex> format_error(%RuntimeError{message: "Oops"})
%SwarmEx.Error.AgentError{message: "Oops", reason: :runtime_error}
Link to this function

generate_id(prefix \\ nil)

View Source
@spec generate_id(String.t() | nil) :: String.t()

Generates a unique identifier with an optional prefix.

Examples

iex> generate_id()
"c1dd6960-7b91-4ca1-b853-c01c7f24d1aa"

iex> generate_id("user")
"user_c1dd6960-7b91-4ca1-b853-c01c7f24d1aa"
Link to this function

log(level, message, metadata \\ [])

View Source
@spec log(atom(), String.t(), keyword()) :: :ok

Logs a message with additional context and metadata. Ensures consistent log formatting across the application.

Examples

iex> log(:info, "Processing message", agent_id: "123")
:ok

iex> log(:error, "Failed to process", [error: "timeout", agent_id: "123"])
:ok
Link to this function

safely_execute(fun, opts \\ [])

View Source
@spec safely_execute(function(), retry_opts()) :: {:ok, term()} | {:error, term()}

Safely executes a function with timeout and retry logic.

Options

  • :timeout - Maximum time in milliseconds to wait for each attempt (default: 5000)
  • :retries - Number of retry attempts (default: 3)
  • :backoff_base - Base time in milliseconds for backoff calculation (default: 100)
  • :backoff_type - Type of backoff, either :exponential or :linear (default: :exponential)

Examples

iex> safely_execute(fn -> {:ok, :success} end)
{:ok, :success}

iex> safely_execute(fn -> raise "error" end)
{:error, %RuntimeError{message: "error"}}
@spec serialize(term()) :: {:ok, String.t()} | {:error, term()}

Serializes a term into a string representation.

Examples

iex> serialize(%{name: "John", age: 30})
{:ok, "{":name":"John",":age":30}"}

iex> serialize(%{invalid: make_ref()})
{:error, :unserializable_term}
Link to this function

validate_schema(map, schema)

View Source
@spec validate_schema(
  map(),
  keyword()
) :: :ok | {:error, term()}

Validates a map against a schema of required and optional keys.

Examples

iex> schema = [required: [:name, :age], optional: [:email]]
iex> validate_schema(%{name: "John", age: 30}, schema)
:ok

iex> validate_schema(%{name: "John"}, [required: [:name, :age]])
{:error, {:missing_required_keys, [:age]}}