View Source Comparing TypeCheck and Elixir Typespecs

TypeCheck is intended to be a drop-in supplement to Elixir typespecs. With very few exceptions, all of Elixir's typespecs are supported by TypeCheck. Below is a breakdown of supported typespec syntax in TypeCheck.

In the tables below:

• '✅' indicates that something is supported
• '❌' indicates that something is not supported.
• '⌛' indicates that something is not currently supported, but there are plans to add support for it in the near future.

Basic Types

Literals

¹: Functions passed as parameters can only be fully checked once they are called. TypeCheck wraps them in a 'wrapper function' which performs the correct check on their input/output. This wrapper will only run once the the function actually is called.

²: Only a single 'required' or 'optional' field in a map is currently supported. (Types which need more are fortunately very rare.)

³: Only optional is currently supported, and only a single one. (Types which need more are fortunately very rare.)

Built-in types

🚀 TypeCheck Additions

TypeCheck adds the following extensions on Elixir's builtin typespec syntax:

Defining Specifications

✅ Basic Spec Definition

# typespecs
@spec function_name(type1, type2) :: return_type

# TypeCheck
@spec! function_name(type1, type2) :: return_type

❌ Spec Guards

# typespecs
@spec function(arg) :: [arg] when arg: atom
@spec function(arg1, arg2) :: {arg1, arg2} when arg1: atom, arg2: integer
@spec function(arg) :: [arg] when arg: var

# TypeCheck - unsupported

TypeCheck currently solely allows the usage of when to specify 'type guards' (see below). Support for spec guards could be added. However:

• Their usage is quite rare.
• Each place where it is used, it matches 'exactly the same value'. Building this check is relatively tricky.

If you have a strong desire for this feature, please open an issue for it.

✅ Named Arguments

# typespecs
@spec days_since_epoch(year :: integer, month :: integer, day :: integer) :: integer
@type color :: {red :: integer, green :: integer, blue :: integer}

# TypeCheck
@spec! days_since_epoch(year :: integer, month :: integer, day :: integer) :: integer
@type! color :: {red :: integer, green :: integer, blue :: integer}

❌ Specification Overloads

# typespecs
@spec function(integer) :: atom
@spec function(atom) :: integer

# TypeCheck - unsupported

There is no intention to support this. The implementation would be very difficult, and it is arguably good practice to have a single specification anyway.

User Defined Types

✅ Basic Definition

# typespecs
@type type_name :: type
@typep type_name :: type
@opaque type_name :: type

# TypeCheck
@type! type_name :: type
@typep! type_name :: type
@opaque! type_name :: type

✅ Parameterized Types

# typespecs
@type dict(key, value) :: [{key, value}]

# TypeCheck
@type! dict(key, value) :: [{key, value}]

🚀 Type Guards

To add extra custom checks to a type, you can use a so-called 'type guard'. This is arbitrary code that is executed during a type-check once the type itself already matches.

You can use "named types" to refer to (parts of) the value that matched the type, and refer to these from a type-guard:

# typespecs - unsupported

# TypeCheck
@type! sorted_pair :: {lower :: number(), higher :: number()} when lower <= higher

✅ Remote Types

It is often useful to refer to types defined in other modules. These are called 'Remote types'. Elixir's typespecs and TypeCheck both support remote types.

# typespecs
defmodule User do
  @type t() :: %User{name: String.t(), age: non_negative_integer()}
end

defmodule Greeter do
  @spec greet(User.t()) :: String.t()
  def greet(user) do
   # ... 
  end
end

# TypeCheck
defmodule User do
  use TypeCheck

  @type! t() :: %User{name: String.t(), age: non_negative_integer()}
end

defmodule Greeter do
  use TypeCheck

  @spec! greet(User.t()) :: String.t()
  def greet(user) do
   # ... 
  end
end

Remote Type Overrides

From time to time we need to interface with modules written in other libraries (or the Elixir standard library) which do not expose their types through TypeCheck yet. We want to be able to use those types in our checks, but they exist in modules that we cannot change ourselves.

The solution is to allow a list of ‘type overrides’ to be given as part of the options passed to use TypeCheck, which allow you to use the original type in your types and documentation, but have it be checked (and potentially property-generated) as the given TypeCheck-type.

Example:

defmodule Original do
  @type t() :: any()
end

defmodule Replacement do
  use TypeCheck
  @type! t() :: integer()
end

defmodule Example do
  use TypeCheck, overrides: [{&Original.t/0, &Replacement.t/0}]

  @spec! times_two(Original.t()) :: integer()
  def times_two(input) do
    input * 2
  end
end

Elixir Standard Library Types

TypeCheck helpfully ships with the majority of the types in Elixir's Standard Library already implemented as default overrides. This means that your @spec! definitions can reference types like String.t(), Date.t() and Range.t() out of the box.