168: Conditional Types, infer, Distributivity, and Advanced Type Logic

Learning outcomes

By the end of this lesson, you can:

explain and apply conditional types in a realistic implementation;
explain and apply infer in a realistic implementation;
explain and apply distributive conditionals in a realistic implementation;
explain and apply recursive conditional types in a realistic implementation;
explain and apply constraint placement in a realistic implementation.

Prerequisites and retrieval

This lesson assumes the 01–06 foundation and the lessons that come before it in this module. Retrieve one concrete example from an earlier project before you begin. Perhaps you had to unwrap a promise, select the element type of an array, preserve a tuple shape, or map a union of API responses. The terminology will be easier to retain if you can connect it to a problem you have actually encountered.

The purpose here is not to memorize clever type tricks. It is to make a defensible choice in a strict TypeScript codebase. The compiler can model domain invariants and relationships between types, but it does not replace runtime validation. Data arriving from a request, file, database, or third-party package is still untrusted until the program checks it.

Terminology

Conditional types: T extends U ? X : Y chooses a resulting type based on assignability. It is the type-level equivalent of asking whether a type fits a particular shape and selecting one of two results.
infer: Within the true branch of a conditional type, infer captures part of a matched type, such as a function return type, promise value, array element, or tuple tail. The captured type can then be used in the branch's result.
Distributive conditionals: A conditional over a naked type parameter distributes across union members. In other words, a union is evaluated one member at a time when the checked type parameter appears directly on the left of extends.
Recursive conditional types: Recursive types can walk nested arrays, objects, or promise-like structures. They should still have practical depth and shape limits, because an unbounded type-level walk can make compilation expensive and errors difficult to read.
Constraint placement: Moving an extends constraint from the generic declaration into a conditional often allows the false branch to describe unsupported types instead of rejecting those types at the call site.
Library-level judgment: Advanced conditional logic is most valuable in generic libraries, SDKs, schema helpers, and framework types. In ordinary application code, an explicit domain name is often easier to maintain than a clever transformation.

Mental model

Treat Conditional Types, infer, Distributivity, and Advanced Type Logic as a design problem with observable inputs, outputs, invariants, and failure modes. A conditional type describes a relationship that changes with the input type. That makes it useful for reusable libraries, where one definition can preserve information across many callers. The same flexibility can become a liability when the type-level program is harder to understand than the runtime code it supports.

A strong implementation makes its assumptions visible, narrows uncertainty at boundaries, and leaves enough evidence to explain why the design is safe. That evidence might be tests, constraints, type assertions checked by the compiler, metrics, or a diagram of the transformation. Types tell you what the compiler can prove; they do not prove that external data was honest.

A useful interview and production sequence is:

requirement -> constraints -> model -> implementation -> failure analysis -> verification

Start by stating what must remain true. Then identify the input and output shapes, choose the type-level mechanism that expresses that relationship, and verify both the type result and the runtime boundary. Do not jump from a requirement directly to a library helper. A short type alias is not automatically a good design if nobody can explain which cases it accepts or rejects.

Deep dive

1. Conditional types

When one API needs to return different type information for different inputs, an ordinary generic constraint may be too blunt. A conditional type expresses the choice directly: T extends U ? X : Y produces X when T is assignable to U, and Y otherwise. The check happens during type analysis, not against a runtime value.

For example, a library might return one result shape for a successful response and another for an error response. The conditional type can preserve that relationship for callers, but it cannot inspect an actual JSON payload while the program is running. Runtime parsing or validation is still responsible for establishing that the payload has the claimed shape.

Decision rule: Use conditional types deliberately when they make the contract or invariant easier to prove. If the conditional merely saves a little typing while hiding an assumption, prefer the more explicit design.

2. infer

Conditional types become more useful when the type you need is part of the shape you are matching. infer gives that part a name inside the true branch. A return-type helper can match a function as (...args: any[]) => infer R and use R; an array helper can match readonly (infer E)[] and use E; an awaited-value helper can match a promise-like wrapper and use the contained value.

The capture is local to the conditional branch. It is not a runtime variable and does not cause the program to unwrap a promise or inspect a function. It tells the compiler how to extract information that is already represented by a type. This is where people usually get confused: infer improves static information, while the implementation still needs the runtime operation that makes the type's promise true.

Decision rule: Use infer deliberately when it makes the contract or invariant easier to prove. If it only reduces typing while hiding an assumption, prefer the more explicit design.

3. Distributive conditionals

Suppose T is string | number and the conditional is written as T extends string ? A : B. When T is a naked type parameter, TypeScript evaluates each union member separately and combines the results: A | B. This behavior is called distributivity. It is useful when a helper should transform every member of a union independently.

