Domo

Domo can be applied to any struct defined with defstruct/1 and a t() type. When a module uses use Domo, it automatically gains several functions for instantiation and validation:

• new!/1: Creates a new instance of the struct. The bang version (!) will raise an error if validation fails.
• new/1: The non-bang version, returning {:ok, struct} or {:error, errors}.
• ensure_type!/1/2: Validates that the provided data matches the expected t() type definition and associated preconditions. The bang version raises an error on failure.
• ensure_type/1/2: The non-bang version, returning {:ok, struct} or {:error, errors}.

ensure_type/2 also accepts an option maybe_filter_precond_errors: true to handle precondition errors.

# Example: Creating and validating a Passenger
alias ExampleAvialia.Boardings.Passenger

# Create a new passenger
p = Passenger.new!(flight: "ALA-1215", first_name: "John", last_name: "Smith", seat: "5C")

# Validate type consistency (will raise error if flight is invalid)
Passenger.ensure_type!(%{p | flight: "invalid"})

# Example: Creating and validating a Shipment
alias ExampleAvialia.Cargos.Shipment

{:ok, s} = Shipment.new(
  flight: "ALA-1215", 
  kind: {:passenger_baggage, "5C"}, 
  weight: {:kilograms, 29}, 
  documents_count: 0, 
  documents: []
)

# Validate with precondition error filtering
Shipment.ensure_type(
  %{s | kind: {:passenger_baggage, "invalid"}}, 
  maybe_filter_precond_errors: true
)

To enforce business rules, use the precond macro. Preconditions can be attached to specific fields or to the struct's type t() as a whole.

Field-level preconditions

Attach a precondition to a specific field type to ensure values meet certain criteria (e.g., range checks).

Type-level (invariant) preconditions

Attach a precondition to the t type to validate invariants involving multiple fields or nested structs.

Example:

defmodule PurchaseOrder do
  use Domo

  defstruct id: 1000, approved_limit: 200, items: []

  @type id :: non_neg_integer()
  precond(id: &(1000 <= &1 and &1 <= 5000))

  @type t :: %__MODULE__{
          id: id(),
          approved_limit: pos_integer(),
          items: [LineItem.t()]
        }
  precond(t: &validate_invariants/1)

  defp validate_invariants(po) do
    amounts = po.items |> Enum.map(& &1.amount) |> Enum.sum()
    if amounts <= po.approved_limit do
      :ok
    else
      {:error, "Sum of line item amounts (#{amounts}) should be <= to approved limit (#{po.approved_limit})."}
    end
  end
end

defmodule LineItem do
  use Domo

  defstruct amount: 0

  @type t :: %__MODULE__{amount: non_neg_integer()}
end

defmodule PurchaseOrder do
  use Domo

  defstruct id: 1000, approved_limit: 200, items: []

  @type id :: non_neg_integer()
  precond(id: &(1000 <= &1 and &1 <= 5000))

  @type t :: %__MODULE__{
          id: id(),
          approved_limit: pos_integer(),
          items: [LineItem.t()]
        }
  precond(t: &validate_invariants/1)

  defp validate_invariants(po) do
    amounts = po.items |> Enum.map(& &1.amount) |> Enum.sum()

    if amounts <= po.approved_limit do
      :ok
    else
      {:error, "Sum of line item amounts (#{amounts}) should be <= to approved limit (#{po.approved_limit})."}
    end
  end
end

The ExampleAvialia project demonstrates how to maintain domain model consistency using Domo within a Phoenix application. It features two contexts—board passengers and cargo shipments—backed by separate Ecto repositories to simulate a microservices architecture.

To run the full application, follow these steps:

1. Start PostgreSQL: Use Docker to run a local PostgreSQL instance.
2. Setup Elixir dependencies: Install project dependencies and migrate the database.
3. Setup Assets: Install Node.js dependencies in the assets directory.
4. Start Server: Launch the Phoenix server and visit http://localhost:4000.

# 1. Start PostgreSQL
docker run --name postgres-domo \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=postgres \
  -p 5432:5432 \
  -d postgres:latest

# 2. Setup Elixir/Phoenix
mix deps.get
mix ecto.setup

# 3. Setup Assets
cd assets && npm install && cd ..

# 4. Start Server
mix phx.server

If you need to generate default values dynamically during construction (e.g., generating a random token), you can instruct Domo to use a different name for its internal constructor. This allows you to define your own new/1 and new!/1 functions while still benefiting from Domo's validation.

1. Use skip_defaults: true in use Domo.
2. Use gen_constructor_name: :_new (or any other atom) to name the Domo-generated constructor.
3. Define your own new/1 and new!/1 which call the generated _new/1 functions.

defmodule Foo do
  use Domo, skip_defaults: true, gen_constructor_name: :_new

  defstruct [:id, :token]

  @type id :: non_neg_integer()
  @type token :: String.t()
  precond token: &byte_size(&1) == 8

  @type t :: %__MODULE__{id: id(), token: token()}

  def new(id) do
    _new(id: id, token: random_string(8))
  end

  def new!(id) do
    _new!(id: id, token: random_string(8))
  end

  defp random_string(length), do: ... 
end