Strict Mode Isn't Enough: Using TypeScript's New Variance Annotations to Catch Subtle Generic Bugs

Most TypeScript teams enable strict mode and assume their type safety problems are solved. The reality is that strict mode catches obvious errors like null checks and implicit any types, but completely misses a class of bugs related to generic variance. These bugs manifest as runtime type violations that the compiler should have prevented but didn't.

The variance problem affects any codebase using generics for containers, event systems, or state management. Developers write code that looks correct, passes type checking, and then fails in production when a string array gets assigned where a readonly string array should be, or when an event handler accepts the wrong payload type.

TypeScript 4.7 introduced variance annotations (in and out) to address this gap. These annotations give developers explicit control over how generic types can be substituted, catching bugs that strict mode ignores. The difference between code with and without proper variance annotations isn't subtle—it's the difference between catching type errors at compile time versus discovering them in production.

Understanding Variance: Covariance, Contravariance, and Invariance

Variance describes how generic types relate when their type parameters are substituted. Three relationships exist: covariance (substituting more specific types), contravariance (substituting less specific types), and invariance (no substitution allowed).

The mental model that works: covariance flows down the type hierarchy, contravariance flows up, and invariance stays locked. When a generic type parameter appears in output positions (return types, readonly properties), it's naturally covariant. When it appears in input positions (function parameters, writable properties), it's naturally contravariant.

flowchart TD
    Animal["Animal (base type)"]
    Dog["Dog (specific type)"]
    Cat["Cat (specific type)"]
    
    Animal --> Dog
    Animal --> Cat
    
    CovariantBox["Covariant: Box&lt;out T&gt;<br/>Accepts Dog where Animal expected"]
    ContravariantBox["Contravariant: Handler&lt;in T&gt;<br/>Accepts Animal where Dog expected"]
    InvariantBox["Invariant: Store&lt;T&gt;<br/>Requires exact type match"]
    
    style CovariantBox fill:#0b3b2e,stroke:#34d399,color:#d1fae5
    style ContravariantBox fill:#2a1840,stroke:#c084fc,color:#f3e8ff
    style InvariantBox fill:#3a2f0b,stroke:#fbbf24,color:#fef3c7

Without explicit variance annotations, TypeScript infers variance based on how type parameters are used. This inference works for simple cases but breaks down with complex generic types that use their parameters in multiple positions. The compiler makes conservative assumptions that allow unsafe code to pass type checking.

The practical consequence: developers write generic utilities that compile without errors but fail type safety at runtime. A container type that should only allow reading becomes writable. An event handler that should accept any event type becomes locked to a specific subtype.

Real-World Bug: The Array Assignment Problem

Consider this common pattern in React applications managing form state:

interface FormField {
  value: string;
  error?: string;
}
 
interface SelectField extends FormField {
  options: string[];
}
 
// This compiles but is unsafe
function updateFields(fields: FormField[]) {
  fields.push({ value: '', error: undefined });
}
 
const selectFields: SelectField[] = [
  { value: 'option1', error: undefined, options: ['a', 'b'] }
];
 
// Type checks pass, runtime fails
updateFields(selectFields); // Adds FormField without options property
console.log(selectFields[1].options.length); // Runtime error: Cannot read property 'length' of undefined

The bug occurs because TypeScript treats FormField[] as covariant by default. It allows passing SelectField[] where FormField[] is expected, even though the function modifies the array. The compiler should reject this code because the function accepts a writable array parameter, which requires contravariance, not covariance.

Strict mode doesn't help here. The types are all explicitly declared, no implicit any exists, and strict null checks pass. The problem is structural: the compiler lacks information about how the generic type parameter should vary.

This pattern appears everywhere: state management libraries accepting action arrays, validation functions processing field collections, and data transformation pipelines working with heterogeneous lists. Each instance creates a potential runtime failure that strict mode silently allows.

TypeScript's New 'in' and 'out' Variance Annotations

Variance annotations solve the problem by letting developers declare their intent explicitly. The out modifier marks covariant positions (output-only), and the in modifier marks contravariant positions (input-only).

// Explicitly covariant: can only read from T
interface ReadonlyBox<out T> {
  readonly value: T;
  get(): T;
}
 
// Explicitly contravariant: can only write to T
interface WriteableBox<in T> {
  set(value: T): void;
  update(fn: (prev: T) => T): void;
}
 
// Invariant: both reads and writes
interface Box<T> {
  value: T;
  get(): T;
  set(value: T): void;
}
 
// Now the compiler catches the bug
interface Animal { name: string; }
interface Dog extends Animal { breed: string; }
 
