Typespec question

Questions / Help
,
1

Hi, all.

I have read several elixir books and the only Ecto book, and still confused on Typespecs. I googled a few articles on typespecs including official Typespect document of Elixir site and questions in elixir forum here, but not clear at all.
For example,

defmodule Friends.Person do
  use Ecto.Schema

  schema "people" do
    field(:first_name, :string)
    field(:last_name, :string)
    field(:age, :integer)
  end

  @spec changeset(
          {map, map} | %{:__struct__ => atom | %{__changeset__: map}, optional(atom) => any},
          :invalid | %{optional(:__struct__) => none, optional(atom | binary) => any}
        ) :: Ecto.Changeset.t()
  def changeset(person, params \\ %{}) do
    person
    |> Ecto.Changeset.cast(params, [:first_name, :last_name, :age])
    |> Ecto.Changeset.validate_required([:first_name, :last_name])
  end
end

I hope someone explain the typespec of the changeset function above.
I guess,

  1. The paremeters of the changeset function can be one of the three:
(1) {map, map}, 
(2) %{:__struct__ => atom | %{__changeset__: map}, optional(atom) => any}, :invalid , 
(3) %{optional(:__struct__) => none, optional(atom | binary) => any}
  1. In the first case(1) of {map, map}, The type of the first parameter person is a struct, and that of the second is a map. What is the meaning of {map, map} tuple? That is to say, why {} is necessary here?
  2. In the second case(2), the changeset function needs only two parameters, then why the third parameter, :invalid atom, is there? What is the meaning of __strunct__ in :__struct__ => atom? What is the meaning of __changeset__ in %{__changeset__: map}? What is the meaning of `optional(atom) => any’ here?
  3. What is the meaning of the third case(3)? %{optional(:__struct__) => none, optional(atom | binary) => any}

It’s quite a verbose question, but it surely will help many novices in the future who visit this forum or googling similar questions.

Always thank you all.

2

Let’s do this from the outside in:

changeset/2 has an arity of 2 (ignoring the default for now, typespecs don’t know about default values) and as any function one return value.

The return value is simple: Ecto.Changeset.t, which essentially aliases an Ecto.Changeset struct.

Parameter 1 is {map, map} | %{:__struct__ => atom | %{__changeset__: map}, optional(atom) => any}
So it can either be a 2 element tuple or a struct.
The tuple needs to have a map for each element. This is the format of schemaless changesets.
The schema needs to have a struct key and optionally further atom key. I’m not sure exactly what the %{__changeset__: map} is for in the struct key. But the value shall be able to have that format as well.

Parameter two is :invalid | %{optional(:__struct__) => none, optional(atom | binary) => any}. I’m not sure why the struct key is explictly listed here, but Ecto.Changeset.cast's typespec accepts %{binary => term} | %{atom => term} | :invalid, which means either the atom :invalid or a map of either exclusively string keys or exclusively atom keys. What you’re seeing allows for the same, but with different constraints.

If you got to those typespecs via the auto-generation of elixir-ls: Dialyzer sometimes does things more complex then they need to be.

2 Likes
3

Hi LostKobrakai. I have thankfully read several articles of you written before.

  1. The first parameter of the changeset function is the person struct, and the second is a map. Can the type of the person struct be denoted as {map, map}?
  2. What is the meaning of the two lowdash ‘__’ before and after some keys, such as __struct__ and __changeset__?
5

Would anyone write the typespecs of the changeset function by hand without Dialyzer?

My guess is;
@spec changeset(Person.t(), %{optional(key) => value}) :: Changeset.t()

Seeing the Typespecs page, the built-in type of struct() is defined as %{:__struct__ => atom(), optional(atom()) => any()}. I hope someone explain what this means.

6

The first parameter of the changeset function is the person struct, and the second is a map . Can the type of the person struct be denoted as {map, map}?

No. I guess the person struct is something like

%MyApp.Person{
  name: "John Doe",
  gender: "male"
}

In Elixir, this is just

%{
  __struct__: MyApp.Person,
  name: "John Doe",
  gender: "male"
}

or to be more bare metal,

%{
  :__struct__ => :"Elixir.MyApp.Person",
  :name => "John Doe",
  :gender => "male"
}

So, it matches %{:__struct__ => atom, optional(atom) => any}.

What is the meaning of the two lowdash ‘__’ before and after some keys, such as __struct__ and __changeset__ ?

Syntactically, the double underscore is nothing special. It’s just a part of a field name. Visually, it tells you that this field is for special use (like reflection), and the Elixir language or the lib/framework you use depends on it. So, you can read it, but you should not change its value or remove the field.

3 Likes
7

Now I understand some of the crypto codes. Would you show me the typespecs of the changeset function if you write it rather than those of Dialyzer?

And what is meaning of {map, map} in the typespecs above?

8

Ecto.Changeset.cast/4 has its first argument typed as Ecto.Schema.t() | t() | {data(), types()}. So the {map, map} is coming from that last argument type, which is a tuple of two maps (both data() and types() are just aliases to map() in Ecto code).

3 Likes
9

Thank you, Nicd.
Much more clear than before.