Variance intuition

Three relationships, one question

Given Dog extends Animal (every Dog is an Animal), variance asks: for a type constructor F<_>, how does F<Dog> relate to F<Animal>?

• Covariant — F<Dog> is assignable to F<Animal> (subtyping flows the same direction). Read-only producers.
• Contravariant — F<Animal> is assignable to F<Dog> (subtyping flows the opposite way). Consumers of input.
• Invariant — neither direction; only exact matches.
• Bivariant — both directions accepted (unsound; TS does this deliberately in one place).

Together these four cases cover every position a type variable can occupy: whether a type constructor produces, consumes, or both determines which direction is safe. The next three sections show each one in real TypeScript, including the case where TS knowingly picks the unsound option.

Why function parameters are contravariant

A function that accepts an Animal can stand in wherever a function accepting a Dog is required — because anything that hands it a Dog is handing it a valid Animal. The reverse is unsafe:

type Animal = { name: string };
type Dog = { name: string; bark(): void };

const feedAnimal = (a: Animal) => a.name;
let feedDog: (d: Dog) => string;

feedDog = feedAnimal; // ok — a Dog IS an Animal, feedAnimal handles it
// the unsafe direction:
let feedAnimal2: (a: Animal) => string;
const handleDog = (d: Dog) => d.bark();
// feedAnimal2 = handleDog;
// Error (under strictFunctionTypes): handleDog needs bark(), but it may
//        be called with a plain Animal that has no bark.

Accepting a wider input is safe; accepting a narrower input than the slot promises is a hole — calling it with the wider value the slot allows would touch members that aren’t there. So standalone function parameters are contravariant.

Why arrays are (unsoundly) covariant

TypeScript treats Array<Dog> as assignable to Array<Animal> even though arrays are mutable — a deliberate, known unsoundness for ergonomics:

const dogs: Dog[] = [{ name: "Rex", bark: () => {} }];
const animals: Animal[] = dogs; // allowed — covariant arrays
animals.push({ name: "Whiskers" }); // pushes a non-Dog into a Dog[]!
dogs[1].bark();
// Runtime: bark is not a function — the type system did not stop us.

A sound system would make the mutable element position invariant. TS chooses covariance because read-heavy array usage dominates and full invariance would be painful. Knowing this hole exists is the senior takeaway.

The bivariant-methods gotcha

Now the hook’s bug. strictFunctionTypes (TS 2.6) makes standalone function-type parameters contravariant — but, by design, it does not apply to method parameters, which stay bivariant. Same-looking declarations behave differently:

// tsconfig: { "strictFunctionTypes": true }
type Handler = (e: Event) => void;

// METHOD syntax — parameter is BIVARIANT (the gotcha):
interface BusMethod {
  on(handler: (e: Event) => void): void;
}
// PROPERTY syntax — parameter is CONTRAVARIANT (checked):
interface BusProp {
  on: (handler: (e: Event) => void) => void;
}

declare const m: BusMethod;
declare const p: BusProp;

const narrow = (e: MouseEvent) => e.button;

m.on(narrow); // ✅ NO ERROR — method param is bivariant (unsound!)
p.on(narrow);
// ❌ Error: '(e: MouseEvent) => number' is not assignable to '(e: Event) => void'
//    Types of parameters 'e' are incompatible:
//    'Event' is missing the properties of 'MouseEvent' (button, ...).

The only difference is method shorthand (on(...)) versus a property holding a function (on: (...) => ...). The method form lets the too-narrow MouseEvent handler through, so when a plain Event is dispatched, e.button is undefined. This is why Array.prototype methods and many DOM/event APIs accept callbacks that are technically too narrow — the bivariance is baked into the method declaration form.

Variance annotations: in / out (TS 4.7)

TS 4.7 lets you state the intended variance of a type parameter with in (contravariant) and out (covariant). The checker then verifies your usage matches — and the annotation also documents intent and can speed up checking:

interface Producer<out T> {  // T only appears in output positions
  get(): T;
}
interface Consumer<in T> {   // T only appears in input positions
  set(value: T): void;
}
interface Box<in out T> {    // T is both read and written → invariant
  get(): T;
  set(value: T): void;
}

// If you annotate `out` but then write T in an input position, you get:
interface Bad<out T> {
  set(value: T): void;
// Error: Type 'T' is declared covariant ('out') but occurs in a
//        contravariant position.  (roughly)
}

Annotations don’t change assignability rules the checker already infers; they let you assert and enforce the variance you intend, catching the mistake of, say, adding a setter to a type you promised was a pure producer.

The numbers and versions behind the holes

Each of these behaviors is pinned to a specific release, and the dates matter when you read a tsconfig or chase a “why did this ever type-check” question. Bivariant method parameters and unsound array covariance predate strict mode entirely. strictFunctionTypes landed in TS 2.6 (Oct 2017) and tightened standalone function-type parameters to contravariant — but by deliberate design left method-shorthand and constructor parameters bivariant, which is the exact hole the hook exploits. Variance annotations in/out arrived in TS 4.7 (May 2022). So a handler bug that slips through a method slot is not a compiler defect to file — it is a nine-year-old, documented tradeoff, and "strictFunctionTypes": false (or the absence of strict: true) silently widens the hole to all function parameters.

The annotations also have a measured performance payoff, which is why large codebases adopt them beyond documentation value. Inferring variance for a deeply recursive generic type is work the checker repeats; stating out T / in T lets it skip that inference and use your declaration directly. The TS team reported variance-annotation and related caching changes cutting structural-comparison time on heavy generic types substantially — on the order of tens of percent of check time on the worst recursive types — which is the difference between a responsive editor and a laggy one on a large schema or a deeply generic ORM type. The annotation is thus three things at once: documentation, a correctness guard against a mis-declared producer/consumer, and a checker hint that can claw back check time.