Estructura type scaffold for creating enumerated types with a limited set of valid values.

This module provides a way to create custom types that can only contain predetermined values, similar to enums in other languages.

Usage

There are two ways to use this type scaffold:

1. Using the module directly

iex> require Estructura.Nested.Type.Enum
...> Estructura.Nested.Type.Enum.type_module_ast(Status, [:pending, :active, :completed])
...> apply(Status, :validate, [:pending])
{:ok, :pending}
iex> apply(Status, :validate, [:invalid])
{:error, "Expected :invalid to be one of: [:pending, :active, :completed]"}

2. Using the use macro

iex> defmodule Role do
...>   use Estructura.Nested.Type.Enum, elements: [:admin, :user, :guest]
...> end
...> Role.validate(:admin)
{:ok, :admin}

Configuration Options

The scaffold accepts the following options:

• :elements - (required) List of valid values for the enum
• :coercer - (optional) Function to coerce input values
• :encoder - (optional) Function to encode values for JSON

Example with Custom Coercion

defmodule Status do
  use Estructura.Nested.Type.Enum,
    elements: [:pending, :active, :completed],
    coercer: fn
      str when is_binary(str) -> {:ok, String.to_existing_atom(str)}
      atom when is_atom(atom) -> {:ok, atom}
      other -> {:error, "Cannot coerce #{inspect(other)} to status"}
    end
end

Example with Custom JSON Encoding

defmodule Role do
  use Estructura.Nested.Type.Enum,
    elements: [:admin, :user, :guest],
    encoder: fn role, opts -> Jason.Encode.string(Atom.to_string(role), opts) end
end

Generated Functions

The scaffold implements the Estructura.Nested.Type behaviour and provides:

• generate/1 - Generates random values from the enum for testing
• coerce/1 - Attempts to convert input into a valid enum value
• validate/1 - Ensures a value is part of the enum

Generation Options

The generate/1 function accepts:

• :only - List of elements to generate from (default: all elements)
• :except - List of elements to exclude from generation

Role.generate(only: [:admin, :user]) |> Enum.take(1) |> List.first()
#⇒ :admin # or :user

Role.generate(except: [:guest]) |> Enum.take(1) |> List.first()
#⇒ :admin # or :user