Docs

Author: josevalim

lib/elixir/lib/module/types/descr.ex

@@ -2987,7 +2987,7 @@ defmodule Module.Types.Descr do
 
         map_update_static_keys(dnf, required_keys, optional_keys, type, missing_fun, acc)
 
-      {_, [missing_domain | _], _} ->
+      {_, _, [missing_domain | _], _} ->
         {:baddomain, domain_key_to_descr(missing_domain)}
     end
   end

lib/elixir/lib/module/types/expr.ex

@@ -897,7 +897,7 @@ defmodule Module.Types.Expr do
       message:
         IO.iodata_to_binary([
           """
-          expected a map with key #{to_quoted_string(key_type)} in map update syntax:
+          expected a map with key of type #{to_quoted_string(key_type)} in map update syntax:
 
               #{expr_to_string(expr, collapse_structs: false) |> indent(4)}
 

lib/elixir/pages/cheatsheets/types-cheat.cheatmd

@@ -0,0 +1,147 @@
+<!--
+  SPDX-License-Identifier: Apache-2.0
+  SPDX-FileCopyrightText: 2025 The Elixir Team
+-->
+
+# Set-theoretic types cheatsheet
+
+## Data types
+
+### Indivisible types
+
+```elixir
+binary()
+empty_list()
+integer()
+float()
+pid()
+port()
+reference()
+```
+
+### Atoms
+
+#### All atoms
+
+```elixir
+atom()
+```
+
+#### Individual atoms
+
+```elixir
+:ok
+:error
+SomeModule
+```
+
+### Functions
+
+#### All functions
+
+```elixir
+function()
+```
+
+#### `n`-arity functions
+
+```elixir
+(-> :ok)
+(integer() -> boolean())
+(binary(), binary() -> binary())
+```
+
+#### Multiple clauses
+
+```elixir
+(integer() -> binary()) and (binary() -> atom())
+```
+
+### Maps
+
+#### All maps
+
+```elixir
+map()
+```
+
+#### Empty map
+
+```elixir
+empty_map()
+```
+
+#### Maps with atom keys
+
+```elixir
+# Only has the keys name and age
+%{name: binary(), age: integer()}
+
+# Has the name key and age is optional
+%{name: binary(), age: if_set(integer())}
+
+# Has the keys name and age and may have other keys (open map)
+%{..., name: binary(), age: integer()}
+```
+
+#### Maps with domain keys (domain keys are always treated as optional)
+
+```elixir
+# Has atom and binary keys
+%{atom() => binary(), binary() => binary()}
+
+# Has atom and binary keys and may have other keys (open map)
+%{..., atom() => binary(), binary() => binary()}
+```
+
+### Non-empty lists
+
+#### Proper lists
+
+```elixir
+non_empty_list(elem_type)
+```
+
+#### Improper lists (as long as `tail_type` does not include lists)
+
+```elixir
+non_empty_list(elem_type, tail_type)
+```
+
+### Tuples
+
+#### All tuples
+
+```elixir
+tuple()
+```
+
+#### n-element tuples
+
+```elixir
+{:ok, binary()}
+{:error, binary(), term()}
+{pid(), reference()}
+```
+
+#### At least n-element tuples
+
+```
+{binary(), binary(), ...}
+```
+
+## Additional types for convenience
+
+#### Booleans
+
+```elixir
+boolean() = true or false
+```
+
+#### Lists
+
+```elixir
+list() = empty_list() or non_empty_list(term())
+list(a) = empty_list() or non_empty_list(a)
+list(a, b) = empty_list() or non_empty_list(a, b)
+```

lib/elixir/pages/references/gradual-set-theoretic-types.md

@@ -17,21 +17,38 @@ The current milestone aims to infer types from existing programs and use them fo
 
 ## A gentle introduction
 
-Types in Elixir are written using the type named followed by parentheses, such as `integer()` or `list(integer())`. The basic types in the language are: `atom()`, `binary()`, `integer()`, `float()`, `function()`, `list()` (and `improper_list()`), `map()`, `pid()`, `port()`, `reference()`, and `tuple()`.
+Types in Elixir are written using the type named followed by parentheses, such as `integer()` or `list(integer())`.
 
-Many of the types above can also be written more precisely. We will discuss their syntax in detail later, but here are some examples:
+The basic types are:
+
+```elixir
+atom()
+binary()
+empty_list()
+integer()
+float()
+function()
+map()
+non_empty_list(elem_type, tail_type)
+pid()
+port()
+reference()
+tuple()
+```
+
+Many of the types above can also be written more precisely. We will discuss their syntax in the next sections, but here are two examples:
 
   * While `atom()` represents all atoms, the atom `:ok` can also be represented in the type system as `:ok`
 
   * While `tuple()` represents all tuples, you can specify the type of a two-element tuple where the first element is the atom `:ok` and the second is an integer as `{:ok, integer()}`
 
-  * While `function()` represents all functions, you can specify a function that receives an integer and returns a boolean as `(integer() -> boolean())`
-
 There are also three special types: `none()` (represents an empty set), `term()` (represents all types), `dynamic()` (represents a range of the given types).
 
 Given the types are set-theoretic, we can compose them using unions (`or`), intersections (`and`), and negations (`not`). For example, to say a function returns either atoms or integers, one could write: `atom() or integer()`.
 
-Intersections will find the elements in common between the operands. For example, `atom() and integer()`, which in this case it becomes the empty set `none()`. You can combine intersections and negations to perform difference, for example, to say that a function expects all atoms, except `nil` (which is an atom), you could write: `atom() and not nil`.
+Intersections will find the elements in common between the operands. For example, `atom() and integer()`, which in this case is the empty set `none()`. You can combine intersections and negations to perform difference, for example, to say that a function expects all atoms, except `nil` (which is an atom), you could write: `atom() and not nil`.
+
+You can find a complete reference in the [set-theoretic types cheatsheet](../cheatsheets/types-cheat.cheatmd).
 
 ## The syntax of data types
 
@@ -63,24 +80,51 @@ Internally, Elixir represents the type `list(a)` as the union two distinct types
 
 #### Improper lists
 
-You can represent all _improper_ lists as `improper_list()`. Most times, however, an `improper_list` is built by passing a second argument to `non_empty_list`, which represents the type of the tail.
+While most developers will simply use `list(a)`, the type system can express all different representations of lists in Elixirby passing a second argument to `non_empty_list`, which represents the type of the tail.
 
 A proper list is one where the tail is the empty list itself. The type `non_empty_list(integer())` is equivalent to `non_empty_list(integer(), empty_list())`.
 
 If the `tail_type` is anything but a list, then we have an improper list. For example, the value `[1, 2 | 3]` would have the type `non_empty_list(integer(), integer())`.
 
-While most developers will simply use `list(a)`, the type system can express all different representations of lists in Elixir. At the end of the day, `list()` and `improper_list()` are translations to the following constructs:
-
-    list() == empty_list() or non_empty_list(term())
-    improper_list() == non_empty_list(term(), term() and not list())
+If you pass a list type as the tail, then the list type is merged into the element type. For example, `non_empty_list(integer(), list(binary()))` is the same as `non_empty_list(integer() or binary(), empty_list())`.
 
 ### Maps
 
-You can represent all maps as `map()`. Maps may also be written using their literal syntax, such as `%{name: binary(), age: integer()}`, which outlines a map with exactly two keys, `:name` and `:age`, and values of type `binary()` and `integer()` respectively.
+You can represent all maps as `map()`.
+
+Maps may also be written using their literal syntax, such as `%{name: binary(), age: integer()}`, which outlines a map with exactly two keys, `:name` and `:age`, and values of type `binary()` and `integer()` respectively.
+
+A key may be marked as optional using the `if_set/1` operation on its value type. For example, `%{name: binary(), age: if_set(integer())}` is a map that certainly has the `:name` key but it may have the `:age` key (and if it has such key, its value type is `integer()`).
+
+We say the maps above are "closed": they only support the keys explicitly defined. We can also mark a map as "open", by including `...` as its first element.
+
+For example, the type `%{..., name: binary(), age: integer()}` means the keys `:name` and `:age` must exist, with their respective types, but any other key may also be present. In other words, `map()` is the same as `%{...}`. For the empty map, you may write `%{}`, although we recommend using `empty_map()` for clarity.
+
+#### Domain types
 
-We say the map above is a "closed" map: it only supports the two keys explicitly defined. We can also mark a map as "open", by including `...` as its last element. For example, the type `%{name: binary(), age: integer(), ...}` means the keys `:name` and `:age` must exist, with their respective types, but any other key may also be present. In other words, `map()` is the same as `%{...}`. For the empty map, you may write `%{}`, although we recommend using `empty_map()` for clarity.
+In the examples above, all map keys were atoms, but we can also use other types as map keys. For example:
+
+```elixir
+# Closed map
+%{binary() or atom() => integer()}
+
+# Open map
+%{..., binary() or atom() => integer()}
+```
+
+Currently, the type system only tracks the top of each individial type as the domain keys. For example, if you say:
+
+```elixir
+%{list(integer()) => integer(), list(binary()) => binary()}
+```
+
+That's the same as:
+
+```elixir
+%{list(term()) => integer() or binary()}
+```
 
-Structs are closed maps with the `__struct__` key pointing to the struct name.
+Furthermore, it is important to note that domain keys are, by definition, optional. Whenever you have a `%{integer() => integer()}`and you try to fetch a key, we must assume the key may not exist (after all, it is not possible to store all integers as map keys as they are infinite).
 
 ### Functions
 
@@ -158,4 +202,4 @@ The third milestone is to introduce set-theoretic type signatures for functions.
 
 ## Acknowledgements
 
-The type system was made possible thanks to a partnership between [CNRS](https://www.cnrs.fr/) and [Remote](https://remote.com/). The research was partially supported by [Supabase](https://supabase.com/) and [Fresha](https://www.fresha.com/). The development work is sponsored by [Fresha](https://www.fresha.com/), [Starfish*](https://starfish.team/), and [Dashbit](https://dashbit.co/).
+The type system was made possible thanks to a partnership between [CNRS](https://www.cnrs.fr/) and [Remote](https://remote.com/). The development work is currently sponsored by [Fresha](https://www.fresha.com/), and [Tidewave](https://tidewave.ai/).

lib/elixir/scripts/elixir_docs.exs

@@ -48,6 +48,7 @@ canonical = System.fetch_env!("CANONICAL")
     "lib/elixir/pages/getting-started/erlang-libraries.md",
     "lib/elixir/pages/getting-started/debugging.md",
     "lib/elixir/pages/cheatsheets/enum-cheat.cheatmd",
+    "lib/elixir/pages/cheatsheets/types-cheat.cheatmd",
     "lib/elixir/pages/anti-patterns/what-anti-patterns.md",
     "lib/elixir/pages/anti-patterns/code-anti-patterns.md",
     "lib/elixir/pages/anti-patterns/design-anti-patterns.md",

lib/elixir/test/elixir/module/types/expr_test.exs

@@ -1058,6 +1058,36 @@ defmodule Module.Types.ExprTest do
                  # from: types_test.ex:LINE-3
                  x = %{foo: :baz}
              """
+
+      # The goal of this assertion is to verify we assert keys,
+      # even if they may be overridden later.
+      assert typeerror!(
+               [key],
+               (
+                 x = %{key: :value}
+                 %{x | :foo => :baz, key => :bat}
+               )
+             ) == ~l"""
+             expected a map with key :foo in map update syntax:
+
+                 %{x | :foo => :baz, key => :bat}
+
+             but got type:
+
+                 %{key: :value}
+
+             where "key" was given the type:
+
+                 # type: dynamic()
+                 # from: types_test.ex:LINE-5
+                 key
+
+             where "x" was given the type:
+
+                 # type: %{key: :value}
+                 # from: types_test.ex:LINE-3
+                 x = %{key: :value}
+             """
     end
 
     test "updating structs" do
@@ -1159,34 +1189,60 @@ defmodule Module.Types.ExprTest do
                )
              ) == closed_map(foo: atom([:new]), baz: atom([:old, :bat]))
 
