Skip to content
Tutorials Center
My learning

Topics

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>.

TypeScript
interface TreeNode<T> {
  value: T;
  children: TreeNode<T>[];
}

type Json = string | number | boolean | null | Json[] | { [key: string]: Json };

Try it

TypeScript A generic tree and a recursive walk

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.

TypeScript DeepPartial and DeepReadonly

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.

TypeScript A recursive JSON type

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

TypeScript
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 = T
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 DeepPartial and DeepReadonly, functions are checked first. A function is an object type, 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.