Mastering Recursive Types in TypeScript: Handling Depth Limitations Gracefully

Introduction

When working with deeply nested data structures in TypeScript, creating utility types to transform these structures is a common task. However, recursive types, while powerful, come with their own set of challenges.

One such challenge is controlling recursion depth effectively to prevent type computation from exceeding TypeScript's capabilities. This article will explore a common approach to incrementing and decrementing type-level numbers, identify its limitations, and present a robust solution for managing recursion depth using proper Increment and Decrement types.

🐛 The Problem with Basic Type-Level Number Operations

To better understand the limitations, let’s look at a naive approach often used when incrementing or decrementing numbers at the type level:

type Prev = [never, 0, 1, 2, 3, 4];
type Next = [1, 2, 3, 4, 5, 6];

type MinusOne = Prev[5]; // 👉 4
type PlusOne = Next[5];  // 👉 6

🍿 Problem Scenario: Deeply Nested Optional Properties

Suppose you have a deeply nested object type and want to make all
properties optional up to a specified level:

type DeepObject = {
  a: number;
  b: {
    c: string;
    d: {
      e: boolean;
      f: {
        g: string;
        h: {
          i: number;
          j: {
            k: string;
          };
        };
      };
    };
  };
};

With a naive, hardcoded approach, managing the depth at which properties become optional would look like this:

type Prev = [never, 0, 1, 2, 3, 4];

type DeepOptional<
  T,
  Limit extends number = 1
> = Limit extends never
  ? never
  : {
      [K in keyof T]?: T[K] extends object
        ? DeepOptional<T[K], Prev[Limit]>
        : T[K];
    };

Explanation:

• DeepOptional makes properties optional up to Limit.
• The Limit will be used to get the decremented value from the static tuple.

Example Usage:

type NewDeepObject = DeepOptional<DeepObject, 3>;

// Result:
// {
//   a?: number;
//   b?: {
//     c?: string;
//     d?: {
//       e?: boolean;
//       f?: {
//         g: string;
//         h: {
//           i: number;
//           j: {
//             k: string;
//           };
//         };
//       };
//     };
//   };
// };

type NewDeepObject = DeepOptional<DeepObject, 1>;

// Result:
// {
//   a?: number;
//   b?: {
//     c: string;
//     d: {
//       e: boolean;
//       f: {
//         g: string;
//         h: {
//           i: number;
//           j: {
//             k: string;
//           };
//         };
//       };
//     };
//   };
// };

✋ Issues with This Approach

• Limited Range: This approach is only as flexible as the predefined arrays Prev and Next. If you need to increment or decrement numbers beyond the length of these arrays, you have to extend them manually, which is cumbersome and error-prone.
• Scalability: As your needs evolve, managing these arrays becomes increasingly complex, making this approach impractical for larger-scale type operations.

🎯 A More Robust Solution: Tuple-Based Increment and Decrement Types

To overcome the limitations of predefined arrays, we can use tuple manipulation to create type-safe Increment and Decrement operations that scale dynamically.

🏗️ Key Building Blocks

• Length Utility: A type to get the length of a tuple:

type Length<T extends any[]> = (T extends { length: number } ? T["length"] : never) & number;

• TupleOf: A type that generates a tuple of N elements:

type TupleOf<N extends number, T extends unknown[] = []> = Length<T> extends N
  ? T
  : TupleOf<N, [...T, unknown]>;

• Pop Utility: A type that removes the last element of a tuple:

type Pop<T extends any[]> = T extends [...infer U, unknown] ? U : never;

• Increment and Decrement:

// Increment adds an element to a tuple, effectively creating N + 1
type Increment<N extends number> = Length<[1, ...TupleOf<N>]>;

// Decrement removes an element from a tuple, effectively creating N - 1
type Decrement<N extends number> = Length<Pop<TupleOf<N>>>;

🍿 Applying Increment and Decrement: A Practical Example

Let’s explore how these utility types can be applied to a more complex real-world problem: making properties of an object optional up to a certain depth.

Problem Scenario: Deeply Nested Optional Properties

Suppose you have a deeply nested object type and want to make all
properties optional up to a specified level:

type DeepObject = {
  a: number;
  b: {
    c: string;
    d: {
      e: boolean;
      f: {
        g: string;
        h: {
          i: number;
          j: {
            k: string;
          };
        };
      };
    };
  };
};

With a naive, hardcoded approach, managing the depth at which properties become optional would be complex. Here’s how a type-safe DeepOptional utility can solve this:

Implementing DeepOptional

type DeepOptional<
  T,
  Limit extends number = 1,
  CurrentLevel extends number = 0
> = CurrentLevel extends Limit
  ? T
  : {
      [K in keyof T]?: T[K] extends object
        ? DeepOptional<T[K], Limit, Increment<CurrentLevel>>
        : T[K];
    };

Explanation:

• DeepOptional makes properties optional up to Limit.
• The type increments CurrentLevel recursively until it matches Limit, at which point it stops recursing and returns T.
• The Increment<CurrentLevel> ensures type-safe recursion without manual array mappings.

Example Usage:

type NewDeepObject = DeepOptional<DeepObject, 3>;

// Result:
// {
//   a?: number;
//   b?: {
//     c?: string;
//     d?: {
//       e?: boolean;
//       f?: {
//         g: string;
//         h: {
//           i: number;
//           j: {
//             k: string;
//           };
//         };
//       };
//     };
//   };
// };

type NewDeepObject = DeepOptional<DeepObject, 1>;

// Result:
// {
//   a?: number;
//   b?: {
//     c: string;
//     d: {
//       e: boolean;
//       f: {
//         g: string;
//         h: {
//           i: number;
//           j: {
//             k: string;
//           };
//         };
//       };
//     };
//   };
// };

🕵️ Conclusion

At medusajs, we're committed to finding the most efficient and innovative solutions to overcome complex technical challenges. By leveraging tuple-based Increment and Decrement types, you can move beyond the limitations of basic type-level operations and create scalable, type-safe utilities. This method not only simplifies recursion depth management but also ensures you maintain the flexibility needed for intricate type operations without exceeding TypeScript’s type-checking limits.