const dogBox: ReadonlyBox<Dog> = { value: { name: 'Max', breed: 'Labrador' }, get: () => ({ name: 'Max', breed: 'Labrador' }) };
const animalBox: ReadonlyBox<Animal> = dogBox; // Valid: covariance allowed for readonly
 
const dogWriter: WriteableBox<Dog> = {
  set: (d) => console.log(d.breed),
  update: (fn) => console.log(fn({ name: 'Max', breed: 'Labrador' }).breed)
};
 
// Error: Type 'WriteableBox<Dog>' is not assignable to type 'WriteableBox<Animal>'
const animalWriter: WriteableBox<Animal> = dogWriter;

The annotations force the compiler to verify that types are used correctly. A ReadonlyBox<out T> cannot have methods that accept T as a parameter—only return it. A WriteableBox<in T> cannot have methods that return T—only accept it. Attempting to mix these patterns produces a compile error.

The key insight: variance annotations don't change runtime behavior. They add compile-time constraints that prevent unsafe code from being written in the first place. Teams adopting this pattern catch bugs during development instead of in production.

Variance Annotations vs Traditional Type Guards

Traditional type guards and variance annotations solve different problems. Type guards validate values at runtime; variance annotations validate generic type relationships at compile time.

flowchart LR
    subgraph TypeGuards["Type Guards: runtime validation"]
        Input1["Unknown value"] --> Guard1["isString(value)"]
        Guard1 --> Output1["Narrowed type"]
    end
    
    subgraph VarianceAnnotations["Variance Annotations: compile-time validation"]
        Input2["Generic type"] --> Annotation["Box<out T>"]
        Annotation --> Output2["Enforced usage"]
    end
    
    TypeGuards --> Runtime["Catches: wrong values"]
    VarianceAnnotations --> CompileTime["Catches: wrong type relationships"]
    
    style Guard1 fill:#142544,stroke:#7c9cf0,color:#eaf2ff
    style Annotation fill:#0b3b2e,stroke:#34d399,color:#d1fae5
    style Runtime fill:#450a0a,stroke:#ef4444,color:#fca5a5
    style CompileTime fill:#0b3b2e,stroke:#34d399,color:#d1fae5

The comparison matters because developers often reach for type guards when variance annotations are the correct tool. Consider this event system:

// Without variance: type guards needed everywhere
interface Event { type: string; }
interface ClickEvent extends Event { x: number; y: number; }
 
function isClickEvent(e: Event): e is ClickEvent {
  return e.type === 'click';
}
 
function handleEvent(e: Event) {
  if (isClickEvent(e)) {
    console.log(e.x, e.y); // Type guard required
  }
}
 
// With variance: type relationships enforced
interface EventHandler<in T extends Event> {
  handle(event: T): void;
}
 
const clickHandler: EventHandler<ClickEvent> = {
  handle: (e) => console.log(e.x, e.y)
};
 
// Error: cannot pass specific handler where general handler expected
const generalHandler: EventHandler<Event> = clickHandler;

Type guards still have their place for validating external data or discriminated unions. But for generic container types, collection processors, and callback systems, variance annotations provide stronger guarantees with less code.

Practical Pattern: Building Type-Safe Event Emitters

Event emitters demonstrate why variance annotations matter in real applications. The typical implementation allows subscribing handlers for specific event types but lacks proper variance constraints.

// Unsafe event emitter without variance
class UnsafeEmitter<T> {
  private handlers: Array<(event: T) => void> = [];
  
  on(handler: (event: T) => void) {
    this.handlers.push(handler);
  }
  
  emit(event: T) {
    this.handlers.forEach(h => h(event));
  }
}
 
interface BaseEvent { timestamp: number; }
interface ErrorEvent extends BaseEvent { error: Error; }
 
const emitter = new UnsafeEmitter<BaseEvent>();
const errorEmitter: UnsafeEmitter<ErrorEvent> = emitter; // Unsafe but compiles
errorEmitter.on(e => console.log(e.error.message)); // Expects ErrorEvent
emitter.emit({ timestamp: Date.now() }); // Runtime error: e.error is undefined

The fix uses variance annotations to encode the correct relationships:

// Type-safe emitter with variance
class EventEmitter<out TEmit, in TSubscribe = TEmit> {
  private handlers: Array<(event: TEmit) => void> = [];
  
  on(handler: (event: TSubscribe) => void) {
    this.handlers.push(handler as (event: TEmit) => void);
  }
  
  emit(event: TEmit) {
    this.handlers.forEach(h => h(event));
  }
}
 
const safeEmitter = new EventEmitter<ErrorEvent, BaseEvent>();
 
// Valid: handler accepts any BaseEvent (contravariant)
safeEmitter.on((e: BaseEvent) => console.log(e.timestamp));
 
