Constructor is a DSL for defining and validating structs. To illustrate, let's take a basic User struct you might have in your app.

defmodule ConstructorExampleUser do
  @enforce_keys [:id, :role]
  @allowed_keys ["id", "role", "first_name", "last_name"]

  @type t :: %__MODULE__{
    id: integer,
    role: :user | :admin,
    first_name: String.t(),
    last_name: String.t()
  }

  defstruct [:id, :role, first_name: "", last_name: ""]

  def new(v) when is_map(v) do
    struct = v |> convert_to_struct()
    with :ok <- is_integer(struct.id),
      :ok <- is_valid_role(struct.role),
      :ok <- is_string(struct.first_name),
      :ok <- is_string(struct.last_name) do
        {:ok, struct}
    else
      {:error, e} -> {:error, {:constructor, e}}
    end
  end

  def map_to_struct(v) do
    mapped = Enum.map(v, fn {key, value} ->
      if Enum.any?(@allowed_keys, fn x -> x == key end) do
        {String.to_atom(key), v}
      else
        {key, v}
      end
    end)
    struct(__MODULE__, mapped)
  end

  def is_string(value) do
    case value do
      x when is_binary(x) -> :ok
      _ -> {:error, "must be a string"}
    end
  end

  def is_integer(value) do
    case value do
      x when Kernel.is_integer(x) -> :ok
      _ -> {:error, "must be an integer"}
    end
  end

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

Elixir code such as this is pretty standard in most projects (especially those without Ecto). It's explicit, and good for taking input from a user or deserializing a struct from JSON. But it has some flaws:

1. It returns on the first validation failure, so the user will have to fix and submit again in order to find out if there's another error.
2. You have duplication of field names in the @type, defstruct and @allowed_keys declarations. A real pain to change each time you add or remove a field, with the @type tending to fall out of sync with the rest of the module quickly.
3. It's a lot of code! Some parts, such as is_integer/1 and is_string/1, can easily apply across projects. A production-ready implementation of map_to_struct/1 would need to be expanded to handle nested structs and lists, all of which needs to be tested.

Constructor solves this problem by providing a constructor/2 macro that allows you to define a field, typespecs, enforced keys, validations, and coercions all in a handful of lines. Here's how you would write the above struct with Constructor.

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

Most of the underlying functionality for Constructor is provided by the :typed_struct library. The TypedStruct.field/3 macro has been expanded to collect the :constructor option, which is than used by the generated new/1 methods. I won't repeat the TypedStruct documentation here, but it's important to note that constructor/2 should behave the same as TypedStruct.typedstruct/2 in all respects that aren't Constructor specific.

You can see that unlike our previous new/1 method, this one will accept keyword lists as well as maps and return errors for multiple fields.

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

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: ""}

Any function that conforms to constructor_fun/0 can be used in the construct field. Additionally, a new/1 function can also be used to build out a nested struct. For example:

defmodule ConstructorExampleAdmin do
  use Constructor

  constructor do
    field :id, :integer, constructor: &Validate.is_integer/1
    field :user, ConstructorExampleUser.t(), constructor: &ConstructorExampleUser.new/1
  end
end

iex> ConstructorExampleAdmin.new!(id: 22, user: %{id: 22, first_name: "Chris"})
%ConstructorExampleAdmin{id: 22, user: %ConstructorExampleUser{id: 22, first_name: "Chris"}}

Enforce Keys

If you're defining a struct with the enforce: true option, you'll also want to set the check_keys: true option in your constructor call. Note that this will cause new/2 to raise a KeyError if a key that is undefined on the struct is passed as input.

Custom Validation Functions

Custom validation functions will need to confrom to the constructor/0 typespec. The test suite has many examples.

Optional Callbacks

before_construct/1 and after_construct/1 can be implemented if you need to work with the entire input at once. If the input was a list of maps, the callbacks will be called for each list value.

• before_construct/1 will be called before anything else, so it allows you to manipulate the raw input before the rest of Constructor works on it.
• after_construct/1 will be called last, after everything else. It's good for doing multi-field validatons after the data has been converted and validated.