Skip to content
Tutorials Center
My learning

Topics

TypeScript Reference ยท Generics

Variance and assignability in TypeScript

Understand TypeScript variance: covariance, contravariance, invariance and bivariance, strictFunctionTypes, and the in and out annotations on type parameters.

Variance describes how subtyping of a generic type relates to subtyping of its type argument. If Dog is a subtype of Animal, is Box<Dog> a subtype of Box<Animal>? The answer depends on how Box uses its parameter.

  • Covariant: the relationship goes the same way. Box<Dog> is assignable to Box<Animal>. This fits types that only produce values of T, such as read-only properties and function return types.
  • Contravariant: the relationship reverses. Handler<Animal> is assignable to Handler<Dog>. This fits types that only consume values of T, such as function parameters.
  • Invariant: neither direction is allowed. This fits types that both produce and consume T.
  • Bivariant: both directions are allowed. TypeScript does this for method parameters, which is convenient but unsound.
TypeScript
type Producer<T> = () => T;            // covariant in T
type Consumer<T> = (value: T) => void; // contravariant in T

Try it

TypeScript Covariant producers, contravariant consumers

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

TypeScript Method bivariance and explicit annotations

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

Syntax

TypeScript
interface Producer<out T> { get(): T }
interface Consumer<in T> { put(value: T): void }
interface Both<in out T> { get(): T; put(value: T): void }
Annotation Meaning
out T T is used only in output positions (covariant).
in T T is used only in input positions (contravariant).
in out T T is invariant: both positions, no subtyping allowed between instantiations.
none The compiler measures variance from the structure of the type.

Errors: if the body uses T in a position that contradicts the annotation, the compiler can report an error. Annotations are only allowed on type parameters of aliases, interfaces and classes.

Usage notes

  • strictFunctionTypes (part of strict) makes function-typed parameters contravariant. Methods declared with method syntax are exempt and stay bivariant, so many built-in APIs keep working.
  • Mutable containers are really invariant. Dog[] is assignable to Animal[] in TypeScript because arrays are treated covariantly, which allows pushing a Cat into what is actually a dogs array. This is a known unsoundness.
  • Prefer readonly views for covariance. ReadonlyArray<Animal> is safely covariant.
  • Choose property syntax for strictness: handle: (v: T) => void is checked strictly, handle(v: T): void leniently.
  • Annotations speed up checking of deep generic types and document intent; they do not change emitted code.
  • Inference of variance works by testing marker types; for recursive types, an annotation can fix wrong or slow results.
  • Assignability also applies to unions and optional members, but the variance rules above are what govern generic type arguments.