// Valid: emitting specific ErrorEvent (covariant)
safeEmitter.emit({ timestamp: Date.now(), error: new Error('failed') });
 
// Error caught at compile time
const generalEmitter: EventEmitter<BaseEvent> = new EventEmitter<ErrorEvent>();

flowchart TD
    Emit["emit(event: TEmit)<br/>Covariant position"] --> EmitCheck{Can substitute<br/>more specific?}
    EmitCheck -->|Yes| EmitValid["ErrorEvent → BaseEvent ✓"]
    EmitCheck -->|No| EmitInvalid["BaseEvent → ErrorEvent ✗"]
    
    Subscribe["on(handler: TSubscribe)<br/>Contravariant position"] --> SubCheck{Can substitute<br/>less specific?}
    SubCheck -->|Yes| SubValid["BaseEvent → ErrorEvent ✓"]
    SubCheck -->|No| SubInvalid["ErrorEvent → BaseEvent ✗"]
    
    EmitValid --> SafeEmit["Type-safe emission"]
    SubValid --> SafeSub["Type-safe subscription"]
    
    style EmitInvalid fill:#450a0a,stroke:#ef4444,color:#fca5a5
    style SubInvalid fill:#450a0a,stroke:#ef4444,color:#fca5a5
    style SafeEmit fill:#0b3b2e,stroke:#34d399,color:#d1fae5
    style SafeSub fill:#0b3b2e,stroke:#34d399,color:#d1fae5

This pattern extends to any pub-sub system, callback registry, or observer implementation. The variance annotations ensure that handlers can be general (accepting base types) while emissions can be specific (sending derived types), preventing the runtime errors that plague unsafe implementations.

When to Use Variance Annotations in Production Code

Variance annotations belong in library code and shared utilities where generic types define contracts between modules. Application code rarely needs explicit annotations unless it defines reusable generic abstractions.

flowchart TD
    Decision{Does type appear in<br/>library/shared code?}
    Decision -->|Yes| CheckUsage{How is T used?}
    Decision -->|No| Skip["Skip annotations<br/>Use inferred variance"]
    
    CheckUsage -->|Output only| UseOut["Add 'out' modifier<br/>ReadonlyBox&lt;out T&gt;"]
    CheckUsage -->|Input only| UseIn["Add 'in' modifier<br/>Handler&lt;in T&gt;"]
    CheckUsage -->|Both| Invariant["Leave unmodified<br/>Invariant by default"]
    
    UseOut --> Validate["Verify: no T in parameters"]
    UseIn --> Validate2["Verify: no T in returns"]
    
    style Decision fill:#142544,stroke:#7c9cf0,color:#eaf2ff
    style UseOut fill:#0b3b2e,stroke:#34d399,color:#d1fae5
    style UseIn fill:#2a1840,stroke:#c084fc,color:#f3e8ff
    style Invariant fill:#3a2f0b,stroke:#fbbf24,color:#fef3c7

The decision tree for when to add annotations:

1. Container types: Always annotate. Arrays, sets, maps, and custom collections need explicit variance to prevent the assignment bugs shown earlier.

2. Callback systems: Always annotate. Event handlers, observers, and middleware processors must declare whether they're covariant (emitting) or contravariant (subscribing).

3. State managers: Annotate selectively. Read-only state should be covariant, write-only actions should be contravariant, and read-write state should stay invariant.

4. Domain models: Rarely annotate. Business logic types typically don't need explicit variance unless they're part of a generic framework.

The tradeoff is code complexity versus safety. Variance annotations add visual noise to type signatures but eliminate entire categories of bugs. Teams maintaining libraries or shared utilities should default to using them. Teams writing application code can adopt them incrementally as they encounter variance-related bugs.

For deeper patterns on generic type design, see this guide on TypeScript generics. Teams migrating to newer TypeScript versions should review the TypeScript 6 migration guide for related breaking changes.

Beyond Strict Mode: The Future of TypeScript Type Safety

Strict mode remains essential for catching null dereferences and implicit any usage. But the next frontier of TypeScript safety lies in features like variance annotations that encode deeper semantic constraints.

The direction is clear: TypeScript is moving toward giving developers more precise control over type relationships. Variance annotations join features like template literal types, conditional types, and the upcoming pattern matching proposal as tools for building genuinely type-safe systems.

The practical impact: codebases that adopt variance annotations catch bugs during code review that would otherwise ship to production. The compiler becomes a more effective safety net, and the distinction between "type-checked code" and "type-safe code" shrinks.

That covers the essential patterns for using variance annotations to catch generic bugs that strict mode misses. Apply these in production and the difference will be immediate—fewer runtime type errors, stronger contracts between modules, and more confidence that compiled code actually works as intended. For form validation patterns that benefit from these techniques, explore custom TypeScript form validators.