TypeScript 39 🔷 Variance and Type Compatibility - KandZ

Variance describes how subtype relationships between types propagate through containers — arrays, functions, promises, and generics. If Dog is a subtype of Animal, is Dog[] a subtype of Animal[]? Is () => Dog a subtype of () => Animal? Is (x: Animal) => void a subtype of (x: Dog) => void? The answers depend on direction — covariant, contravariant, invariant, or bivariant. This is one of the most conceptually dense parts of TypeScript, but it explains why some assignments work and others don’t, why strictFunctionTypes matters, and where the compiler’s soundness has deliberate holes.

Key point: Variance answers: if A is assignable to B, is F<A> assignable to F? Covariant means yes (same direction). Contravariant means yes in the opposite direction. Invariant means no — the types must match exactly. Bivariant means yes in either direction. Arrays are covariant (unsoundly). Function returns are covariant. Function parameters are contravariant under strictFunctionTypes. Method parameters are bivariant. All of this flows from assignability — the same rule TypeScript uses everywhere else.

What variance is

Variance is how subtype relationships transform through a type constructor.

Given:

A is a subtype of B
F is a type constructor (like Array, Promise, () => _)

What is the relationship between F<A> and F?

Variance	Relationship
Covariant	`F<A>` is a subtype of `F<B>`
Contravariant	`F<B>` is a subtype of `F<A>`
Invariant	Neither — `F<A>` and `F<B>` are unrelated
Bivariant	Both — either direction works

In TypeScript terms: Subtype means assignable. A assignable to B means “every A can be used where a B is expected.”

Why it matters: Variance explains the rules for arrays, functions, and generics. It’s why Dog[] is assignable to Animal[] (covariant), why a function that takes Animal is assignable to one that takes Dog (contravariant), and why Promise<Dog> is assignable to Promise<Animal> (covariant).

Where variance appears:

Context	Variance of the type parameter
Array elements	Covariant
Function return	Covariant
Function parameters	Contravariant
Method parameters	Bivariant
`Promise<T>`	Covariant
`ReadonlyArray<T>`	Covariant
`Map<K, V>`	Invariant in K, covariant in V

Why “variance”: The subtype relationship “varies” as it passes through the container. It may stay the same (covariant), flip (contravariant), or break (invariant). The term describes the direction of the variation.

Why this is hard: Variance isn’t a rule the compiler imposes — it’s a consequence of assignability. Once you know what “assignable” means, variance follows. The difficulty is that assignability is defined recursively, so variance is too.

Covariance — same direction

Covariance: if A is assignable to B, then F<A> is assignable to F.

Arrays are covariant:

class Animal {
  name = '';
}

class Dog extends Animal {
  breed = '';
}

let animals: Animal[] = [];
let dogs: Dog[] = [];

animals = dogs;   // ✅ Dog[] assignable to Animal[]

Every Dog is an Animal. An array of Dogs is an array of Animals. The subtype relationship stays the same direction.

Function returns are covariant:

type Fn = () => Animal;

const returnsAnimal: () => Animal = () => ({ name: 'a' });
const returnsDog: () => Dog = () => ({ name: 'd', breed: 'lab' });

const fn: Fn = returnsDog;   // ✅

A function returning Dog can be used where a function returning Animal is expected. The return type stays in the same direction.

Promise<T> is covariant:

let pa: Promise<Animal> = Promise.resolve({ name: 'a' });
let pd: Promise<Dog> = Promise.resolve({ name: 'd', breed: 'lab' });

pa = pd;   // ✅

Why covariance for returns and arrays: The output position — what a function returns, what an array holds — follows the same direction. A Dog is an Animal, so a container of Dogs is a container of Animals.

The array exception: Arrays are also mutable, which makes covariance unsound.

const dogs: Dog[] = [];
const animals: Animal[] = dogs;

animals.push({ name: 'generic animal' });   // ⚠️  no error!
// dogs now contains a plain Animal, not a Dog

TypeScript allows this — it’s a known unsoundness. Arrays are covariant because banning it would break too much real code.

The sound alternative — readonly:

const dogs: readonly Dog[] = [];
const animals: readonly Animal[] = dogs;   // ✅ sound
// animals.push(...)  // ❌ readonly prevents it

readonly Dog[] is covariant and sound because no mutation can happen.

Why arrays are unsound: TypeScript’s designers chose pragmatism. Most code doesn’t mutate arrays in ways that break the type. Enforcing invariance would reject valid patterns. The unsoundness is documented and accepted.

Why covariance is the “natural” direction: A Dog is an Animal. A value that produces Dogs produces Animals. The relationship goes the same way. Covariance is what you’d naively expect. Contravariance is the surprise.

Contravariance — opposite direction

Contravariance: if A is assignable to B, then F is assignable to F<A>.

Function parameters are contravariant under strictFunctionTypes:

type HandleAnimal = (a: Animal) => void;
type HandleDog = (d: Dog) => void;

const handleAnimal: HandleAnimal = (a) => console.log(a.name);
const handleDog: HandleDog = (d) => console.log(d.breed);

