Trogon.Error.Metadata (Trogon.Error v0.3.1)

View Source

A 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

t()

@type t() :: %Trogon.Error.Metadata{
  entries: %{required(String.t()) => Trogon.Error.MetadataValue.t()}
}

Functions

fetch(metadata, key)

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

get_and_update(metadata, key, fun)

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"

is_empty_metadata(metadata)

(macro)

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

merge(metadata1, metadata2)

@spec merge(t(), t()) :: t()

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

new()

@spec new() :: t()

Creates a new empty Metadata struct.

Examples

iex> Trogon.Error.Metadata.new()
%Trogon.Error.Metadata{entries: %{}}

new(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

pop(metadata, key)

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