Skip to content
Tutorials Center
My learning

Topics

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).

TypeScript
interface Producer<out T> { get(): T }
interface Consumer<in T> { accept(value: T): void }

Try it

TypeScript Covariant and contravariant

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 A wrong annotation is caught

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 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> and Foo<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 under strictFunctionTypes.
  • Mutable arrays are unsound: Array<T> is treated covariantly, so Cat[] is assignable to Animal[] even though writes could break it.
  • Version: in and out on type parameters were added in TypeScript 4.7.