TypeScript Variance Annotations FAQ & Answers

Variance annotations (TypeScript 4.7+): Explicit syntax to declare how generic type parameters behave in subtyping relationships. Syntax: (1) 'out T' (covariant) - type parameter appears only in output/return positions, allows assigning subtype to supertype. Example: type Producer = () => T; means Producer assignable to Producer, (2) 'in T' (contravariant) - type parameter in input/parameter positions only, allows assigning supertype to subtype (reversed). Example: type Consumer = (val: T) => void;, (3) No annotation (invariant) - type parameter in both positions, strict equality required.

Benefits (2025): (1) Type-checking performance - 50-90% faster for generic-heavy codebases (compiler skips inference, uses declared variance), (2) Earlier error detection - variance errors caught at declaration site not usage site (better error messages, easier debugging), (3) Soundness guarantees - eliminates bivariant parameter bugs, strict contravariance for inputs, (4) Better IDE responsiveness - faster autocomplete, hover info, error squiggles in VS Code/WebStorm. Before 4.7: structural inference was slow (seconds for complex types), error-prone, bivariant parameter errors, 10-100x slowdowns in large codebases.

Common use cases (2025): (1) Event emitters - interface EventEmitter (events are output-only), (2) Promise/Observable - type Observable (values produced, not consumed), (3) State management - type Store { getState(): S; } (state is read-only output), (4) Dependency injection - interface Container { resolve(token: Token): T; } (produces instances), (5) Validators - type Validator = (value: T) => ValidationResult; (consumes values). Rule: Use 'out T' for return types, readonly properties, promise values, observable streams, getters. Use 'in T' for function parameters, setters, event handlers, validators.

API client example (2025): interface ApiClient<out TResponse, in TRequest> { get(): Promise; post(data: TRequest): Promise; }. TResponse covariant (produces responses), TRequest contravariant (consumes requests). Allows flexible subtyping: ApiClient<UserProfile, CreateUserDTO> assignable to ApiClient<BasicProfile, UserData> (BasicProfile supertype of UserProfile, UserData subtype of CreateUserDTO). Performance benchmarks: large TypeScript libraries (50K+ lines) see 60-80% faster type-checking with explicit variance on public API types.

When to use: (1) Public library APIs (maximize performance for consumers), (2) Complex generic types (eliminate inference ambiguity), (3) Variance-related compiler errors (make intent explicit). When NOT to use: simple types, internal implementation details, types with <3 generic parameters (inference fast enough). Best practices: add variance annotations to public API surface first (biggest performance gain), use --strictFunctionTypes flag (enforces contravariance for parameters, catches unsound code). TypeScript 5.0+: better variance checking for recursive types, improved error messages, faster inference for unannotated generics.

Variance annotations (TypeScript 4.7+): Explicit syntax to declare how generic type parameters behave in subtyping relationships. Syntax: (1) 'out T' (covariant) - type parameter appears only in output/return positions, allows assigning subtype to supertype. Example: type Producer = () => T; means Producer assignable to Producer, (2) 'in T' (contravariant) - type parameter in input/parameter positions only, allows assigning supertype to subtype (reversed). Example: type Consumer = (val: T) => void;, (3) No annotation (invariant) - type parameter in both positions, strict equality required.

Benefits (2025): (1) Type-checking performance - 50-90% faster for generic-heavy codebases (compiler skips inference, uses declared variance), (2) Earlier error detection - variance errors caught at declaration site not usage site (better error messages, easier debugging), (3) Soundness guarantees - eliminates bivariant parameter bugs, strict contravariance for inputs, (4) Better IDE responsiveness - faster autocomplete, hover info, error squiggles in VS Code/WebStorm. Before 4.7: structural inference was slow (seconds for complex types), error-prone, bivariant parameter errors, 10-100x slowdowns in large codebases.

Common use cases (2025): (1) Event emitters - interface EventEmitter (events are output-only), (2) Promise/Observable - type Observable (values produced, not consumed), (3) State management - type Store { getState(): S; } (state is read-only output), (4) Dependency injection - interface Container { resolve(token: Token): T; } (produces instances), (5) Validators - type Validator = (value: T) => ValidationResult; (consumes values). Rule: Use 'out T' for return types, readonly properties, promise values, observable streams, getters. Use 'in T' for function parameters, setters, event handlers, validators.

API client example (2025): interface ApiClient<out TResponse, in TRequest> { get(): Promise; post(data: TRequest): Promise; }. TResponse covariant (produces responses), TRequest contravariant (consumes requests). Allows flexible subtyping: ApiClient<UserProfile, CreateUserDTO> assignable to ApiClient<BasicProfile, UserData> (BasicProfile supertype of UserProfile, UserData subtype of CreateUserDTO). Performance benchmarks: large TypeScript libraries (50K+ lines) see 60-80% faster type-checking with explicit variance on public API types.

When to use: (1) Public library APIs (maximize performance for consumers), (2) Complex generic types (eliminate inference ambiguity), (3) Variance-related compiler errors (make intent explicit). When NOT to use: simple types, internal implementation details, types with <3 generic parameters (inference fast enough). Best practices: add variance annotations to public API surface first (biggest performance gain), use --strictFunctionTypes flag (enforces contravariance for parameters, catches unsound code). TypeScript 5.0+: better variance checking for recursive types, improved error messages, faster inference for unannotated generics.