-      # The goal of this assertion is to verify we assert keys,
-      # even if they may be overridden later.
       assert typeerror!(
                [key],
                (
-                 x = %{key: :value}
-                 %{x | :foo => :baz, key => :bat}
+                 x = %{String.to_integer(key) => :old}
+                 %{x | String.to_atom(key) => :new}
                )
              ) == ~l"""
-             expected a map with key :foo in map update syntax:
+             expected a map with key of type atom() in map update syntax:
 
-                 %{x | :foo => :baz, key => :bat}
+                 %{x | String.to_atom(key) => :new}
 
              but got type:
 
-                 %{key: :value}
+                 %{integer() => if_set(:old)}
 
              where "key" was given the type:
 
-                 # type: dynamic()
-                 # from: types_test.ex:LINE-5
-                 key
+                 # type: binary()
+                 # from: types_test.ex:LINE-3
+                 String.to_integer(key)
 
              where "x" was given the type:
 
-                 # type: %{key: :value}
+                 # type: %{integer() => if_set(:old)}
                  # from: types_test.ex:LINE-3
-                 x = %{key: :value}
+                 x = %{String.to_integer(key) => :old}
+             """
+
+      assert typeerror!(
+               [key],
+               (
+                 x = %{key: :old}
+                 %{x | String.to_atom(key) => :new}
+               )
+             ) == ~l"""
+             expected a map with key of type atom() in map update syntax:
+
+                 %{x | String.to_atom(key) => :new}
+
+             but got type:
+
+                 %{key: :old}
+
+             where "key" was given the type:
+
+                 # type: binary()
+                 # from: types_test.ex:LINE-2
+                 String.to_atom(key)
+
+             where "x" was given the type:
+
+                 # type: %{key: :old}
+                 # from: types_test.ex:LINE-3
+                 x = %{key: :old}
              """
     end