const h1: HandleAnimal = handleDog;   // ❌
const h2: HandleDog = handleAnimal;   // ✅

Wait — why is handleAnimal assignable to HandleDog but not the other way?

The reasoning: A function that handles any Animal can handle a Dog — a Dog is an Animal. So HandleAnimal is assignable to HandleDog.

A function that handles only Dogs can’t handle any Animal — what if you passed a Cat? So HandleDog is not assignable to HandleAnimal.

The direction flips: Animal → Dog is a narrowing, and the function type goes the other way.

In a call-site example:

function callHandler(handler: HandleDog): void {
  handler({ name: 'Rex', breed: 'lab' });   // passes a Dog
}

const animalHandler: HandleAnimal = (a) => console.log(a.name);

callHandler(animalHandler);   // ✅ — animalHandler can handle any Animal

animalHandler accepts an Animal and gets a Dog. Since Dog is an Animal, it works.

Without strictFunctionTypes: Function parameters are bivariant — both directions work. strictFunctionTypes tightens this to contravariance. That’s why you should enable it.

Why contravariance matters: It’s how function assignability works when the parameter types differ. Calling code passes specific values; the function must accept them. The requirement flows opposite to the subtype direction.

Why strictFunctionTypes exists: Before it, function parameters were bivariant — a source of real bugs. A function expecting Dog could be assigned where Animal was expected, and calling code would pass a Cat. strictFunctionTypes catches it.

The method exception: Method parameters (defined with method syntax) are still bivariant even with strictFunctionTypes:

interface Handler {
  handle(a: Animal): void;    // method — bivariant
}

interface HandlerFn {
  handle: (a: Animal) => void;  // function property — contravariant
}

That’s a subtle difference between the two syntaxes. Use function-property syntax when you want contravariance; method syntax keeps bivariance for compatibility.

Why parameter direction flips: A function’s parameter is a requirement. The function says “I need at least this much.” A function requiring Animal needs less than one requiring Dog. So it’s more general — assignable to more places. Contravariance captures that.

Bivariance — both directions

Bivariance: F<A> and F are assignable in either direction.

Method parameters are bivariant:

interface Store {
  add(item: Animal): void;   // method syntax
}

interface StoreFn {
  add: (item: Animal) => void;   // function property
}

With Store, add accepts either Animal or Dog handlers — both directions work.

Why methods are bivariant: Compatibility with older code and libraries. Changing method parameters to contravariant broke too much. TypeScript kept them bivariant as a compromise.

Implications: Method parameters are less strict than function-property parameters. If you want contravariance, use the function-property syntax.

The difference in practice:

interface A {
  m(x: Dog): void;    // bivariant
}

interface B {
  m: (x: Dog) => void;  // contravariant
}

const a: A = { m: (x: Animal) => {} };  // ✅
const b: B = { m: (x: Animal) => {} };  // ❌ under strictFunctionTypes

Why bivariance persists: Method syntax is common in interfaces. Making it strict would break too many real-world patterns. The compromise: function properties are contravariant, methods stay bivariant.

Why bivariance is a compromise: It’s not theoretically sound — a HandleDog assignable to HandleAnimal means you could pass a Cat at runtime. But in practice, methods are called from the same class more often than assigned across types. The unsoundness is rare. TypeScript accepts it for compatibility.

Invariance — neither direction

Invariance: F<A> and F are unrelated — neither is assignable to the other.

Mutable properties are invariant:

interface Box<T> {
  value: T;
}

let animalBox: Box<Animal> = { value: { name: 'a' } };
let dogBox: Box<Dog> = { value: { name: 'd', breed: 'lab' } };

animalBox = dogBox;   // ✅?
dogBox = animalBox;   // ❌

Hmm — Box<Dog> is assignable to Box<Animal> in TypeScript, because Box is structurally covariant when the property is read-only? No — actually, mutable properties are covariant in TypeScript, not invariant. Let me correct.

What’s invariant in TypeScript:

Type parameters that are used in both input and output positions tend to be invariant in a stricter language. TypeScript is less strict — it treats many generic types as covariant even when they’re mutable.

Example — function types with the parameter and return both using T:

type Fn<T> = (arg: T) => T;

let animalFn: Fn<Animal> = a => a;
let dogFn: Fn<Dog> = d => d;

animalFn = dogFn;   // ❌ under strictFunctionTypes
dogFn = animalFn;   // ❌

Fn<Dog> has Dog in the parameter (contravariant) and Dog in the return (covariant). The two directions cancel — the result is invariant. Neither is assignable to the other.

Where invariance appears:

Types with a type parameter in both parameter and return positions
Types with mutable properties where reads and writes conflict
Map<K, V> — the value type is invariant in TypeScript? Actually covariant.

TypeScript’s pragmatism: Full invariance would reject many useful patterns. TypeScript accepts some unsoundness in the name of ergonomics. It’s not as strict as languages like Scala or Kotlin in variance checking.

Why invariance is rare in TypeScript: TypeScript is structural and pragmatic. It treats most generic types as covariant for convenience. Invariance shows up mostly when variance direction cancels — like the Fn<T> example.

