Estructura    Kantox ❤ OSS  Test  Dialyzer

View Source

Extensions for Elixir structures.

Installation

def deps do
  [
    {:estructura, "~> 0.1"},
    # optionally you might want to add `boundary` library 
    # it is used by `estructura` and many other projects
    # more info: https://hexdocs.pm/boundary
    {:boundary, "~> 0.9", runtime: false}
  ]
end

I suggest adding boundary as a dependency since that is used in this project.

Features

Nested Structures

Estructura.Nested provides powerful nested structure support with validation, coercion, and generation capabilities:

defmodule User do
  use Estructura.Nested

  defstruct [
    name: "",
    address: %{
      city: "",
      street: %{name: "", house: 0}
    }
  ]

  # Validation rules
  def validate(:name, value), do: String.length(value) > 0
  def validate("address.street.house", value), do: value > 0
end

# Usage
iex> user = %User{name: "John", address: %{city: "London", street: %{name: "High St", house: 42}}}
iex> User.validate(user)
{:ok, %User{...}}

Type System

Estructura provides a rich type system with built-in types and scaffolds for custom types:

Built-in Types

  • DateTime - For handling datetime values
  • Date - For date values
  • Time - For time values
  • URI - For URI handling
  • IP - For IPv4 and IPv6 addresses
  • String - For string values
defmodule Event do
  use Estructura.Nested

  defstruct [
    timestamp: nil,
    url: nil
  ]

  def type(:timestamp), do: Estructura.Nested.Type.DateTime
  def type(:url), do: Estructura.Nested.Type.URI
end

Type Scaffolds

Enum Types

Create types with predefined values:

defmodule Status do
  use Estructura.Nested.Type.Enum,
    elements: [:pending, :active, :completed]
end

iex> Status.validate(:pending)
{:ok, :pending}
iex> Status.validate(:invalid)
{:error, "Expected :invalid to be one of: [:pending, :active, :completed]"}
Tag Sets

Manage lists of predefined tags:

defmodule Categories do
  use Estructura.Nested.Type.Tags,
    elements: [:tech, :art, :science]
end

iex> Categories.validate([:tech, :art])
{:ok, [:tech, :art]}
iex> Categories.validate([:invalid])
{:error, "All tags are expected to be one of [:tech, :art, :science]..."}

Coercion and Validation

Estructura provides flexible coercion and validation:

defmodule Temperature do
  use Estructura.Nested

  defstruct value: 0, unit: :celsius

  def coerce(:value, str) when is_binary(str) do
    case Float.parse(str) do
      {num, ""} -> {:ok, num}
      _ -> {:error, "Invalid number"}
    end
  end

  def validate(:value, v), do: v >= -273.15  # Absolute zero
  def validate(:unit, u), do: u in [:celsius, :fahrenheit, :kelvin]
end

Lazy Values

Use Estructura.Lazy for deferred computation:

defmodule Cache do
  use Estructura.Nested

  defstruct value: Estructura.Lazy.new(&expensive_computation/1)

  def expensive_computation(_), do: :timer.sleep(1000) && :computed
end

Flattening and Transformation

Convert nested structures to flat representations:

defmodule User do
  use Estructura.Nested, flattenable: true

  defstruct name: "", address: %{city: "", postal_code: ""}
end

iex> user = %User{name: "John", address: %{city: "London", postal_code: "SW1"}}
iex> Estructura.Flattenable.flatten(user)
%{"name" => "John", "address_city" => "London", "address_postal_code" => "SW1"}

Property Testing

Estructura supports property-based testing out of the box:

defmodule UserTest do
  use ExUnit.Case
  use ExUnitProperties

  property "valid users are validated" do
    check all %User{} = user <- User.__generator__() do
      assert {:ok, ^user} = User.validate(user)
    end
  end
end

Changelog

Documentation