TypeScript Reference ยท Literal and Object Types
TypeScript recursive types
Reference for TypeScript recursive types: self-referencing type aliases and interfaces, JSON and tree types, recursive conditional types and depth limits.
A recursive type refers to itself in its own definition. Interfaces have always been able to do this. Type aliases can too, as long as the self-reference sits inside an object type, array, tuple, function type, or another deferred position. Recursive types model data of arbitrary depth: trees, linked lists, nested menus, JSON values and ASTs.
Recursive conditional and template literal types go further: they let you compute over types, for example making every nested property optional or splitting a string type at dots.
type Tree<T> = { value: T; children: Tree<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.
Concepts
Where self-reference is allowed
An alias may mention itself inside object properties, array element types (Json[]), tuple elements, function parameter and return types, and index signatures. These positions are resolved lazily. Direct, immediate circularity is an error: type A = A | string fails with "Type alias 'A' circularly references itself". Interfaces and classes never have this problem.
Recursive conditional types
A conditional type may call itself in a branch. TypeScript evaluates it until the condition stops matching. Tail-recursive forms (where the recursive call is the entire result of a branch) are optimized and can go about a thousand levels deep; other forms stop at roughly fifty levels with "Type instantiation is excessively deep and possibly infinite".
Termination
Every recursive type needs a base case: the object test in DeepPartial, the missing dot in Split. Without one the compiler reports the depth error.
Usage notes
- Functions and classes: these are
objectin conditional checks;DeepPartialwould walk into them. Add a function branch if that matters. - Arrays: the mapped type above maps arrays element-wise because mapped types over array types produce arrays.
- Readability: hover text for deep recursive results can be unreadable; consider an interface for the data and keep the recursive type for tooling.
- Performance: very large recursive unions slow checking; prefer simple structural recursion for data.
- Runtime: nothing is emitted; write the recursive function separately and let the type describe the result.
- Tail recursion: accumulate results in an extra type parameter to stay within limits.