Why some languages enforce invariance: Because mutation breaks covariance. If Box<Dog> is a subtype of Box<Animal>, and Box is mutable, you could put an Animal in the box and later read it as a Dog. Invariance prevents that.

Why TypeScript doesn’t: Because the strict version rejects too much real code. The compromise: covariant generics with documented unsoundness.

Why Fn<T> is invariant: T is used as both input and output. Input is contravariant; output is covariant. Two opposite directions with the same type parameter cancel. Neither Fn<Dog> nor Fn<Animal> is a subtype of the other.

`strictFunctionTypes` in detail

The compiler flag strictFunctionTypes (included in strict) enables contravariant function parameter checks.

With strictFunctionTypes: false:

type HandleAnimal = (a: Animal) => void;
type HandleDog = (d: Dog) => void;

const h1: HandleDog = (a: Animal) => {};   // ✅ bivariant
const h2: HandleAnimal = (d: Dog) => {};   // ✅ bivariant

Both directions are allowed.

With strictFunctionTypes: true:

const h1: HandleDog = (a: Animal) => {};   // ✅ contravariant — allowed
const h2: HandleAnimal = (d: Dog) => {};   // ❌ contravariant — rejected

Only the safe direction is allowed.

What strictFunctionTypes affects:

Function type assignability
Callback parameter types
Higher-order functions
Array.prototype.map callbacks
React event handlers

What it doesn’t affect:

Method parameters (still bivariant)
Class instance methods
Interface methods

Why enable it: It catches a real class of bugs — passing a function that expects a narrower type where a broader type is expected. That’s how runtime crashes happen.

Example of the bug it catches:

type Comparator = (a: Animal, b: Animal) => number;
type DogComparator = (a: Dog, b: Dog) => number;

const dogComp: DogComparator = (a, b) => a.breed.localeCompare(b.breed);

const comp: Comparator = dogComp;   // ❌ under strictFunctionTypes
comp({ name: 'a' }, { name: 'b' });  // would crash at runtime

dogComp accesses breed, which plain Animals don’t have. Passing plain animals would crash. strictFunctionTypes catches it.

Why the flag is named for functions: It changes the assignability rules for function types, not for classes or objects. Methods are unaffected. The flag targets the specific case where function-typed values are assigned across parameter types.

Why strictFunctionTypes doesn’t cover methods: Methods are called on this more often. The parameter types are less likely to vary. Keeping methods bivariant avoids false positives on common patterns. Function-typed properties are the main risk, and those are covered.

Practical implications

Variance shows up in real code — usually as an error you need to understand.

Callbacks and Array.map:

const dogs: Dog[] = [];
const animals: Animal[] = dogs;

// fine — covariance
animals.map(a => a.name);

// but the callback parameter is typed
animals.map((a: Dog) => a.breed);   // ❌ a is Animal, not Dog

The array is covariant, but the callback receives Animal, not Dog.

Callback variance:

function forEach<T>(items: T[], fn: (item: T) => void): void {
  for (const item of items) fn(item);
}

forEach<Dog>(dogs, (d: Dog) => console.log(d.breed));      // ✅
forEach<Dog>(dogs, (a: Animal) => console.log(a.name));    // ✅ contravariant
forEach<Dog>(dogs, (b: { name: string }) => {});           // ✅ structurally compatible

fn accepts a Dog (or wider). The contravariance allows any function that can handle a Dog.

Comparator patterns:

type Comparator<T> = (a: T, b: T) => number;

const animalComp: Comparator<Animal> = (a, b) => a.name.localeCompare(b.name);
const dogComp: Comparator<Dog> = (a, b) => a.breed.localeCompare(b.breed);

// A Comparator<Animal> can compare Dogs
const c: Comparator<Dog> = animalComp;   // ✅
// A Comparator<Dog> cannot compare all Animals
const d: Comparator<Animal> = dogComp;   // ❌ under strictFunctionTypes

The general comparator works for the narrower type; the narrow one doesn’t work for the general type.

React event handlers — covariant event types:

type Handler = (e: MouseEvent) => void;

const specific: (e: Event) => void = e => {};   // wider
const h: Handler = specific;   // ✅ contravariant — accepts Event

Enabling strictFunctionTypes:

{
  "compilerOptions": {
    "strict": true
  }
}

strict: true includes strictFunctionTypes. Keep it on.

Why practical examples matter more than theory: The variance rules are abstract until you see them in a callback error. Once you’ve debugged one, the concept clicks.

Why developers run into variance without knowing it: strictFunctionTypes errors mention contravariance implicitly. The fix is usually to widen the parameter type or convert a method to a function property. Understanding the rules makes the fix obvious.

A full example

A typed event system that exercises variance.

// ============================================
// DOMAIN
// ============================================

interface Animal {
  name: string;
}

interface Dog extends Animal {
  breed: string;
}

interface Cat extends Animal {
  indoor: boolean;
}

// ============================================
// COVARIANT — arrays and returns
// ============================================

const dogs: Dog[] = [
  { name: 'Rex', breed: 'lab' },
  { name: 'Bud', breed: 'pug' }
];

