TypeScript Reference ยท Type Operators
TypeScript in and out variance annotations
Reference for TypeScript variance annotations: out for covariant, in for contravariant, in out for invariant type parameters, with checking rules.
Variance describes how subtyping of a generic type follows subtyping of its argument. If Cat is a subtype of Animal, is Box<Cat> a subtype of Box<Animal>? The answer depends on how the type parameter is used. TypeScript normally infers this by comparing structures; since version 4.7 you can state it with the in and out modifiers on type parameters.
out T marks T as covariant (only produced), in T as contravariant (only consumed), and in out T as invariant (both).
interface Producer<out T> { get(): T } interface Consumer<in T> { accept(value: T): void }
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 Name<in T, out U, in out V> { ... } type Alias<out T> = ...; class C<out T> { ... }
| Modifier | Variance | Meaning |
|---|---|---|
out T |
Covariant | T may only appear in output positions: return types, readonly properties. |
in T |
Contravariant | T may only appear in input positions: method parameters. |
in out T |
Invariant | Both read and write; no substitution allowed in either direction. |
| none | Inferred | The compiler measures it from the structure. |
Errors: if the annotation contradicts the use of T, the compiler reports error 2636, "Type ... is not assignable to type ... as implied by variance annotation". The second example above triggers it with put: (value: T) => void under out T. The same declaration written as a method, put(value: T): void, is accepted without error because method parameters are checked bivariantly.
Usage notes
- Optional in practice. Inference gets most cases right; annotate to document intent or to speed up checking of deeply recursive generic types.
- Performance: with an annotation the compiler can compare
Foo<A>andFoo<B>by their arguments alone, skipping a structural comparison. - Only on type aliases of object, function, class and interface types. Annotations are not permitted on other aliases (such as plain unions).
- Methods are bivariant by default. Method-syntax members (
put(v: T): void) are checked loosely for historical reasons; property syntax with a function type (put: (v: T) => void) is checked contravariantly understrictFunctionTypes. - Mutable arrays are unsound:
Array<T>is treated covariantly, soCat[]is assignable toAnimal[]even though writes could break it. - Version:
inandouton type parameters were added in TypeScript 4.7.