TypeScript Recursive Type Instantiation Depth Limits

Answer

The internal depth limit for non‑tail‑recursive conditional types is 50 by default (the maxDepth compiler option). The compiler will switch to a tail‑recursive optimization when a conditional type’s recursive reference appears only in one branch (the true or the false side) and the condition does not reference the type alias being defined.

Confirmed facts

• TypeScript’s default maxDepth value is 50.
• Exceeding this limit emits the error “Type instantiation depth exceeded.”
• The maxDepth option can be set in tsconfig.json or via tsc --maxDepth N.

Likely explanation (tail‑recursion condition)

When a conditional type is written as T extends U ? X : Y, the compiler treats it as tail‑recursive if:

1. The recursive reference to the type alias appears only in X or only in Y, never in both branches.
2. The condition T extends U does not mention the type alias being defined (i.e., U and T are independent of the alias).
3. The recursive call is not wrapped inside another type construct (e.g., not inside a mapped type or a tuple).

Under these circumstances the compiler can collapse the recursion into a loop, allowing depths far beyond the default limit without triggering the depth‑exceeded error.

Verification steps for this case

1. Create recursive.ts with a non‑tail‑recursive type that exceeds 50 levels, e.g.:

   type Deep<T, N extends number = 0> =
       N extends 50 ? T : Deep<T, N & 1>;

2. Run tsc --noEmit recursive.ts – you should see “Type instantiation depth exceeded.”
3. Add { "compilerOptions": { "maxDepth": 60 } } to tsconfig.json and re‑run; the error disappears.
4. To test tail‑recursion, replace the type with a tail‑recursive form:

   type Tail<T, N extends number = 0> =
       N extends 50 ? T : Tail<T, N & 1>;

   (where the recursive call is the whole expression in the false branch) and compile with the default maxDepth; it will succeed even for N > 50.