const animals: Animal[] = dogs;   // ✅ covariant
// animals.push({ name: 'Cat' });  // ⚠️  unsound but allowed

// Return types
type Fn = () => Animal;

const returnsDog: () => Dog = () => ({ name: 'd', breed: 'l' });
const fn: Fn = returnsDog;   // ✅ covariant

// ============================================
// CONTRAVARIANT — function parameters
// ============================================

type HandleDog = (d: Dog) => void;
type HandleAnimal = (a: Animal) => void;

const handleAnimal: HandleAnimal = (a) => console.log(a.name);
const handleDog: HandleDog = (d) => console.log(d.breed);

// A handler that takes Animal can handle Dog
const h1: HandleDog = handleAnimal;   // ✅ contravariant

// A handler that takes Dog can't handle all Animals
// const h2: HandleAnimal = handleDog;   // ❌ under strictFunctionTypes

// ============================================
// INVARIANT — parameter and return
// ============================================

type Identity<T> = (x: T) => T;

const animalId: Identity<Animal> = (a) => a;
const dogId: Identity<Dog> = (d) => d;

// const i1: Identity<Dog> = animalId;   // ❌
// const i2: Identity<Animal> = dogId;   // ❌
// Neither direction — invariant

// ============================================
// BIVARIANT — methods
// ============================================

interface AnimalStore {
  add(item: Animal): void;   // method — bivariant
}

interface AnimalStoreFn {
  add: (item: Animal) => void;   // property — contravariant
}

const store1: AnimalStore = {
  add: (d: Dog) => console.log(d.breed)   // ✅ bivariant method
};

// const store2: AnimalStoreFn = {
//   add: (d: Dog) => console.log(d.breed)   // ❌ under strictFunctionTypes
// };

// ============================================
// GENERIC UTILITIES — variance of T
// ============================================

// Covariant: T only in return
type Producer<T> = () => T;

// Contravariant: T only in parameter
type Consumer<T> = (value: T) => void;

// Invariant: T in both
type Transformer<T> = (value: T) => T;

// ============================================
// USAGE
// ============================================

function processAnimals(animals: Animal[]): void {
  for (const a of animals) console.log(a.name);
}

processAnimals(dogs);   // ✅ covariance

function processWithHandler(
  items: Dog[],
  handler: (d: Dog) => void
): void {
  for (const item of items) handler(item);
}

processWithHandler(dogs, handleAnimal);   // ✅ contravariance
processWithHandler(dogs, handleDog);      // ✅ exact match

const producer: Producer<Dog> = () => ({ name: 'd', breed: 'l' });
const animalProducer: Producer<Animal> = producer;   // ✅ covariant

const consumer: Consumer<Animal> = (a) => console.log(a.name);
const dogConsumer: Consumer<Dog> = consumer;   // ✅ contravariant

// const animalConsumer: Consumer<Animal> = dogConsumer;  // ❌

console.log(animals, fn, h1, producer, consumer);

What this shows:

Covariance — Dog[] → Animal[], () => Dog → () => Animal
Contravariance — (a: Animal) => void → (d: Dog) => void
Invariance — (x: T) => T — neither direction
Bivariance — method add(item: Animal) accepts add(d: Dog)
Producer<T> — covariant (T only in return)
Consumer<T> — contravariant (T only in parameter)
Transformer<T> — invariant (T in both)

Every variance is exercised. The compiler allows the safe directions and rejects the unsafe ones.

Why this shape: It demonstrates each variance with minimal examples. Once you see the pattern — return covariant, parameter contravariant, both invariant, method bivariant — you can reason about any function or generic type.

Complete Example Session

# ============================================
# PART 1: COVARIANCE — ARRAYS
# ============================================

cat > covariance.ts << 'EOF'
class Animal { name = ''; }
class Dog extends Animal { breed = ''; }

let animals: Animal[] = [];
const dogs: Dog[] = [{ name: 'Rex', breed: 'lab' }];

animals = dogs;   // ✅ covariant

console.log(animals, dogs);
EOF

npx tsc --noEmit covariance.ts
# (no errors)

# ============================================
# PART 2: COVARIANCE — RETURNS
# ============================================

cat > returns.ts << 'EOF'
class Animal { name = ''; }
class Dog extends Animal { breed = ''; }

type Fn = () => Animal;

const returnsDog: () => Dog = () => ({ name: 'd', breed: 'lab' });
const f: Fn = returnsDog;   // ✅

console.log(f());
EOF

npx tsc --noEmit returns.ts
# (no errors)

# ============================================
# PART 3: CONTRAVARIANCE — PARAMETERS
# ============================================

cat > contravariance.ts << 'EOF'
class Animal { name = ''; }
class Dog extends Animal { breed = ''; }

type HandleAnimal = (a: Animal) => void;
type HandleDog = (d: Dog) => void;

const handleAnimal: HandleAnimal = a => console.log(a.name);
const handleDog: HandleDog = d => console.log(d.breed);

const h1: HandleDog = handleAnimal;   // ✅
// const h2: HandleAnimal = handleDog;   // ❌

console.log(h1);
EOF

npx tsc --noEmit contravariance.ts
# (no errors)