Sometimes that is not what an API needs. To test the union as one value, wrap the checked type in a tuple: [T] extends [string] ? A : B. The tuple wrapper prevents the special distribution behavior and asks whether the complete union is assignable to string. The two forms look almost identical, so this distinction is worth checking when a helper unexpectedly widens or produces a union.

Decision rule: Use distributive conditionals deliberately when they make the contract or invariant easier to prove. If distribution only hides whether the API is handling members or the union as a whole, make the choice explicit.

4. Recursive conditional types

A recursive conditional type applies the same transformation again to a smaller part of the input. That makes it possible to unwrap nested promise-like values, flatten nested arrays, or walk a nested object shape. The recursion needs a clear stopping case. Without one, the compiler has no useful boundary for the transformation, and even a technically valid design can produce excessive-instantiation errors or unreadable diagnostics.

In production library types, practical limits matter. A bounded tuple can act as a depth counter, and a shape check can stop recursion for unsupported values. The goal is not to model every conceivable type. It is to model the supported input shapes clearly enough that compilation remains predictable and users can understand an error.

Decision rule: Use recursive conditional types deliberately when they make the contract or invariant easier to prove. If recursion introduces more compiler complexity than value, use a bounded or explicit alternative.

5. Constraint placement

There are two different ways to express a requirement such as “this helper understands array-like inputs.” You can constrain the generic declaration, as in T extends readonly unknown[], or accept a broader T and test the relationship inside the conditional. The first form rejects unsupported inputs before the helper can produce a result. The second can return a fallback type for unsupported inputs.

Neither placement is universally better. Put the constraint on the generic when unsupported input is a programmer error and should never be part of the helper's domain. Put the check inside the conditional when the helper intentionally describes both supported and unsupported cases. This choice affects error messages and API composition, not just syntax.

Decision rule: Use constraint placement deliberately when it makes the contract or invariant easier to prove. If it only makes a declaration look stricter while losing a useful false branch, reconsider where the constraint belongs.

6. Library-level judgment

These techniques earn their keep most often in generic libraries, SDKs, schema helpers, and framework types. A library may need to preserve a caller's exact return type, unwrap a transport wrapper, or map a union of routes to a union of results. Conditional logic can provide that precision once and serve many consumers.

Application code has a different maintenance trade-off. If a type transformation obscures a business rule, give the rule an explicit domain name or use a small, named interface. A slightly longer type that a team can debug is often better than a compact type-level puzzle. The right measure is not how advanced the syntax looks; it is whether the resulting contract is easier to use and verify.

Decision rule: Apply library-level judgment deliberately when it makes the contract or invariant easier to prove. If clever transformations obscure intent, prefer explicit domain types.

Worked example

Consider a strict TypeScript codebase that uses the compiler to describe domain invariants without pretending that static types replace runtime validation. Begin with the requirement in one sentence. Then list the input and output contracts and identify which of the concepts above owns each failure mode. This prevents the type helper from becoming a substitute for architecture.

The useful separation is by responsibility: parsing or validation belongs at the boundary; domain rules belong in the domain or service layer; persistence rules belong in the database or repository; presentation rules belong in the client. Mixing these concerns can make a happy-path demo shorter, but it leaves edge cases scattered across the system and makes failures harder to localize.

type TaskId = string & { readonly __brand: 'TaskId' };

function parseTaskId(value: unknown): TaskId {
  if (typeof value !== 'string' || value.length === 0) {
    throw new TypeError('Invalid task id');
  }
  return value as TaskId;
}

This example uses a branded intersection to distinguish a validated TaskId from an arbitrary string. The assertion does not validate anything by itself. The function's runtime check establishes the condition first, and the assertion communicates that established fact to the type system. A conditional type could help describe a generic transformation around this value, but it would not make an untrusted request value safe.

Walk the example through at least four cases: the normal path; an empty or missing value; a duplicate, retry, or concurrent path where that concern applies; and a dependency failure. For each case, state which layer detects the problem and what the caller observes. For instance, parsing should reject an empty external value, while duplicate handling belongs to the domain or persistence design rather than to the TaskId brand. This is the level of explanation expected in a senior code review or technical interview.

Production perspective

Production correctness is broader than “the code works on my machine.” Ask how the design behaves during deploys, retries, partial failure, stale clients, concurrent requests, malformed data, schema changes, and high-cardinality inputs. Advanced type logic can improve the developer experience, but it does not remove operational concerns or runtime failure modes.

