Limits and type performance

The two hard limits

The compiler enforces two ceilings that produce the same error message:

• Instantiation depth — how deep a single chain of type instantiations may nest. Non-tail recursion walls out around 50; tail-recursive conditional types (TS 4.5+) reach roughly 1000.
• Instantiation count — a global budget on how many type instantiations one expression may trigger. The compiler aborts a runaway type with Type instantiation is excessively deep and possibly infinite. to protect against types that would otherwise hang the checker forever.

The message does not distinguish “genuinely infinite” from “finite but too expensive.” Both surface identically, so diagnosis means checking the base case first, then the depth, then the total instantiation count.

The real killer: union cross-products

Depth is rarely what bites teams in production. The catastrophic cost is combinatorial union explosion. When two unions meet in a way that forces the compiler to materialize every pairing, the work is the product of their sizes:

type Pair<A, B> = A extends any ? (B extends any ? [A, B] : never) : never;
type U = "a" | "b" | "c" | "d";          // 4 members
type Cross = Pair<U, U>;                  // 4 x 4 = 16 members
// chain three of these and you have 4^3 = 64; ten unions of 10 -> 10^10 instantiations

A distributive conditional over a 50-member union nested inside another distributive conditional over a 50-member union is 2,500 instantiations — for one type alias. Stack a few of those and you reach millions. This is why a type that looks innocent can 10x everyone’s editor latency.

Measuring instead of guessing

Never optimize types by feel. The compiler hands you exact numbers:

# Where is the time going? Totals: parse, bind, check, instantiation counts.
tsc --noEmit --extendedDiagnostics

# Emit a profile you can open in chrome://tracing or with the analyzer.
tsc --noEmit --generateTrace ./trace
npx @typescript/analyze-trace ./trace   # ranks the hottest types and files

# Stop the compiler from hiding the offending type behind "..." in errors.
tsc --noEmit --noErrorTruncation

--extendedDiagnostics shows Instantiations: and Check time — a jump from 200k to 5M instantiations after a PR points straight at the culprit. --generateTrace plus @typescript/analyze-trace names the specific type alias and source location burning the most time. --noErrorTruncation reveals the full (often enormous) type the compiler is choking on, instead of an unhelpful ....

Mitigations, in order of leverage

1. Shrink the inputs. Avoid distributing over large unions; opt out with [T] wrapping where you do not need per-member behavior.
2. Cache intermediates. Give a recursive or composed type a named alias so the compiler memoizes it instead of recomputing inline at every reference.
3. Prefer interfaces over large intersections for hot shapes; they are cached by name.
4. Avoid deep conditional chains. Flatten long A extends X ? ... : B extends Y ? ... ladders; they multiply instantiation count.
5. Turn on --incremental (and project references) so unchanged files reuse the prior .tsbuildinfo and only the touched graph re-checks.
6. Stop and validate at runtime. The senior move: if a type costs the team more than it saves, delete it and assert the invariant at runtime (a schema validator, a parser, a runtime guard). A 200-line type that proves a string is a valid route is worth less than a 5-line runtime check that does the same and costs the editor nothing.

Together these six levers move from the cheapest fix (shrink inputs, no structural change needed) to the most decisive (delete the type entirely). When you hit a limit, work down the list in order — if step 1 does not help, you likely have a structural problem that only steps 4–6 can resolve.