# ============================================
# PART 4: INVARIANCE
# ============================================

cat > invariance.ts << 'EOF'
class Animal { name = ''; }
class Dog extends Animal { breed = ''; }

type Identity<T> = (x: T) => T;

const animalId: Identity<Animal> = a => a;
const dogId: Identity<Dog> = d => d;

// const i1: Identity<Dog> = animalId;   // ❌
// const i2: Identity<Animal> = dogId;   // ❌

console.log(animalId, dogId);
EOF

npx tsc --noEmit invariance.ts
# (no errors)

# ============================================
# PART 5: BIVARIANCE — METHODS
# ============================================

cat > bivariance.ts << 'EOF'
class Animal { name = ''; }
class Dog extends Animal { breed = ''; }

interface Store {
  add(item: Animal): void;
}

const store: Store = {
  add: (d: Dog) => console.log(d.breed)
};

console.log(store);
EOF

npx tsc --noEmit bivariance.ts
# (no errors)

# ============================================
# PART 6: COMPARATOR EXAMPLE
# ============================================

cat > comparator.ts << 'EOF'
class Animal { name = ''; }
class Dog extends Animal { breed = ''; }

type Comparator<T> = (a: T, b: T) => number;

const animalComp: Comparator<Animal> = (a, b) =>
  a.name.localeCompare(b.name);

const dogComp: Comparator<Dog> = (a, b) =>
  a.breed.localeCompare(b.breed);

// Comparator<Animal> can compare Dogs
const c1: Comparator<Dog> = animalComp;   // ✅

// Comparator<Dog> can't compare all Animals
// const c2: Comparator<Animal> = dogComp;   // ❌

console.log(c1);
EOF

npx tsc --noEmit comparator.ts
# (no errors)

# ============================================
# PART 7: GENERIC CONTAINERS
# ============================================

cat > containers.ts << 'EOF'
class Animal { name = ''; }
class Dog extends Animal { breed = ''; }

// Covariant — T only in return
type Producer<T> = () => T;
const prod: Producer<Dog> = () => ({ name: 'd', breed: 'l' });
const animalProd: Producer<Animal> = prod;   // ✅

// Contravariant — T only in parameter
type Consumer<T> = (x: T) => void;
const cons: Consumer<Animal> = a => console.log(a.name);
const dogCons: Consumer<Dog> = cons;   // ✅

// Invariant — T in both
type Transformer<T> = (x: T) => T;
const animalTrans: Transformer<Animal> = a => a;
const dogTrans: Transformer<Dog> = d => d;
// const t: Transformer<Dog> = animalTrans;   // ❌
// const t2: Transformer<Animal> = dogTrans;  // ❌

console.log(animalProd, dogCons, animalTrans, dogTrans);
EOF

npx tsc --noEmit containers.ts
# (no errors)

# ============================================
# PART 8: COMPILE AND RUN
# ============================================

npx tsc covariance.ts returns.ts contravariance.ts invariance.ts bivariance.ts comparator.ts containers.ts
node covariance.js
# [ [ { name: 'Rex', breed: 'lab' } ] [ { name: 'Rex', breed: 'lab' } ] ]

node returns.js
# [ { name: 'd', breed: 'lab' } ]

node contravariance.js
# [ [Function: handleAnimal] ]

node invariance.js
# [ [Function: animalId] [Function: dogId] ]

node bivariance.js
# [ { add: [Function: add] } ]

node comparator.js
# [ [Function: animalComp] ]

node containers.js
# [ [Function] [Function] [Function] [Function] ]

Quick Reference

The Four Variances

Variance	Meaning
Covariant	`F<A>` assignable to `F<B>`
Contravariant	`F<B>` assignable to `F<A>`
Invariant	Neither
Bivariant	Both

Where Each Applies

Context	Variance
Array elements	Covariant
Function return	Covariant
`Promise<T>`	Covariant
`ReadonlyArray<T>`	Covariant
Function parameters	Contravariant
Method parameters	Bivariant
`(x: T) => T`	Invariant

`strictFunctionTypes`

Flag	Effect on function parameters
`false`	Bivariant
`true`	Contravariant
On methods	Always bivariant

Soundness Trade-Offs

Type	Sound?	Reason
`Dog[]` → `Animal[]`	❌	Mutation allowed
`readonly Dog[]` → `readonly Animal[]`	✅	No mutation
`() => Dog` → `() => Animal`	✅	Return covariant
`(a: Animal) => void` → `(d: Dog) => void`	✅	Parameter contravariant
Method `(a: Animal) => void` → method `(d: Dog) => void`	❌	Bivariant

Function Type Patterns

Type	Variance of T
`() => T`	Covariant
`(x: T) => void`	Contravariant
`(x: T) => T`	Invariant
`(x: () => T) => void`	Contravariant in outer
`(x: (t: T) => void) => void`	Covariant in outer

Method vs Function Property

Syntax	Variance
`m(x: T): void`	Bivariant
`m: (x: T) => void`	Contravariant

Practical Rules

