⚠️ Preview, requires Elixir 1.11.0-dev to run

Domo is a library to model a business domain with composable tags and type-safe structs.

It's a library to define what piece of data is what and make a dialyzer and run-time type checks to cover one's back, reminding about taken definitions.

The library aims for two goals:

• to model a business domain entity's possible valid states with custom types for fields of the struct representing the entity
• to verify that entity structs are assembled to one of the allowed valid states in run-time

The validation of the incoming data is on the author of the concrete application. The library can only ensure the consistent processing of that valid data according to type specs and definitions throughout the system.

The library has the means to build structs and relies on the TypedStruct to do so. It's possible to extend and configure many of the TypedStruct features transparently.

If you practice Domain Driven Design, this library can be used to model entities, value objects, and aggregates because it's delightful.

Rationale

To model a business domain entity, one may define a named struct with several fields of primitive data types. Construction of the struct from parsed data can look like this:

%Order{
  id: "156",
  quantity: 2.5
  note: "Deliver on Tue"
}

and modification of the struct's data can be done with a function of the following signature:

@spec put_quantity(Order.t(), float()) :: Order.t()
def put_quantity(order, quantity) ...

Primitive types of binary and float are universal and have no relation to the Order struct specifically. That is, any data of these types can leak into the new struct instance by mistake. The float type defining quantity reflects no measure from the business domain. Meaning, that a new requirement - to measure quantity in Kilograms or Units makes space for misinterpretation of the quantity field's value processed in any part of the app.

How about some domain modeling?

In the context given above, it'd be great to define a contract to allow only valid states for Order struct fields, that enables:

• local reasoning about the relation of value to the struct in any nested function of the app
• compile-time verification of assembling/updating of the structure from the values that relate only to it

One possible valid way to do so is to use Domo library like the following:

defmodule Order do
  use Domo

  deftag Id, for_type: String.t()

  deftag Quantity do
     for_type __MODULE__.Kilograms.t() | __MODULE__.Units.t()

     deftag Kilograms, for_type: float
     deftag Units, for_type: integer
  end

  deftag Note, for_type: :none | String.t()

  typedstruct do
    field :id, Id.t()
    field :quantity, Quantity.t()
    field :note, Note.t(), default: Note --- :none
  end
end

Then the construction of the struct becomes like this:

Order.new!(
  id: Id --- "156",
  quantity: Quantity --- Kilograms --- 2.5
  note: Note --- "Deliver on Tue"
)

And a signature of a custom function to modify the struct becomes like this:

@spec put_quantity(Order.t(), Order.Quantity.t()) :: Order.t()
def put_quantity(order, Quantity --- Units --- units) ...
def put_quantity(order, Quantity --- Kilograms --- kilos) ...

Thanks to the Domo library, every field of the structure becomes a tagged tuple consisting of a tag and a value. The tag is a module itself. Several tags can be nested, defining valid tag chains. These are playing the role of shapes for values of primitive type. That makes it possible to perform pattern matching against the shape of the struct's value. That enables the dialyzer to validate contracts for the structure itself and the structure's field values.

Run-time type checking

Complicated function calls can produce states that are unavailable to the dialyzer's static analysis. That can lead to a mix up of the data in the instances of the structures.

To catch possible logical errors, every struct modifying function that is added by Domo library checks a value of the field against its type spec when called. That makes it possible to fail closer to the origin of the error.

Creating a new structure with wrongly tagged value raises the ArgumentError like the following.

Order.new!(
  id: Id --- "ord000000012",
  quantity: Quantity --- Kilograms --- 2.5,
  note: Note --- :whaat
)

** (ArgumentError) Can't construct %App.Core.Order{...} with new!([id: {App.Core.Order.Id, "ord000000012"}, quantity: {App.Core.Order.Quantity, {App.Core.Order.Quantity.Kilograms, 2.5}}, note: {App.Core.Order.Note, :whaat}])
    Unexpected value type for the field :note. The value {App.Core.Order.Note, :whaat} doesn't match the Note.t() type.
    (app 0.1.0) lib/domo/struct_functions_generator.ex:18: App.Core.Order."new! (overridable 1)"/1

Modification of the existing structure with mismatching type raises the ArgumentError like that.

Order.merge!(order, note: :foo, quantity: :bar)

** (ArgumentError) Unexpected value type for the field :note. The value :foo doesn't match the Note.t() type.
    Unexpected value type for the field :quantity. The value :bar doesn't match the Quantity.t() type.
    (app 0.1.0) lib/domo/struct_functions_generator.ex:74: App.Core.Order.merge!/2

Usage

Setup

To use Domo in your project, add this to your Mix dependencies:

{:domo, "~> 0.0.9"}

To avoid mix format putting parentheses on tagged tuples definitions made with ---/2 operator, you can add to your .formatter.exs:

[
  ...,
  import_deps: [:domo]
]

General usage

Define a tag

To define a tag on the top level of a file import Domo, then define the tag name and type associated value with deftag/2 macro.

import Domo

