TypeScript Reference ยท Generics
Recursive generic types in TypeScript
Reference for recursive generic types in TypeScript: self-referencing interfaces and aliases, trees, JSON values, deep mapped types and recursion limits.
A recursive generic type mentions itself in its own definition, usually with a type parameter. This is how you describe data that nests to an unknown depth: a tree whose children are trees, a JSON value that can contain more JSON values, or an object whose properties should all become optional at every level.
Interfaces and classes may refer to themselves freely. Type aliases may too, as long as the self-reference sits inside an object type, array, tuple, or another deferred position. Conditional and mapped types can recurse as well, which is the basis of helpers such as DeepPartial<T>.
interface TreeNode<T> { value: T; children: TreeNode<T>[]; } type Json = string | number | boolean | null | Json[] | { [key: string]: Json };
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.
Syntax
interface Node<T> { next: Node<T> | null; value: T } type Tree<T> = { value: T; children: Tree<T>[] }; type Nested<T> = T | Nested<T>[]; type Recur<T> = T extends object ? { [K in keyof T]: Recur<T[K]> } : T;
| Form | Description |
|---|---|
| Interface or class | May reference itself anywhere in its members. |
| Object-shaped alias | The self-reference lives in a property, so it is deferred and allowed. |
| Array or tuple alias | `type A |
| Conditional or mapped alias | Recurses once per level of the input type; the compiler expands it lazily. |
Edge cases:
- An alias that only refers to itself at the top level, such as
type Bad = Bad, is error TS2456 ("Type alias 'Bad' circularly references itself."). - Very deep or unbounded expansion ends with TS2589 ("Type instantiation is excessively deep and possibly infinite.").
Usage notes
- Prefer a base case. Every recursive conditional type needs a branch that stops, usually a primitive or
never. - Guard functions. In
DeepPartialandDeepReadonly, functions are checked first. A function is anobjecttype, and mapping over it would erase its call signature. - Arrays and tuples. A homomorphic mapped type applied to an array type keeps it an array, so the recursive helpers above work on
string[]and tuples without extra code. - Depth limits. The compiler caps instantiation depth (around 100 levels for most cases, more for tail-recursive conditional types). Keep recursive types for data of realistic depth.
- Tail recursion. A conditional type whose recursive call is the final result in a branch is optimized, allowing much deeper recursion. This matters for string-parsing types built on template literals.
- Runtime is separate. The type says nothing about actual depth. Functions that walk the data need their own termination, and untrusted JSON should be validated.
- Compile speed. Deep recursive types over large objects can slow down type checking noticeably. Test with real shapes.