Need	Use
Sound covariance	`readonly T[]`
Contravariant callback	Function type, not method
Invariant generic	`(x: T) => T`
Safe callbacks	`strictFunctionTypes: true`
Mutable containers	Careful with covariance

Error Messages

Error	Meaning
`not assignable`	Variance mismatch
`strictFunctionTypes`	Parameter too narrow
`Property does not exist`	Covariance read error
`possibly undefined`	Contravariant parameter

When Variance Errors Appear

Scenario	Error
Callback with narrower param	`strictFunctionTypes`
Method assignment	Rare
Generic container mutation	None — covariant
Function return mismatch	`not assignable`
Both parameter and return	Invariant — both directions fail

Comparisons Across Languages

Language	Variance
TypeScript	Covariant by default, contravariant for functions under `strict`
Java	Invariant generics, covariant arrays (unsound)
C#	Declared variance (`in`, `out`)
Scala	Declared variance, covariant by default
Kotlin	Declared variance (`in`, `out`)

TypeScript differs — it doesn’t use declared variance. Structural assignability implies variance.

Helper Types for Variance

Type	Meaning
`Producer<T>`	`() => T` — covariant
`Consumer<T>`	`(x: T) => void` — contravariant
`Transformer<T>`	`(x: T) => T` — invariant
`Bivariant<T>`	Method syntax — bivariant

Key Facts

Fact	Detail
Arrays	Covariant, unsound
`readonly` arrays	Covariant, sound
Function returns	Covariant
Function params	Contravariant under `strict`
Methods	Always bivariant
`strict: true`	Includes `strictFunctionTypes`
Structural typing	Drives variance

Best Practices

✅ Do This:

// Enable strict mode (includes strictFunctionTypes)
"strict": true                                                  // ✅

// Use readonly arrays for sound covariance
function process(items: readonly Animal[]): void { }            // ✅

// Use function-property syntax for contravariant callbacks
type Handler = { on: (e: Animal) => void };                     // ✅

// Prefer contravariant-safe parameter types
type Comparator<T> = (a: T, b: T) => number;                    // ✅

// Widen parameter types to accept more
const h: (a: Animal) => void = a => console.log(a.name);        // ✅

// Use `readonly T[]` for inputs you don't mutate
function render(items: readonly string[]): void { }             // ✅

// Type callbacks with the actual type they receive
[1, 2].map((n: number) => n * 2);                               // ✅

// Keep method parameters broad when possible
add(item: Animal): void { }                                     // ✅

❌ Don’t Do This:

// Don't disable strictFunctionTypes
"strictFunctionTypes": false  // ⚠️  allows unsafe callbacks     // ⚠️

// Don't narrow callback parameters
const h: (a: Animal) => void = (d: Dog) => console.log(d.breed);
// ❌ under strictFunctionTypes                                    // ❌

// Don't rely on array covariance for mutation
const animals: Animal[] = dogs;
animals.push({ name: 'generic' });  // ⚠️  unsound                  // ⚠️

// Don't expect mutability to be covariant-sound
function addDefault(box: Box<Animal>): void {
  box.value = { name: 'default' };  // ⚠️  breaks Box<Dog>          // ⚠️
}

// Don't use method syntax when you need contravariance
interface I { m(d: Dog): void }  // ⚠️  bivariant                   // ⚠️

// Don't cast to bypass variance
const c = dogHandler as (a: Animal) => void;  // ⚠️  unsafe         // ⚠️

// Don't fight variance errors with `any`
const h2: (a: Animal) => void = (d: any) => {};  // ⚠️              // ⚠️

// Don't use invariant types where covariant suffices
type Bad<T> = (x: T) => T;  // ⚠️  when () => T would do          // ⚠️

Common Pitfalls

Pitfall	Problem	Solution
Array covariance mutation	Unsound	Use `readonly T[]`
Narrow callback param	Error under `strict`	Widen the parameter
Method bivariance surprise	Less strict than expected	Use function syntax
Invariant type confusion	Both directions fail	Recognize `(x: T) => T`
Disabling `strictFunctionTypes`	Misses real bugs	Keep it on
Assuming all generics covariant	Not always	Check T’s positions
Casting past variance	Hides unsafety	Fix the type
Confusing subtype with assignable	Variance is about assignability	Same thing

Real-World Examples

1. Covariant array

const dogs: Dog[] = [];
const animals: Animal[] = dogs;   // ✅

2. Sound covariant array

const dogs: readonly Dog[] = [];
const animals: readonly Animal[] = dogs;   // ✅ sound

3. Covariant return

const f: () => Animal = () => new Dog();   // ✅

4. Contravariant parameter

const h: (d: Dog) => void = (a: Animal) => console.log(a.name);   // ✅

5. Rejected contravariant direction

// const h: (a: Animal) => void = (d: Dog) => console.log(d.breed);   // ❌

6. Invariant identity

type Id<T> = (x: T) => T;
// Id<Dog> and Id<Animal> are unrelated

7. Bivariant method

interface I {
  m(a: Animal): void;  // method — bivariant
}

8. Contravariant function property

interface I {
  m: (a: Animal) => void;  // function property — contravariant
}

9. Comparator