deftag Title, for_type: String.t()
deftag Height do
  for_type: __MODULE__.Meters.t() | __MODULE__.Foots.t()

  deftag Meters, for_type: float
  deftag Foots, for_type: float
end

Any tag is a module by itself. Type t() of the tag is a tagged tuple. When defining a tag in a block form, you can specify the associated value type through the for_type/1 macro.

To add a tag or a tag chain to a value use ---/2 macro.

alias Height.{Meters, Foots}

t = Title --- "Eiffel tower"
m = Height --- Meters --- 324.0
f = Height --- Foots --- 1062.992

Under the hood, the tag chain is a series of nested tagged tuples where the value is in the core. Because of that, you can use the ---/2 macro in pattern matching.

{Height, {Meters, 324.0}} == m

@spec to_string(Height.t()) :: String.t()
def to_string(Height --- Meters --- val), do: to_string(val) <> " m"
def to_string(Height --- Foots --- val), do: to_string(val) <> " ft"

Each tag module has type t() of tagged tuple with the name of tag itself and a value type specified with for_type. Use t() in the function spec to inform the dialyzer about the tagged argument.

Define a structure

To define a structure with field value's contracts, use Domo, then define your struct with a typedstruct/1 block.

defmodule Order do
  use Domo

  deftag Id, for_type: String.t()
  deftag Note, for_type: :none | String.t()

  @typedoc "An Order from Sales context"
  typedstruct do
    field :id, Id.t()
    field :note, Note.t(), default: Note --- :none
  end
end

Each field is defined through field/3 macro. The generated structure has all fields enforced, default values specified by default: key, and type t() constructed with field types. See TypedStruct library documentation for implementation details.

Use new/1, merge/2, and put/3 function or their raising versions that are all automatically defined for the struct to create a new instance and update an existing one.

alias Order
alias Order.{Id, Note}

%{id: Id --- "o123556"}
|> Order.new!()
|> Order.put!(:note, Note --- "Deliver on Tue")

At the compile-time the dialyzer can check if properly tagged values are passed as parameters to these functions.

At the run-time, each function checks the values passed in against the types set in the field/3 macro. In case of mismatch, the functions raise an error.

That works with tags, and with any other user or system type, you may specify for the field. You can introduce tags in the project gracefully, taking them in appropriate proportion with the type safe-structs.

The functions mentioned above can be overridden to make data validations. Please, be careful and modify struct with a super(...) call. This call should be the last call in the overridden function.

It's still possible to modify a struct with %{... | s } map syntax and other standard functions directly skipping the checks. Please, use the functions mentioned above for the type-safety.

After the module compilation, the Domo library checks if all tags that are used with the ---/2 operator are defined and appropriately aliased.

The following options can be passed with use Domo, ...

Options

* `undefined_tag_error_as_warning` - if set to true, prints warning
  instead of raising an exception for undefined tags.

* `no_field` - if set to true, skips import of typedstruct/1
  and field/3 macros, useful with the import of the Ecto.Schema
  in the same module.

Reflexion

Each struct or tag defines __tags__/0 function that returns a list of tags defined in the module. Additionally each tag module defines __tag__?/0 function that returns true.

For example:

iex.(1)> defmodule Order do
....(1)>   use Domo
....(1)>
....(1)>   deftag Id, for_type: String.t()
....(1)>
....(1)>   deftag Quantity do
....(1)>      for_type __MODULE__.Kilograms.t() | __MODULE__.Units.t()
....(1)>
....(1)>      deftag Kilograms, for_type: float
....(1)>      deftag Units, for_type: integer
....(1)>   end
....(1)>
....(1)>   deftag Note, for_type: :none | String.t()
....(1)>
....(1)>   typedstruct do
....(1)>     field :id, Id.t()
....(1)>     field :quantity, Quantity.t()
....(1)>     field :note, Note.t(), default: Note --- :none
....(1)>   end
....(1)> end
{:module, Order,
<<70, 79, 82, 49, 0, 0, 17, 156, 66, 69, 65, 77, 65, 116, 85, 56, 0, 0, 1, 131,
  0, 0, 0, 41, 12, 69, 108, 105, 120, 105, 114, 46, 79, 114, 100, 101, 114, 8,
  95, 95, 105, 110, 102, 111, 95, 95, 7, ...>>,
[put!: 3, put!: 3, put!: 3, put!: 3, put!: 3]}
iex.(2)> Order.__tags__
[Order.Id, Order.Quantity, Order.Note]
iex.(3)> Order.Id.__tag__?
true

Pipeland

To add a tag or a tag chain to a value in a pipe use tag/2 macro and to remove use untag!/2 macro appropriately.

For instance:

import Domo
alias Order.Id

identifier
|> untag!(Id)
|> String.graphemes()
|> Enum.intersperse("_")
|> Enum.join()
|> tag(Id)

Limitations

When one uses a remote type for the field of a struct, the runtime type check will work properly only if the remote type's module is compiled into the .beam file on the disk, which means, that modules generated in memory are not supported. That's because of the way the Erlang functions load types.

We may not know your business problem; at the same time, the Domo library can help you to model the problem and understand it better.