Trogon.Error.Metadata (Trogon.Error v0.4.0)
View SourceA structured container for error metadata with support for visibility controls.
This module provides a wrapper around metadata entries, where each entry
is a MetadataValue
struct containing both the value and its visibility level.
Implements the Access
behavior for convenient map-like access to metadata entries.
Examples
iex> metadata = Trogon.Error.Metadata.new(%{"user_id" => "123", "action" => "login"})
iex> metadata["user_id"].value
"123"
iex> metadata["user_id"].visibility
:INTERNAL
Summary
Functions
Fetches a metadata value by key.
Gets and updates a metadata entry.
Guard that checks if metadata is empty (has no entries).
Merges two Metadata structs, with the second taking precedence for duplicate keys.
Creates a new empty Metadata struct.
Creates a new Metadata struct from a map of entries.
Pops a metadata entry by key.
Types
@type t() :: %Trogon.Error.Metadata{ entries: %{required(String.t()) => Trogon.Error.MetadataValue.t()} }
Functions
Fetches a metadata value by key.
Examples
iex> metadata = Trogon.Error.Metadata.new(%{"user_id" => "123"})
iex> Trogon.Error.Metadata.fetch(metadata, "user_id")
{:ok, %Trogon.Error.MetadataValue{value: "123", visibility: :INTERNAL}}
iex> metadata = Trogon.Error.Metadata.new(%{})
iex> Trogon.Error.Metadata.fetch(metadata, "missing")
:error
Gets and updates a metadata entry.
Examples
iex> metadata = Trogon.Error.Metadata.new(%{"count" => "1"})
iex> {old_value, new_metadata} = Trogon.Error.Metadata.get_and_update(metadata, "count", fn old ->
...> new_value = %Trogon.Error.MetadataValue{value: "2", visibility: :internal}
...> {old, new_value}
...> end)
iex> old_value.value
"1"
iex> new_metadata["count"].value
"2"
Guard that checks if metadata is empty (has no entries).
Examples
iex> import Trogon.Error.Metadata, only: [is_empty_metadata: 1]
iex> empty = Trogon.Error.Metadata.new()
iex> is_empty_metadata(empty)
true
iex> import Trogon.Error.Metadata, only: [is_empty_metadata: 1]
iex> with_data = Trogon.Error.Metadata.new(%{"key" => "value"})
iex> is_empty_metadata(with_data)
false
Merges two Metadata structs, with the second taking precedence for duplicate keys.
Examples
iex> metadata1 = Trogon.Error.Metadata.new(%{"user_id" => "123", "action" => "login"})
iex> metadata2 = Trogon.Error.Metadata.new(%{"user_id" => "456", "session" => "abc"})
iex> merged = Trogon.Error.Metadata.merge(metadata1, metadata2)
iex> merged["user_id"].value
"456"
iex> map_size(merged.entries)
3
@spec new() :: t()
Creates a new empty Metadata struct.
Examples
iex> Trogon.Error.Metadata.new()
%Trogon.Error.Metadata{entries: %{}}
@spec new(%{ required(term()) => Trogon.Error.MetadataValue.t() | {term(), Trogon.Error.MetadataValue.visibility()} | term() }) :: t()
Creates a new Metadata struct from a map of entries.
Accepts various formats for metadata values:
- Simple values (converted to MetadataValue with :internal visibility)
- Tuples with explicit visibility:
{value, visibility}
- Pre-existing MetadataValue structs
Examples
iex> metadata = Trogon.Error.Metadata.new(%{"user_id" => "123", "secret" => {"api-key", :PRIVATE}})
iex> metadata["user_id"].visibility
:INTERNAL
iex> metadata["secret"].visibility
:PRIVATE
Pops a metadata entry by key.
Examples
iex> metadata = Trogon.Error.Metadata.new(%{"user_id" => "123", "action" => "login"})
iex> {value, new_metadata} = Trogon.Error.Metadata.pop(metadata, "user_id")
iex> value.value
"123"
iex> map_size(new_metadata.entries)
1