Learning covariance and contravariance in TypeScript could be tricky (I know from my experience!), but knowing them is a great addition to understanding types and subtyping.
In this post, you'll read an accessible explanation of covariance and contravariance concepts.
Table of Contents
1. Subtyping
Subtyping is a form of polymorphism in which a subtype is associated with a base type by some form of substitutability.
The substitutability means that a variable of base type can also accept subtype values.
For example, let's define a base class User
and a class Admin
that extends User
class:
ts
classUser {username : string;constructor(username : string) {this.username =username ;}}classAdmin extendsUser {isSuperAdmin : boolean;constructor(username : string,isSuperAdmin : boolean) {super(username );this.isSuperAdmin =isSuperAdmin ;}}
Since Admin
extends User
(Admin extends User
), you could say that Admin
is a subtype of the base type User
.
The substitutability of Admin
(subtype) and User
(base type) consists, for example, in the ability to assign to a variable of type User
an instance of type Admin
:
ts
constuser1 :User = newUser ('user1'); // OKconstuser2 :User = newAdmin ('admin1', true); // also OK
How can you benefit from the substitutability?
One of the great benefits is that you can define behavior that doesn't depend on details. In simple words, you can create functions that accept the base type as a parameter, but then you can invoke that function with subtypes.
For example, let's write a function that logs the user name to the console:
ts
functionlogUsername (user :User ): void {console .log (user .username );}
This function accepts arguments of type User
, Admin
, and instances of any other subtypes of User
you might create later. That makes logUsername()
more reusable and less bothered with details:
ts
logUsername (newUser ('user1')); // logs "user1"logUsername (newAdmin ('admin1', true)); // logs "admin1"
1.1 A few helpers
Now let's introduce the symbol A <: B
— meaning "A is a subtype of B".
Because Admin
is a subtype of User
, now you could write shorter:
Admin <: User
Let's also define a helper type IsSubtypeOf<S, P>
, which evaluates to true
if S
if a subtype of P
, and false
otherwise:
ts
typeIsSubtypeOf <S ,P > =S extendsP ? true : false;
IsSubtypeOf<Admin, User>
evaluates to true
because Admin
is a subtype of User
:
ts
typeT11 =IsSubtypeOf <Admin ,User >;
Subtyping is possible for many other types, including primitives and built-in JavaScript types.
For example, the literal string type 'Hello'
is a subtype of string
, the literal number type 42
is a subtype of number
, Map<K, V>
is a subtype of Object
.
ts
typeT12 =IsSubtypeOf <'hello', string>;typeT13 =IsSubtypeOf <42, number>;typeT14 =IsSubtypeOf <Map <string, string>,Object >
2. Covariance
Let's think about some asynchronous code that fetches User
and Admin
instances. Working with async code requires dealing with promises of User
and Admin
: Promise<User>
and <: Promise<Admin>
.
Here's an interesting question: having Admin <: User
, does it mean that Promise<Admin> <: Promise<User>
holds as well?
Let's make the experiment:
ts
typeT21 =IsSubtypeOf <Promise <Admin >,Promise <User >>
Having Admin <: User
, then Promise<Admin> <: Promise<User>
indeed holds true. This demonstrates that Promise
type is covariant.
Here's a definition of covariance:
A type
T
is covariant if havingS <: P
, thenT<S> <: T<P>
.
The covariance of a type is intuitive. If Admin
is a subtype of User
, then you can expect Promise<Admin>
to be a subtype of Promise<User>
.
Covariance holds for many types in TypeScript.
A) Promise<V>
(demonstrated above)
B) Record<K,V>
:
ts
typeRecordOfAdmin =Record <string,Admin >;typeRecordOfUser =Record <string,User >;typeT22 =IsSubtypeOf <RecordOfAdmin ,RecordOfUser >;
C) Map<K,V>
:
ts
typeMapOfAdmin =Map <string,Admin >;typeMapOfUser =Map <string,User >;typeT23 =IsSubtypeOf <MapOfAdmin ,MapOfUser >;
3. Contravariance
Now let's consider the following generic type:
ts
typeFunc <Param > = (param :Param ) => void;
Func<Param>
creates function types with one parameter of type Param
.
Having Admin <: User
, which of the expressions is true:
Func<Admin> <: Func<User>
, orFunc<User> <: Func<Admin>
?
Let's take a try:
ts
typeT31 =IsSubtypeOf <Func <Admin >,Func <User >>typeT32 =IsSubtypeOf <Func <User >,Func <Admin >>
Func<User> <: Func<Admin>
holds true — meaning that Func<User>
is a subtype of Func<Admin>
. Note that the subtyping direction has flipped compared to the original types Admin <: User
.
Such behavior of Func
type makes it contravariant. Speaking generally, function types are contravariant in regards to their parameter types.
A type
T
is contravariant if havingS <: P
, thenT<P> <: T<S>
.
The subtyping direction of function types is in the opposite direction of the subtyping of the parameter types.
ts
typeFuncUser = (p :User ) => void;typeFuncAdmin = (p :Admin ) => void;typeT31 =IsSubtypeOf <Admin ,User >;typeT32 =IsSubtypeOf <FuncUser ,FuncAdmin >;
4. Functions subtyping
What is interesting about functions subtyping is that it combines both covariance and contravariance.
A function type is a subtype of a base type if its parameter types are contravariant with the base type' parameter types, and the return type is covariant* with the base type' return type.
*when strictFunctionTypes mode is enabled.
In other words, the subtyping for functions requires that the parameter types be contravariant, while the return types covariant.
For example:
ts
typeSubtypeFunc = (p :User ) => '1' | '2';typeBaseFunc = (p :Admin ) => string;typeT41 =IsSubtypeOf <SubtypeFunc ,BaseFunc >
SubtypeFunc <: BaseFunc
because:
A) parameter types are contravariant (subtyping direction flipped User :> Admin
)
B) return types are covariant (same subtyping direction '1' | '2' <: string
).
Knowing subtyping greatly helps to understand the substitutability of function types.
For example, having a list of Admin
instances:
ts
constadmins :Admin [] = [newAdmin ('john.smith', false),newAdmin ('jane.doe', true),newAdmin ('joker', false)];
What types of callbacks does the admins.filter(...)
accept?
Obviously, it accepts a callback with one parameter of type Admin
:
ts
constadmins :Admin [] = [newAdmin ('john.smith', false),newAdmin ('jane.doe', true),newAdmin ('joker', false)];constsuperAdmins =admins .filter ((admin :Admin ): boolean => {returnadmin .isSuperAdmin ;});superAdmins ; // [ Admin('jane.doe', true) ]
But would admins.filter(...)
accept a callback which parameter type is User
?
ts
constjokers =admins .filter ((user :User ): boolean => {returnuser .username .startsWith ('joker');});jokers ; // [ Admin('joker', false) ]
Yes, admins.filter()
accepts (admin: Admin) => boolean
base type, but also its subtypes like (user: User) => boolean
.
If a higher-order function accepts callbacks of a specific type, e.g. (admin: Admin) => boolean
, then you can also supply callbacks that are subtypes of the specific type, e.g. (user: User) => boolean
.
5. Conclusion
The type T
is covariant if having 2 types S <: P
, then T<S> <: T<P>
(the subtyping direction is maintained). An example of a covariant type is the Promise<T>
.
But if T<P> <: T<S>
(the subtyping is flipped), then T
is contravariant.
The function type is contravariant by the parameter types, but covariant by the return types.
Challenge: What other covariant or contravariant types do you know?