Constructor

An Elixir DSL for defining and validating structs.

Usage

  defmodule ConstructorExampleUser do
    use Constructor

    constructor do
      field :id, :integer, constructor: &is_integer/1, enforce: true
      field :role,  :user | :admin, constructor: &is_valid_role/1, enforce: true
      field :first_name, :string, default: "", constructor: &is_string/1
      field :last_name, :string, default: "", constructor: &is_string/1
    end

    def is_valid_role(value) do
      case value do
        :admin -> {:ok, value}
        :user -> {:ok, value}
        _ -> {:error, "invalid role!"}
      end
    end
  end

  iex> ConstructorExampleUser.new(id: "foo", role: :admin, first_name: 37)
  {:error, {:constructor, %{id: "must be an integer", first_name: "must be an integer"}}}

  iex> ConstructorExampleUser.new(id: 12, role: :admin, first_name: "Chris")
  {:ok, %ConstructorExampleUser{id: 12, first_name: "Chris", last_name: ""}}

  iex> ConstructorExampleUser.new!(id: 12, role: :admin, first_name: "Chris")
  %ConstructorExampleUser{id: 12, first_name: "Chris", last_name: ""}

Check out the docs to learn more.

Installation

Add constructor to your list of dependencies in mix.exs:

def deps do
  [
    {:constructor, "~> 1.0"}
  ]
end

Documentation can be generated with ExDoc and published on HexDocs. Once published, the docs can be found at https://hexdocs.pm/constructor.

But why?

Before writing the first iteration of this, I was using Vex for projects that didn't have an Ecto dependency, or Ecto.Changeset if I did. It worked, but there were a couple of issues.

1. Vex has some performance issues that seem difficult to resolve in a way that won't break existing users. More concerning, it seems like Vex is without a clear maintainer.
2. You can do most of what Constructor does with Ecto.Changesets, but you bring a lot of ORM baggage along with it. Much of it may not be applicable if your project is not using an RDBMS. Constructor provides a richer and more concise way of doing validations and type casting

Acknowledgments

This library was born from the lack of a lightweight and flexible validation library in Elixir. However, the design of the constructor/2 macro and indeed much of the functionality is provided by the excellent TypedStruct library.

Existing TypedStruct users

If you already depend on TypedStruct, you will need to remove that dependency from your mix.exs until the plugin system is released. You can track progress here