Skip to content
Tutorials Center
My learning

Topics

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.

TypeScript
type Tree<T> = { value: T; children: Tree<T>[] };
type Json = string | number | boolean | null | Json[] | { [key: string]: Json };

Try it

TypeScript Trees and JSON

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 Recursive conditional types

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 object in conditional checks; DeepPartial would 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.