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 toBox<Animal>. This fits types that only produce values ofT, such as read-only properties and function return types. - Contravariant: the relationship reverses.
Handler<Animal>is assignable toHandler<Dog>. This fits types that only consume values ofT, 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.
type Producer<T> = () => T; // covariant in T type Consumer<T> = (value: T) => void; // contravariant in T
Try it
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.
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
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 ofstrict) 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 toAnimal[]in TypeScript because arrays are treated covariantly, which allows pushing aCatinto 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) => voidis checked strictly,handle(v: T): voidleniently. - 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.