A library to ensure the consistency of structs modelling a business domain via their t() types and associated precondition functions.

Used in a struct's module, the library adds constructor, validation, and reflection functions. Constructor and validation functions guarantee the following at call time:

• A complex struct conforms to its t() type.
• Structs are validated to be consistent to follow given business rules by precondition functions associated with struct types.

If the conditions described above are not met, the constructor and validation functions return an error.

Because precondition function associates with type the validation can be shared across all structs referencing the type.

In terms of Domain Driven Design the invariants relating structs to each other can be defined with types and associated precondition functions.

Let's say that we have a PurchaseOrder and LineItem structs with relating invariant that is the sum of line item amounts should be less then order's approved limit. That can be expressed like the following:

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
    cond do
      po.items |> Enum.map(& &1.amount) |> Enum.sum() > po.approved_limit ->
        {:error, "Sum of line item amounts should be <= to approved limit"}

      true ->
        :ok
    end
  end
end

defmodule LineItem do
  use Domo

  defstruct [amount: 0]

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

Then PurchaseOrder struct can be constructed consistently like that:

iex> {:ok, po} = PurchaseOrder.new_ok()
{:ok, %PurchaseOrder{approved_limit: 200, id: 1000, items: []}}

iex> PurchaseOrder.new_ok(id: 500, approved_limit: 0)
{:error,
 [
   id: "Invalid value 500 for field :id of %PurchaseOrder{}. Expected the 
   value matching the non_neg_integer() type. And a true value from 
   the precondition function \"&(1000 <= &1 and &1 <= 5000)\" 
   defined for PurchaseOrder.id() type.",
   approved_limit: "Invalid value 0 for field :approved_limit of %PurchaseOrder{}. 
   Expected the value matching the pos_integer() type."
 ]}

iex> updated_po = %{po | items: [LineItem.new!(amount: 150), LineItem.new!(amount: 100)]}
%PurchaseOrder{
  approved_limit: 200,
  id: 1000,
  items: [%LineItem{amount: 150}, %LineItem{amount: 100}]
}

iex> PurchaseOrder.ensure_type_ok(updated_po)
{:error, [t: "Sum of line item amounts should be <= to approved limit"]}

iex> updated_po = %{po | items: [LineItem.new!(amount: 150)]}
%PurchaseOrder{approved_limit: 200, id: 1000, items: [%LineItem{amount: 150}]}

iex> PurchaseOrder.ensure_type_ok(updated_po)
{:ok, %PurchaseOrder{approved_limit: 200, id: 1000, items: [%LineItem{amount: 150}]}}

See the Callbacks section for more details about functions added to the struct.

Compile-time and Run-time validations

At the project's compile-time, Domo can perform the following checks:

• It automatically validates that the default values given with defstruct/1 conform to struct's type and fulfill preconditions.

• It ensures that the struct using Domo built with new!/1 function to be a function's default argument or a struct field's default value matches its type and preconditions.

Domo validates struct type conformance with appropriate TypeEnsurer modules built during the project's compilation at the application's run-time. These modules rely on guards and pattern matchings. See __using__/1 for more details.

Depending types tracking

Suppose the given structure field's type depends on a type defined in another module. When the latter type or its precondition changes, Domo recompiles the former module automatically to update its TypeEnsurer to keep type validation in current state.

That works similarly for any number of intermediate modules between module defining the struct's field and module defining the field's final type.

Setup

To use Domo in a project, add the following line to mix.exs dependencies:

{:domo, "~> 1.2.0"}

And the following line to the compilers:

compilers: Mix.compilers() ++ [:domo_compiler],

To avoid mix format putting extra parentheses around precond/1 macro call, add the following import to the .formatter.exs:

[
  import_deps: [:domo]
]

Usage with Phoenix hot reload

To call functions added by Domo from a Phoenix controller, add the following line to the endpoint's configuration in the config.exs file:

config :my_app, MyApp.Endpoint,
  reloadable_compilers: [:phoenix] ++ Mix.compilers() ++ [:domo_compiler],

Otherwise, type changes wouldn't be hot-reloaded by Phoenix.

Usage with Ecto

Ecto schema changeset can be automatically validated to conform to t() type and fulfil associated preconditions.

See Domo.Changeset module documentation for details.

See the example app using Domo to validate Ecto changesets in the /example_avialia folder of this repository.

Usage with libraries generating t() type for a struct

Domo is compatible with most libraries that generate t() type for a struct or an Ecto schema. Just use Domo in the module, and that's it.

An advanced example is in the /example_typed_integrations folder of this repository.