What is type variance (covariance and contravariance)?

Question

Accepted Answer

**Variance** describes how subtyping of a composite type relates to subtyping of its parts — i.e. when is `Container_{` assignable to `Container`?

Let `Dog` be a subtype of `Animal`.

## Covariance — preserves direction (the intuitive case)

```ts
let dogs: Dog[] = [];
let animals: Animal[] = dogs; // ✅ Dog[] is assignable to Animal[]
```

Return types and arrays are **covariant**: if `Dog` ⊆ `Animal`, then `Dog[]` ⊆ `Animal[]`. A function returning `Dog` is usable where one returning `Animal` is expected.

## Contravariance — reverses direction (function parameters)

```ts
type Handler = (arg: T) => void;
let animalHandler: Handler = (a) => {};
let dogHandler: Handler = animalHandler; // ✅ (with strictFunctionTypes)
// a handler that accepts ANY Animal can safely handle a Dog
```

Function **parameters** are contravariant: `Handler` is assignable to `Handler`, the *reverse* of the element relationship. This is sound — something that handles all animals certainly handles dogs.

## The unsound default for methods

```ts
// Method parameters in TS are bivariant by default (a known unsound convenience)
interface Comparer { compare(a: T): void; }
```

TypeScript checks standalone function types contravariantly only under `strictFunctionTypes`; method parameters are intentionally **bivariant** for ergonomics, which is technically unsound.

## Why it matters

Variance explains *why* certain assignments are allowed or rejected — why `Dog[]` fits `Animal[]` but a `(d: Dog) => void` callback can't always stand in for a `(a: Animal) => void`.

Understanding it helps you design generic APIs (e.g. read-only vs write positions) and decode confusing "not assignable" errors involving functions and generics.}