Variance, Covariance, and Contravariance

The Subtyping Direction Problem

Quick: if Dog extends Animal, can you use Dog[] where Animal[] is expected? What about (x: Dog) => void where (x: Animal) => void is expected? Most developers get at least one of these wrong. The answer depends on variance — the rules that determine how subtyping relationships propagate through generic types. Get this wrong and you introduce unsound type assignments that crash at runtime.

Covariance — Same Direction

A type is covariant in a position when subtyping is preserved in the same direction:

class Animal { name: string = ""; }
class Dog extends Animal { breed: string = ""; }
class Cat extends Animal { indoor: boolean = false; }

// Return types are COVARIANT
// If Dog extends Animal, then () => Dog extends () => Animal
type AnimalFactory = () => Animal;
type DogFactory = () => Dog;

const getDog: DogFactory = () => new Dog();
const getAnimal: AnimalFactory = getDog; // OK — covariant
// Safe: if you expect an Animal and get a Dog, Dog has everything Animal has

Arrays are covariant in TypeScript (readonly arrays are safely covariant):

const dogs: Dog[] = [new Dog()];
const animals: readonly Animal[] = dogs; // OK — reading Dog as Animal is safe

Contravariance — Opposite Direction

This is the one that trips everyone up. A type is contravariant in a position when subtyping goes the opposite direction:

// Function parameters are CONTRAVARIANT (with strictFunctionTypes)
type AnimalHandler = (animal: Animal) => void;
type DogHandler = (dog: Dog) => void;

const handleAnimal: AnimalHandler = (a) => console.log(a.name);
const handleDog: DogHandler = handleAnimal; // OK — contravariant
// Safe: handleAnimal accepts any Animal. Dog is an Animal, so it works.

const handleDogOnly: DogHandler = (d) => console.log(d.breed);
const handleAnimal2: AnimalHandler = handleDogOnly; // ERROR
// Unsafe: handleDogOnly reads .breed, but not every Animal has .breed

// With strictFunctionTypes: false (UNSOUND)
const dogHandler: DogHandler = (d) => console.log(d.breed);
const animalHandler: AnimalHandler = dogHandler; // Allowed — but wrong!
animalHandler(new Cat()); // Runtime crash — Cat doesn't have .breed

// With strictFunctionTypes: true (SOUND)
const animalHandler: AnimalHandler = dogHandler; // ERROR — correctly rejected

The in and out Modifiers (TypeScript 4.7+)

TypeScript 4.7 added explicit variance annotations for generic type parameters:

// out = covariant (output/producer position)
interface Producer<out T> {
  get(): T;
}

// in = contravariant (input/consumer position)
interface Consumer<in T> {
  accept(value: T): void;
}

// in out = invariant (both positions)
interface Transform<in out T> {
  transform(value: T): T;
}

// Error: Type 'T' is not assignable to 'out' position
interface Broken<out T> {
  accept(value: T): void; // ERROR — T is in an 'in' position
  get(): T;               // OK — T is in an 'out' position
}

Variance in Practice

Now let's see where variance actually bites you in real code.

Array Mutability and Variance

// Readonly arrays are safely covariant
const dogs: readonly Dog[] = [new Dog()];
const animals: readonly Animal[] = dogs; // Safe — can only read

// Mutable arrays SHOULD be invariant (but TypeScript makes them covariant)
const dogs2: Dog[] = [new Dog()];
const animals2: Animal[] = dogs2; // TypeScript allows this (unsound!)
animals2.push(new Cat()); // No type error, but dogs2 now contains a Cat!
console.log(dogs2[1].breed); // Runtime crash — Cat doesn't have breed

Generic Class Variance

// Covariant container — only produces T
class Box<out T> {
  constructor(private value: T) {}
  get(): T { return this.value; }
}

const dogBox: Box<Dog> = new Box(new Dog());
const animalBox: Box<Animal> = dogBox; // OK — covariant

// Contravariant handler — only consumes T
class Validator<in T> {
  constructor(private validate: (value: T) => boolean) {}
  check(value: T): boolean { return this.validate(value); }
}

const animalValidator = new Validator<Animal>((a) => a.name.length > 0);
const dogValidator: Validator<Dog> = animalValidator; // OK — contravariant

// Invariant — both produces and consumes T
class State<in out T> {
  constructor(private value: T) {}
  get(): T { return this.value; }
  set(value: T) { this.value = value; }
}

const dogState: State<Dog> = new State(new Dog());
// const animalState: State<Animal> = dogState; // ERROR — invariant

Production Scenario: Event Emitter Variance

// Type-safe event emitter with correct variance
type EventMap = Record<string, unknown>;

// Listener is contravariant in its parameter
type Listener<T> = (data: T) => void;

class TypedEmitter<Events extends EventMap> {
  private handlers = new Map<string, Set<Function>>();

  // T is in an 'in' (contravariant) position for the listener parameter
  on<K extends keyof Events>(event: K, listener: Listener<Events[K]>): void {
    const set = this.handlers.get(event as string) ?? new Set();
    set.add(listener);
    this.handlers.set(event as string, set);
  }

  // T is in an 'in' (contravariant) position for the data parameter
  emit<K extends keyof Events>(event: K, data: Events[K]): void {
    this.handlers.get(event as string)?.forEach(fn => fn(data));
  }
}

interface AppEvents {
  userLogin: { userId: string; timestamp: number };
  error: { message: string; code: number };
}

const emitter = new TypedEmitter<AppEvents>();

// Listener receives exactly the right type
emitter.on("userLogin", (data) => {
  console.log(data.userId); // string — fully typed
});

emitter.emit("error", { message: "fail", code: 500 }); // Type-checked

Challenge: Fix the Variance Bug

// This code has a variance-related bug that compiles but crashes at runtime.
// Find the bug, explain why it happens, and fix it.

class AnimalShelter {
  private animals: Animal[] = [];

  add(animal: Animal) {
    this.animals.push(animal);
  }

  getAll(): Animal[] {
    return this.animals;
  }
}

class DogShelter extends AnimalShelter {
  getDogs(): Dog[] {
    return this.getAll() as Dog[];
  }
}

function addCat(shelter: AnimalShelter) {
  shelter.add(new Cat());
}

const dogShelter = new DogShelter();
dogShelter.add(new Dog());
addCat(dogShelter); // Passes type check — DogShelter extends AnimalShelter
const dogs = dogShelter.getDogs();
console.log(dogs[1].breed); // Runtime crash — dogs[1] is a Cat!

The bug is that DogShelter extends AnimalShelter and is passed to addCat(), which adds a Cat to what's supposed to be a dogs-only collection. The getDogs() cast as Dog[] then lies about the contents.

// Fix: Make DogShelter not extend AnimalShelter, or use generics with proper constraints
class Shelter<T extends Animal> {
  private animals: T[] = [];

  add(animal: T) {
    this.animals.push(animal);
  }

  getAll(): readonly T[] {
    return this.animals;
  }
}

const dogShelter = new Shelter<Dog>();
dogShelter.add(new Dog());
// addCat(dogShelter); // ERROR: Shelter<Dog> is not assignable to Shelter<Animal>
// Because Shelter has T in both in and out positions — it's invariant

// If you need a read-only view:
function readAnimals(shelter: { getAll(): readonly Animal[] }) {
  return shelter.getAll(); // Covariant — safe for reading
}
readAnimals(dogShelter); // OK — only reads, never adds

The fix uses generics where T appears in both input (add) and output (getAll) positions, making Shelter invariant in T. This prevents the unsound substitution.