Prefer explicit contracts, bounded resource usage, structured errors, and measurable behavior. Optimize only after you can identify the bottleneck or risk with evidence. A recursive type that slows the compiler is a developer-productivity problem; a recursive runtime transformation over unbounded input can also be a resource-exhaustion problem. Treat those as separate concerns and test both where relevant.

When the topic involves an external dependency, define a timeout and cancellation strategy. When it involves persistence, define transaction and consistency expectations. When it involves user-visible state, define loading, empty, error, stale, and success states. When it involves security, assume that the client can be modified and that network input is untrusted. Compile-time guarantees apply to the code you compile, not to values that bypass the boundary checks.

Guided lab

Implement Awaited-like, ElementOf, and ReturnType-like helpers with infer. Demonstrate distributive and non-distributive behavior over a union, and document which version your API requires. For the awaited helper, decide what happens with nested promise-like values and where recursion stops. For ElementOf, decide whether readonly arrays are supported. For ReturnType-like behavior, decide what the helper should produce for a non-function input or whether that input should be rejected by a constraint.

Use compile-time examples or type-level tests to verify the results. Then keep the runtime boundary in view: a type helper can describe a value that the implementation promises to return, but it cannot validate external data or execute an asynchronous operation.

Complete the lab with this discipline:

Write the requirement and two non-requirements.
List input, output, and error contracts before implementation.
Implement the smallest correct vertical slice.
Add at least one invalid-input test and one edge-case test.
Instrument or inspect the behavior instead of guessing.
Refactor one hidden assumption into an explicit type, constraint, function, or configuration.
Explain one alternative design and why you did not choose it.
Record a short “what would break at 10× scale?” note.

Edge cases and failure modes

Conditional types: test absence, malformed input, duplicates, ordering or concurrency where applicable, and behavior at the smallest and largest credible sizes.
infer: test absence, malformed input, duplicates, ordering or concurrency where applicable, and behavior at the smallest and largest credible sizes.
Distributive conditionals: test absence, malformed input, duplicates, ordering or concurrency where applicable, and behavior at the smallest and largest credible sizes.
Recursive conditional types: test absence, malformed input, duplicates, ordering or concurrency where applicable, and behavior at the smallest and largest credible sizes. Include a depth or shape that reaches the intended recursion boundary.
Constraint placement: test absence, malformed input, duplicates, ordering or concurrency where applicable, and behavior at the smallest and largest credible sizes. Check both an accepted input and an input that should reach the false branch or produce a deliberate constraint error.

Common mistakes and debugging

Solving the example instead of the requirement: a copied pattern can be syntactically correct but architecturally wrong.
Hiding uncertainty with assertions, broad exception handlers, permissive schemas, or “temporary” any values.
Testing only the happy path and discovering the real contracts only after integration.
Optimizing before measuring, or choosing a scalable mechanism without a scale requirement.
Letting client-side behavior stand in for server-side authorization, validation, or persistence guarantees.
Treating a successful compile as proof that runtime input has been validated.
Forgetting whether a conditional should distribute over union members, or assuming that a tuple wrapper has no semantic effect.
Adding unconstrained recursive type logic and then debugging an error that is really a compiler-complexity or depth problem.

For debugging, reproduce the smallest failing case. Inspect the actual value or type result, trace the boundary where the invariant first becomes false, and fix the owning layer instead of adding a downstream patch. With a conditional helper, reduce the input to one simple branch and then to a union. Check whether the type parameter is naked on the left of extends; if it is, distribution may be the behavior you are seeing. With infer, inspect the matched shape and confirm that the capture is inside the true branch. With recursive types, reduce nesting and add or verify a stopping condition.

Interview questions

What problem do conditional types solve, and what trade-off or failure mode would make you choose a different approach?
What problem does infer solve, and what trade-off or failure mode would make you choose a different approach?
What problem do distributive conditionals solve, and what trade-off or failure mode would make you choose a different approach?
What problem do recursive conditional types solve, and what trade-off or failure mode would make you choose a different approach?
What problem does constraint placement solve, and what trade-off or failure mode would make you choose a different approach?

Checkpoint

Without notes, explain Conditional Types, infer, Distributivity, and Advanced Type Logic to another developer in five minutes. Your explanation must include one invariant, one edge case, one production failure mode, and one alternative design. Include the difference between a distributive check and a tuple-wrapped non-distributive check, and distinguish compile-time extraction from runtime validation. Then implement a small example without copying the lesson code.

Mastery checklist

I can define the core terms precisely.
I can choose a design from requirements instead of from habit.
I can implement and test the normal path and edge cases.
I can explain the runtime, storage, or complexity cost.
I can identify which layer owns validation, errors, and recovery.
I can compare at least two reasonable alternatives.
I can explain how the design changes at larger scale or stricter reliability.