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. ```mermaid flowchart TD Animal["Animal (base type)"] Dog["Dog (specific type)"] Cat["Cat (specific type)"] Animal --> Dog Animal --> Cat CovariantBox["Covariant: Box<out T>
Accepts Dog where Animal expected"] ContravariantBox["Contravariant: Handler<in T>
Accepts Animal where Dog expected"] InvariantBox["Invariant: Store<T>
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: ```typescript 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. ![TypeScript variance error in IDE](https://emzvxuokuqzdkmyrzfut.supabase.co/storage/v1/object/public/blog/posts/typescript-variance-annotations-generic-bugs/content-1.jpg) 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). ```typescript // Explicitly covariant: can only read from T interface ReadonlyBox { readonly value: T; get(): T; } // Explicitly contravariant: can only write to T interface WriteableBox { set(value: T): void; update(fn: (prev: T) => T): void; } // Invariant: both reads and writes interface Box { 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 = { value: { name: 'Max', breed: 'Labrador' }, get: () => ({ name: 'Max', breed: 'Labrador' }) }; const animalBox: ReadonlyBox = dogBox; // Valid: covariance allowed for readonly const dogWriter: WriteableBox = { set: (d) => console.log(d.breed), update: (fn) => console.log(fn({ name: 'Max', breed: 'Labrador' }).breed) }; // Error: Type 'WriteableBox' is not assignable to type 'WriteableBox' const animalWriter: WriteableBox = dogWriter; ``` The annotations force the compiler to verify that types are used correctly. A `ReadonlyBox` cannot have methods that accept `T` as a parameter—only return it. A `WriteableBox` 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. ```mermaid 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: ```typescript // 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 { handle(event: T): void; } const clickHandler: EventHandler = { handle: (e) => console.log(e.x, e.y) }; // Error: cannot pass specific handler where general handler expected const generalHandler: EventHandler = 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. ![Diagram showing variance annotation flow](https://emzvxuokuqzdkmyrzfut.supabase.co/storage/v1/object/public/blog/posts/typescript-variance-annotations-generic-bugs/content-2.jpg) ## 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. ```typescript // Unsafe event emitter without variance class UnsafeEmitter { 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(); const errorEmitter: UnsafeEmitter = 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: ```typescript // Type-safe emitter with variance class EventEmitter { 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(); // 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 = new EventEmitter(); ``` ```mermaid flowchart TD Emit["emit(event: TEmit)
Covariant position"] --> EmitCheck{Can substitute
more specific?} EmitCheck -->|Yes| EmitValid["ErrorEvent → BaseEvent ✓"] EmitCheck -->|No| EmitInvalid["BaseEvent → ErrorEvent ✗"] Subscribe["on(handler: TSubscribe)
Contravariant position"] --> SubCheck{Can substitute
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. ```mermaid flowchart TD Decision{Does type appear in
library/shared code?} Decision -->|Yes| CheckUsage{How is T used?} Decision -->|No| Skip["Skip annotations
Use inferred variance"] CheckUsage -->|Output only| UseOut["Add 'out' modifier
ReadonlyBox<out T>"] CheckUsage -->|Input only| UseIn["Add 'in' modifier
Handler<in T>"] CheckUsage -->|Both| Invariant["Leave unmodified
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](/generics-in-typescript). Teams migrating to newer TypeScript versions should review [the TypeScript 6 migration guide](/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](/typescript-form-validators-custom).

Posts tagged “variance”

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