TypeScript Conditional Types

TypeScript Conditional Types

Use conditional types, infer, and distributive logic to derive types programmatically

When to Use

• Deriving a type based on the shape of another type
• Extracting nested types from generics (unwrapping Promises, extracting array elements)
• Building type-level branching logic (if-then-else at the type level)
• Creating utility types that adapt to their input

Instructions

1. Basic conditional type — T extends U ? TrueType : FalseType:

type IsString<T> = T extends string ? true : false;

type A = IsString<'hello'>; // true
type B = IsString<42>; // false

2. Extract nested types with infer:

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

type A = UnwrapPromise<Promise<string>>; // string
type B = UnwrapPromise<number>; // number

type ArrayElement<T> = T extends (infer E)[] ? E : never;

type C = ArrayElement<string[]>; // string

3. Recursive unwrapping:

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

type A = DeepUnwrap<Promise<Promise<string>>>; // string

4. Function type extraction:

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

type Params = Parameters<(a: string, b: number) => void>; // [string, number]

5. Distributive conditional types — when T is a union, the condition distributes over each member:

type NonNullable<T> = T extends null | undefined ? never : T;

type A = NonNullable<string | null | undefined>; // string
// Distributes as: (string extends null ? never : string) | (null extends null ? never : null) | ...

6. Prevent distribution by wrapping in a tuple:

type IsUnion<T> = [T] extends [T] ? false : true; // Does not distribute

7. Constrain infer with extends:

type FirstString<T> = T extends [infer F extends string, ...any[]] ? F : never;

type A = FirstString<['hello', 42]>; // 'hello'
type B = FirstString<[42, 'hello']>; // never

8. Combine with mapped types for powerful transformations:

type OptionalByKey<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;

type User = { id: string; name: string; email: string };
type CreateUser = OptionalByKey<User, 'id'>; // id is optional, rest required

9. Chain conditional types for multi-branch logic:

type TypeName<T> = T extends string
  ? 'string'
  : T extends number
    ? 'number'
    : T extends boolean
      ? 'boolean'
      : T extends Function
        ? 'function'
        : 'object';

Details

Conditional types are TypeScript's mechanism for type-level computation. They enable types that depend on other types, analogous to ternary expressions at the value level.

Distribution behavior: When a conditional type is applied to a naked type parameter that is a union, it distributes — the condition is applied to each union member separately, and the results form a new union. This is usually desirable but can be surprising.

infer keyword: Only valid inside the extends clause of a conditional type. It declares a type variable that TypeScript infers from the structure being matched. You can use multiple infer keywords in one condition.

never in conditionals: A conditional branch that returns never removes that member from a union (since T | never = T). This is the mechanism behind Exclude, Extract, and NonNullable.

Recursive conditional types: TypeScript supports recursive conditional types (up to a depth limit). Use them for deep unwrapping, recursive object transformation, or path-based type extraction.

Trade-offs:

• Conditional types make the type system Turing-complete — but deeply nested conditionals slow down the compiler
• Distributive behavior is implicit and can produce unexpected results with union inputs
• infer can only capture types at specific structural positions — it cannot pattern-match arbitrary nested types

Common mistakes:

• Forgetting that T extends U checks assignability, not equality — string extends string | number is true
• Not accounting for never input — never extends anything distributes to never (empty union)
• Using infer outside of a conditional type's extends clause — it is not a standalone keyword

Source

https://typescriptlang.org/docs/handbook/2/conditional-types.html

Process

1. Read the instructions and examples in this document.
2. Apply the patterns to your implementation, adapting to your specific context.
3. Verify your implementation against the details and edge cases listed above.

Harness Integration

• Type: knowledge — this skill is a reference document, not a procedural workflow.
• No tools or state — consumed as context by other skills and agents.

Success Criteria

• The patterns described in this document are applied correctly in the implementation.
• Edge cases and anti-patterns listed in this document are avoided.