TypeScript Conditional Types: Mastering the infer Keyword

A January 2026 empirical study on arXiv — From Logic to Toolchains: An Empirical Study of Bugs in the TypeScript Ecosystem (arXiv:2601.21186) — analyzed 633 bug reports across 16 popular TypeScript open-source repositories and constructed a taxonomy of fault types. The findings show that inadequate type narrowing and incorrect type assumptions form a significant and preventable category of real-world TypeScript failures. This is precisely the class of errors that TypeScript's conditional types with infer are designed to prevent at compile time.

This guide walks through TypeScript conditional types from first principles to production-grade infer patterns, with concrete examples drawn from the patterns libraries use in the wild.

What Are Conditional Types?

Conditional types let the TypeScript type system make decisions based on type relationships, using a ternary-like syntax at the type level:

type IsArray<T> = T extends any[] ? true : false;

type A = IsArray<string[]>;  // true
type B = IsArray<number>;    // false

The T extends U ? X : Y form reads: if T is assignable to U, resolve to type X; otherwise, resolve to type Y. This is evaluated entirely at the type level — no runtime cost, no emitted code, pure structural reasoning by the compiler.

Conditional types become significantly more powerful when combined with two features: distribution over union types and the infer keyword. When a conditional type is used in a generic over a union, TypeScript distributes the condition over each member independently:

type ToArray<T> = T extends any ? T[] : never;
type Result = ToArray<string | number>;  // string[] | number[]

The infer Keyword: Extracting Types From Structure

The real power arrives with infer, which lets you capture a sub-type from within a conditional check. Think of it as a type-level variable declaration that only exists within the true branch of the conditional:

type ReturnType<T> = T extends (...args: any[]) => infer R ? R : never;

function greet(name: string): string {
  return `Hello, ${name}`;
}

type Greeting = ReturnType<typeof greet>;  // string

Here, infer R captures whatever the return type of the function T happens to be, without you needing to know or hard-code it ahead of time. This is not a toy pattern — it is how TypeScript's own built-in utility types are implemented. ReturnType, InstanceType, Parameters, and Awaited all use infer internally.

A February 2026 eye-tracking study (arXiv:2602.04824, Do Developers Read Type Information? An Eye-Tracking Study on TypeScript) found that developers significantly change their reading behavior when type information is made explicit in signatures rather than inferred implicitly. When conditional types make return or parameter shapes explicit, developers spend more time confirming the constraint — a reading behavior associated with earlier detection of type mismatches.

Practical Pattern 1: Unwrapping Promises and Async Types

One of the most commonly needed patterns in modern TypeScript is unwrapping the resolved value type of a Promise, particularly in data-fetching layers and async API wrappers:

type Awaited<T> = T extends Promise<infer U> ? Awaited<U> : T;

type A = Awaited<Promise<string>>;              // string
type B = Awaited<Promise<Promise<number>>>;     // number (recursive!)

TypeScript 4.5 added a built-in Awaited<T> utility type for exactly this use case. However, constructing it yourself from scratch is the fastest way to internalize how recursive conditional types work — a pattern that appears throughout the internals of every major TypeScript library including Zod, Prisma, and tRPC.

Practical Pattern 2: Tuple and Function Parameter Extraction

Conditional types with infer can reach into deeply nested generic structures. A common real-world use is extracting element types from tuples, or unpacking function parameter shapes for middleware and adapter layers:

// Extract the first element type of a tuple
type Head<T extends any[]> = T extends [infer H, ...any[]] ? H : never;
type First = Head<[string, number, boolean]>;  // string

// Extract the last element
type Last<T extends any[]> = T extends [...any[], infer L] ? L : never;
type Final = Last<[string, number, boolean]>;  // boolean

// Extract all parameter types as a tuple
type Params<T> = T extends (...args: infer P) => any ? P : never;

function save(id: number, data: string): void {}
type SaveParams = Params<typeof save>;  // [number, string]

This is particularly valuable when building typed middleware, generic wrappers, or decorator factories that need to preserve the full type signature of functions they wrap — a pattern that appears in every major TypeScript framework.

Practical Pattern 3: Discriminated Union Filtering

Conditional types compose powerfully with discriminated union patterns. Consider an API response union where you want to extract the data type only from success cases, at the type level:

type ApiResponse<T> =
  | { status: 'success'; data: T }
  | { status: 'error'; error: string };

type ExtractSuccess<R> =
  R extends { status: 'success'; data: infer D } ? D : never;

type UserResponse = ApiResponse<{ id: number; name: string }>;
type UserData = ExtractSuccess<UserResponse>;
// Result: { id: number; name: string }

When distributed over a union, this pattern acts as a type-level filter, separating success payloads from error payloads without any runtime logic. Libraries like Zod, @effect/schema, and ts-results use exactly this technique for their typed error-handling APIs.

Comparing TypeScript Conditional Type Patterns

Common Pitfalls When Using infer

Despite their power, conditional types with infer have sharp edges that appear repeatedly in real-world bug reports:

• Contravariant positions: Using infer in a function parameter (contravariant) position may produce an unexpected intersection type. When infer appears in multiple positions, TypeScript must reconcile potentially conflicting inferences from each position.
• Circularity and depth errors: Recursive conditional types can trigger a “Type instantiation is excessively deep” compiler error for deeply nested structures. The fix is often to add a recursion-depth accumulator parameter or use TypeScript 4.1+’s tail-call optimization for recursive types.
• Distribution opt-out: If you want a conditional type to apply to a union as a whole rather than distribute over each member, wrap the extends check in a tuple: [T] extends [U] instead of bare T extends U.
• Compile-time performance: Complex recursive conditional types can significantly increase type-check time. Test with tsc --diagnostics when adding complex conditional type chains to a large codebase.

Frequently Asked Questions

When should I use conditional types instead of function overloads?

Conditional types are better when the type relationship is structural — when the output type depends on the shape of the input type, not on a small enumerable set of specific values. Function overloads work better when you have a fixed number of known calling signatures. In practice, many complex APIs use both: overloads define the public-facing signatures, while conditional types implement the utility types those signatures depend on internally.

Can infer be used multiple times in a single conditional type?

Yes. Multiple infer clauses can appear in a single conditional type, each capturing a different structural component. For example, to extract both the parameter type and return type of a function in one step: T extends (arg: infer A) => infer R ? [A, R] : never. Each infer binds independently to its structural position in the extends clause, and TypeScript resolves each independently.

Are there performance-safe alternatives to deep recursive conditional types?

Yes. For many common deep-unwrapping scenarios, TypeScript's built-in utilities (Awaited, NonNullable, Required) cover the most frequent cases without custom recursion. For custom recursive types, limiting recursion depth with a counter parameter (a tuple accumulator pattern) reliably prevents the “instantiation is excessively deep” error while keeping the type safe.

The Bottom Line

TypeScript's infer keyword is the difference between a type system that passively documents your code and one that actively reasons about it. The patterns covered here — promise unwrapping, tuple decomposition, discriminated union filtering — appear in the internals of every major TypeScript library and framework. Empirical research on the TypeScript ecosystem confirms that poor type narrowing is a leading contributor to preventable bugs in production TypeScript codebases. Learning infer well is one of the highest-leverage investments a TypeScript developer can make: it closes a meaningful class of runtime errors at the type level, where they cost nothing to fix.

Disclaimer: This article is for informational purposes only. Technology landscapes change rapidly; verify information with official sources before making technical decisions.