# `AgentXM.Examples.TinyFlags`
[🔗](https://github.com/agentxm/polyglot-examples/blob/main/lib/agentxm_example_tinyflags.ex#L1)

Tiny feature flags library used by AXM companion package examples.

Flags are defined with `AgentXM.Examples.TinyFlags.BooleanFlag.new/1` or
`AgentXM.Examples.TinyFlags.VariantFlag.new/2` and evaluated through a
flag set built with `new/1`. Rollout decisions are deterministic for a
given `{flag_name, context_id}` pair so the same caller always sees the
same answer.

## Example

    flags =
      AgentXM.Examples.TinyFlags.new!(%{
        "checkout-redesign" =>
          AgentXM.Examples.TinyFlags.BooleanFlag.new!(default: true),
        "search-ranking" =>
          AgentXM.Examples.TinyFlags.VariantFlag.new!(
            ["classic", "semantic"],
            default: "classic",
            rollout: %{"semantic" => 100}
          )
      })

    AgentXM.Examples.TinyFlags.enabled?(flags, "checkout-redesign", %{id: "user-1"})
    # => true

    AgentXM.Examples.TinyFlags.variant(flags, "search-ranking", %{id: "user-1"})
    # => {:ok, "semantic"}

# `t`

```elixir
@type t() :: %AgentXM.Examples.TinyFlags{
  definitions: %{
    optional(String.t()) =>
      AgentXM.Examples.TinyFlags.BooleanFlag.t()
      | AgentXM.Examples.TinyFlags.VariantFlag.t()
  }
}
```

A flag set built with `new/1` or `new!/1`.

# `enabled`

```elixir
@spec enabled(t(), String.t(), AgentXM.Examples.TinyFlags.Context.t() | map()) ::
  {:ok, boolean()} | {:error, term()}
```

Return the boolean treatment for the named flag.

Returns `{:error, reason}` when the flag is unknown or is not a boolean flag.

# `enabled?`

```elixir
@spec enabled?(t(), String.t(), AgentXM.Examples.TinyFlags.Context.t() | map()) ::
  boolean()
```

Convenience wrapper that returns the boolean directly. Raises on error.

# `evaluate`

```elixir
@spec evaluate(t(), String.t(), AgentXM.Examples.TinyFlags.Context.t() | map()) ::
  {:ok, {:boolean, boolean()} | {:variant, String.t()}} | {:error, term()}
```

Evaluate a flag without knowing its kind ahead of time. Returns a
`{:boolean, bool}` or `{:variant, name}` tuple.

# `fetch`

```elixir
@spec fetch(t(), String.t()) ::
  {:ok,
   AgentXM.Examples.TinyFlags.BooleanFlag.t()
   | AgentXM.Examples.TinyFlags.VariantFlag.t()}
  | {:error, term()}
```

Return `{:ok, flag}` or `{:error, reason}` if the flag is unknown.

# `names`

```elixir
@spec names(t()) :: [String.t()]
```

Return the registered flag names in lexicographic order.

# `new`

```elixir
@spec new(map()) :: {:ok, t()} | {:error, term()}
```

Build a flag set from a map of flag name to definition.

Returns `{:error, reason}` if the map is invalid (nil, non-map, or contains a
blank flag name).

# `new!`

```elixir
@spec new!(map()) :: t()
```

Like `new/1` but raises `ArgumentError` on invalid input.

# `variant`

```elixir
@spec variant(t(), String.t(), AgentXM.Examples.TinyFlags.Context.t() | map()) ::
  {:ok, String.t()} | {:error, term()}
```

Return the named variant treatment for the named flag.

Returns `{:error, reason}` when the flag is unknown or is not a variant flag.

---

*Consult [api-reference.md](api-reference.md) for complete listing*