What is type recursion depth limit?

TypeScript employs a type recursion depth limit to prevent infinite loops during type analysis, ensuring compiler stability and reasonable performance. This limit can sometimes be encountered when dealing with very complex or deeply nested type definitions.

What is Type Recursion?

Type recursion occurs when a type definition refers to itself, either directly or indirectly. This is common in advanced utility types, recursive data structures (like tree nodes or linked lists), and complex conditional types that iteratively process other types.

The Default Limit

By default, TypeScript's type recursion depth limit is set to 50. This means that if the compiler needs to expand a recursive type definition more than 50 levels deep, it will stop and report an error.

Why a Limit Exists

• Prevent Infinite Loops: Without a limit, an improperly defined recursive type could lead the compiler into an infinite loop, consuming all available memory or CPU cycles.
• Performance: Deep type instantiations are computationally expensive. A limit helps keep type checking performance predictable.
• Compiler Stability: It protects the compiler from potential stack overflows or crashes when dealing with excessively complex type structures.

Consequences of Exceeding the Limit

When the type recursion limit is exceeded, TypeScript typically issues an error message like 'Type instantiation is excessively deep and possibly infinite' or 'Type instantiation too deep and possibly infinite'. This error indicates that the compiler gave up on fully evaluating a type due to its depth.

Adjusting the Limit

Developers can adjust the type recursion depth limit using the --type-recursion-depth compiler option in their tsconfig.json file. While it's possible to increase this limit, it should be done cautiously, as it can lead to longer compilation times and potentially mask genuinely infinite recursive types.

{
  "compilerOptions": {
    "typeRecursionDepth": 100 // Increase to 100 from default 50
  }
}

It's generally recommended to only increase this limit when absolutely necessary for complex, well-understood recursive types, and after ensuring there isn't a simpler way to express the type.