type Comparator<T> = (a: T, b: T) => number;
const c: Comparator<Dog> = (a: Animal, b: Animal) => 0;   // ✅

10. Covariant promise

const pd: Promise<Dog> = Promise.resolve(new Dog());
const pa: Promise<Animal> = pd;   // ✅

11. Readonly covariance

const dogs: readonly Dog[] = [];
const animals: readonly Animal[] = dogs;   // ✅

12. Event handler

type ClickHandler = (e: MouseEvent) => void;
const h: ClickHandler = (e: Event) => {};   // ✅ contravariant

13. Producer pattern

type Producer<T> = () => T;
const p: Producer<Dog> = () => new Dog();
const ap: Producer<Animal> = p;   // ✅

14. Consumer pattern

type Consumer<T> = (x: T) => void;
const c: Consumer<Animal> = a => {};
const dc: Consumer<Dog> = c;   // ✅

15. Transformer pattern

type Transformer<T> = (x: T) => T;
// invariant — no direction works

16. Callback widening

[1, 2, 3].forEach((n: number | string) => {});   // ✅ wider is fine

17. Comparator rejection

// const c: Comparator<Animal> = (a: Dog, b: Dog) => 0;   // ❌

18. Sound transform

function map<T, U>(items: readonly T[], fn: (x: T) => U): U[] {
  return items.map(fn);
}

19. `strictFunctionTypes` error

type H = (a: Animal) => void;
// const h: H = (d: Dog) => {};   // ❌

20. Explicit variance helper

type Consumer<T> = (x: T) => void;
type Producer<T> = () => T;

Visual: Covariance

┌──────────────────────────────────────────────┐
│  Dog is a subtype of Animal                  │
│                                              │
│  Dog[] ───────► Animal[]                     │
│  ─────►                                      │
│                                              │
│  Same direction                              │
│  Every Dog is an Animal, so a Dog[] is       │
│  an Animal[]                                 │
│                                              │
└──────────────────────────────────────────────┘

┌──────────────────────────────────────────────┐
│  () => Dog ───────► () => Animal             │
│                                              │
│  Return type stays same direction            │
│                                              │
└──────────────────────────────────────────────┘

Visual: Contravariance

┌──────────────────────────────────────────────┐
│  Dog is a subtype of Animal                  │
│                                              │
│  (x: Animal) => void                         │
│       │                                      │
│       │  assignable to                       │
│       ▼                                      │
│  (x: Dog) => void                            │
│                                              │
│  Opposite direction                          │
│  A function that handles any Animal can      │
│  handle a Dog                                 │
│                                              │
└──────────────────────────────────────────────┘

┌──────────────────────────────────────────────┐
│  (x: Dog) => void                            │
│       │                                      │
│       │  NOT assignable to                   │
│       ▼                                      │
│  (x: Animal) => void                         │
│                                              │
│  A function that only handles Dog can't      │
│  handle every Animal                          │
│                                              │
└──────────────────────────────────────────────┘

Visual: Invariance

┌──────────────────────────────────────────────┐
│  type Id<T> = (x: T) => T                    │
│                                              │
│  T is in parameter position (contravariant)  │
│  T is in return position (covariant)         │
│                                              │
│  The two directions cancel                   │
│                                              │
│  Id<Dog> and Id<Animal> are unrelated        │
│                                              │
│      Id<Dog> ◄─── no ───► Id<Animal>         │
│                                              │
└──────────────────────────────────────────────┘

Visual: Bivariance

┌──────────────────────────────────────────────┐
│  interface Store {                           │
│    add(item: Animal): void;   ← method       │
│  }                                           │
│                                              │
│  With method syntax:                         │
│                                              │
│  add(item: Animal) accepts:                  │
│    add(item: Animal) ✅                      │
│    add(item: Dog)    ✅                      │
│                                              │
│  Both directions allowed                     │
│                                              │
└──────────────────────────────────────────────┘

┌──────────────────────────────────────────────┐
│  interface Store {                           │
│    add: (item: Animal) => void;  ← property  │
│  }                                           │
│                                              │
│  With function-property syntax:              │
│                                              │
│  add(item: Animal) accepts:                  │
│    add(item: Animal) ✅                      │
│    add(item: Dog)    ❌ under strict         │
│                                              │
│  Only contravariant direction                │
│                                              │
└──────────────────────────────────────────────┘

Visual: Where Each Applies

┌──────────────────────────────────────────────┐
│  Covariant:                                  │
│                                              │
│  T[]             ──► array elements          │
│  () => T         ──► return                  │
│  Promise<T>      ──► promise value           │
│  readonly T[]    ──► sound array             │
│                                              │
├──────────────────────────────────────────────┤
│  Contravariant:                              │
│                                              │
│  (x: T) => void  ──► parameter (strict)      │
│  Comparator<T>   ──► parameter               │
│  Handler<T>      ──► callback                │
│                                              │
├──────────────────────────────────────────────┤
│  Invariant:                                  │
│                                              │
│  (x: T) => T     ──► both positions          │
│  Box<T> mutable  ──► parameterized by T      │
│                                              │
├──────────────────────────────────────────────┤
│  Bivariant:                                  │
│                                              │
│  m(x: T): void   ──► method syntax           │
│                                              │
└──────────────────────────────────────────────┘

