Covariance & Contravariance

Also Known As

TL;DR

Explanation

Covariance: if Dog extends Animal, then Dog[] extends Animal[] — arrays are covariant in their element type. Producer types (return positions) are covariant. Contravariance: a function that accepts Animal is assignable to one that accepts Dog — function parameters are contravariant (you can pass a more general handler). TypeScript is structurally typed so variance is checked structurally. Method shorthand syntax (method(): void) is bivariant (both directions) for historical reasons — function property syntax (method: () => void) is strictly contravariant, which is safer. TypeScript 4.7 added explicit variance annotations: in T (contravariant), out T (covariant), in out T (invariant).

Diagram

flowchart LR
    subgraph Covariant
        DA[Dog extends Animal]
        DA --> DA2[Dog array extends Animal array]
    end
    subgraph Contravariant
        FN[fn Animal-void]
        FN --> FN2[assignable to fn Dog-void<br/>reverses direction]
    end
    subgraph Invariant
        INV[ReadWrite T<br/>neither sub nor super]
    end

Watch Out

Common Misconception

Why It Matters

Common Mistakes

• Using method shorthand instead of function property syntax — loses contravariance checking on parameters.
• Mutating a covariant array — Dog[] assignable to Animal[] seems fine until you push a Cat into it via the Animal[] reference.
• Expecting a callback accepting a subtype to be assignable to one accepting a supertype — it's actually the reverse (contravariance).
• Not using in/out variance annotations on generic interfaces where correctness matters.

Avoid When

• Variance annotations are unnecessary for simple non-generic interfaces.

When To Use

• Designing generic interfaces that are clearly producers (out T) or consumers (in T) for safer assignments.
• Library authors ensuring their generic types compose correctly with user-defined subtypes.

Code Examples

// Method shorthand — bivariant (unsound)
interface Processor {
    process(input: Dog): void; // bivariant — accepts Dog or Animal
}

// Mutable covariant array — unsafe
const dogs: Dog[] = [new Dog()];
const animals: Animal[] = dogs;  // OK in TS
animals.push(new Cat());          // Runtime: dogs now contains a Cat!

// Function property — strictly contravariant (safe)
interface Processor {
    process: (input: Dog) => void;
}

// TypeScript 4.7 explicit variance
interface Producer<out T> { get(): T }     // covariant — only produces T
interface Consumer<in T> { set(v: T): void } // contravariant — only consumes T
interface Invariant<in out T> { transform(v: T): T } // invariant

References

• ↗ https://www.typescriptlang.org/docs/handbook/2/generics.html#variance-annotations

Tags

Related Terms