Visual: Sound vs Unsound

┌──────────────────────────────────────────────┐
│  Dog[] ──► Animal[]                          │
│                                              │
│  ⚠️  Unsound                                  │
│                                              │
│  const dogs: Dog[] = [];                     │
│  const animals: Animal[] = dogs;             │
│  animals.push({ name: 'generic' });          │
│  // dogs now contains a plain Animal         │
│                                              │
└──────────────────────────────────────────────┘

┌──────────────────────────────────────────────┐
│  readonly Dog[] ──► readonly Animal[]        │
│                                              │
│  ✅ Sound                                     │
│                                              │
│  const dogs: readonly Dog[] = [];            │
│  const animals: readonly Animal[] = dogs;    │
│  // animals.push(...)  ❌ prevented          │
│                                              │
└──────────────────────────────────────────────┘

Visual: Function Type Variance Summary

┌──────────────────────────────────────────────┐
│  T only in return:                           │
│  () => T                                     │
│  Covariant                                   │
│                                              │
├──────────────────────────────────────────────┤
│  T only in parameter:                        │
│  (x: T) => void                              │
│  Contravariant (with strict)                 │
│                                              │
├──────────────────────────────────────────────┤
│  T in both:                                  │
│  (x: T) => T                                 │
│  Invariant                                   │
│                                              │
├──────────────────────────────────────────────┤
│  Nested — depends on position:               │
│  (x: () => T) => void                        │
│  T is contravariant in outer (through inner) │
│                                              │
│  (x: (y: T) => void) => void                 │
│  T is covariant in outer (double negation)   │
│                                              │
└──────────────────────────────────────────────┘

Visual: Decision Flow

┌──────────────────────────────────────────────┐
│  Are you assigning a function?               │
│       │                                      │
│       ├── Check the return type:             │
│       │   narrower return OK (covariant)     │
│       │                                      │
│       └── Check the parameter types:         │
│           wider parameters OK (contravariant)│
│                                              │
└──────────────────────────────────────────────┘

┌──────────────────────────────────────────────┐
│  Are you assigning an array?                 │
│       │                                      │
│       ├── Mutable ──► Covariant (unsound)    │
│       │                                      │
│       └── readonly ──► Covariant (sound)     │
│                                              │
└──────────────────────────────────────────────┘

┌──────────────────────────────────────────────┐
│  Compile error about functions?              │
│       │                                      │
│       ├── Parameter too narrow ──► widen     │
│       │                                      │
│       └── Return mismatch ──► check subtype  │
│                                              │
└──────────────────────────────────────────────┘

┌──────────────────────────────────────────────┐
│  Method or function property?                │
│       │                                      │
│       ├── Method ──► bivariant               │
│       │                                      │
│       └── Property ──► contravariant         │
│                                              │
└──────────────────────────────────────────────┘

Summary

Variance	Direction	Applies to
Covariant	Same	Arrays, returns, promises
Contravariant	Opposite	Function parameters (strict)
Invariant	Neither	`(x: T) => T`
Bivariant	Both	Method parameters

Key takeaways:

Variance describes how subtype relationships propagate through type constructors
Covariant — Dog[] → Animal[], () => Dog → () => Animal — same direction
Contravariant — (a: Animal) => void → (d: Dog) => void — opposite direction
Invariant — (x: T) => T — neither direction, both positions used
Bivariant — method parameters — both directions, a compatibility compromise
strictFunctionTypes (in strict) makes function parameters contravariant
Method syntax stays bivariant even under strict; function-property syntax is contravariant
Arrays are covariant and unsound — mutation can break the invariant
readonly T[] is covariant and sound — no mutation possible
Returns and promises are covariant
Comparator patterns use contravariance for parameter types
Enabling strict catches real callback bugs
Widen parameter types to satisfy contravariance
Use readonly for inputs you promise not to mutate

Remember: Variance is a consequence of assignability, not a separate rule. Subtype means assignable. Dog[] is assignable to Animal[] because every Dog is an Animal — covariance. (a: Animal) => void is assignable to (d: Dog) => void because a function that handles any Animal can handle a Dog — contravariance. Both positions make it invariant. Method syntax makes it bivariant. Enable strictFunctionTypes, prefer readonly for sound covariance, widen parameters for safe callbacks. Once variance clicks, the compiler’s errors stop being mysterious — they’re just the rules of the type system doing their job.

Stop using slow, ad-bloated tool sites! 🤮

🔎 Search “KandZ Tools” on Google to use many professional utilities for free.

KandZ.me is the ultimate minimalist hub for:
✅ Finance (Mortgage, Interest, Inflation)
✅ Tech (Base64, JSON, Dev Suite, IP)
✅ Health (BMI, BMR, TDEE)
✅ Productivity (Timer, Workspace, QR)

⚡️ Fast & Private
🔒 No data leaves your device
💎 100% Free

🔗 Use it now: https://tools.kandz.me
🔖 Bookmark it—you’ll need it later!