Cartwheel’s product categories form a tree: Kitchen contains Cookware, which contains Pans. The API returns that tree as nested JSON, and the checkout’s settings screen edits a deeply nested config object. Both need types that refer to themselves. TypeScript handles that well, up to a point. This lesson covers how to write recursive types, where the limits are, and the judgment call this whole section has been building towards: when to stop.
\nA type alias may mention itself inside an object or array type:
\ntype Category = { id: number; name: string; children: Category[] };\n\ntype Json = string | number | boolean | null | Json[] | { [key: string]: Json };Category describes a tree of any depth. Json describes any value JSON.parse can return, which makes it a much better return type for a parser than any: it is honest, and it forces you to narrow before use.
Recursive type-level functions follow the same idea. Awaited<T>, built into the lib since TypeScript 4.5, unwraps promises until there are none left. A simplified version:
type MyAwaited<T> = T extends Promise<infer V> ? MyAwaited<V> : T;\n\ntype Loaded = MyAwaited<Promise<Promise<Order>>>; // OrderEach step peels off one Promise and calls itself on what was inside. When the type is no longer a promise, the false branch returns it and the recursion ends.
The mapped types from Mapped Types and Key Remapping are shallow. Recursion makes them deep:
\ntype DeepReadonly<T> = T extends (...args: any[]) => any\n ? T\n : T extends object\n ? { readonly [K in keyof T]: DeepReadonly<T[K]> }\n : T;\n\ntype FrozenCheckout = DeepReadonly<Checkout>;Each case is there for a reason. Primitives fall through unchanged. Objects are mapped, and each property is processed recursively. Functions get their own branch because a mapped type keeps properties but not call signatures: without the branch, an onSubmit handler would turn into an object you cannot call. Arrays need no special case here, because a homomorphic mapped type applied to an array produces a readonly array.
DeepPartial is the other one you will meet, typically for test fixtures and config overrides:
type DeepPartial<T> = T extends readonly unknown[]\n ? T\n : T extends object\n ? { [K in keyof T]?: DeepPartial<T[K]> }\n : T;\n\ndeclare function checkoutFixture(overrides?: DeepPartial<Checkout>): Checkout;\ncheckoutFixture({ shipping: { address: { country: 'JO' } } });Here arrays are kept whole on purpose: a partial array of partial line items is rarely what a test means.
\n\nHere is the type people reach for when they want get(checkout, 'shipping.address.city') to be checked:
type Paths<T> = {\n [K in keyof T & string]: T[K] extends object ? K | `${K}.${Paths<T[K]>}` : K;\n}[keyof T & string];\n\ntype CheckoutPath = Paths<{ shipping: { address: { city: string; country: string } }; totalCents: number }>;\n// 'shipping' | 'shipping.address' | 'shipping.address.city' | 'shipping.address.country' | 'totalCents'It works, and on a small type it is delightful. It is also a mapped type, a conditional, a template literal and recursion in four lines, and its cost grows with every field and every level. On a real 40-field state object with arrays and dates in it, a type like this can produce thousands of members and make every keystroke in the editor slower.
\nTypeScript also has hard limits. Each nested instantiation counts, and after a few dozen levels of ordinary recursion you get Type instantiation is excessively deep and possibly infinite. Since TypeScript 4.5, a conditional type whose recursive call is in tail position (the whole result of a branch, as in MyAwaited) is optimised and can run about 1,000 iterations. There is no compiler flag to raise either limit.
Recursive types are the right tool for genuinely recursive data: trees, JSON, nested configs. For everything else, write the boring type first, and reach for the clever one only when a real bug justifies it.
\nIn the exercise you will write MyAwaited, DeepReadonly and DeepPartial, and use the last one for a test fixture. That closes the type-level section. Section 4 turns to patterns: what experienced teams actually build with all of this.
DeepReadonly and DeepPartial need explicit cases for functions and arrays, or they transform things you did not mean to touch.","TypeScript stops recursion after a few dozen nested levels, or about 1,000 for tail-recursive conditional types, with “Type instantiation is excessively deep”.","readonly only blocks property assignment; methods like Date#setFullYear or Map#set still mutate a deeply readonly value.","Before shipping a clever type, ask what bug it prevents, whether a teammate can read its errors, and what it costs the editor."],"further":[{"title":"Recursive conditional types (TypeScript 4.1 release notes)","url":"https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-1.html"},{"title":"Tail-recursion elimination on conditional types (TypeScript 4.5 release notes)","url":"https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-5.html"},{"title":"Awaited utility type","url":"https://www.typescriptlang.org/docs/handbook/utility-types.html#awaitedtype"}],"quiz":[{"q":"With this definition, what is the type of o.lines?
type DeepReadonly<T> = T extends (...args: any[]) => any\n ? T\n : T extends object ? { readonly [K in keyof T]: DeepReadonly<T[K]> } : T;\ndeclare const o: DeepReadonly<{ lines: { sku: string }[] }>;{ sku: string }[], because mapped types skip arrays","why":"A homomorphic mapped type applied to an array produces an array, and here it also adds readonly."},{"text":"readonly { readonly sku: string }[]","why":"Correct. Mapping over an array type gives a readonly array, and each element is made deeply readonly by the recursive call."},{"text":"{ readonly 0: …; readonly length: number; … }, an object with numeric keys","why":"TypeScript special-cases homomorphic mapped types on arrays and tuples, so the result stays an array type."}],"answer":1},{"q":"Why does a DeepReadonly type usually need a separate branch for functions?
onSubmit would stop being callable."},{"text":"Because functions cannot be readonly in JavaScript.","why":"The concern is the type transformation, not runtime freezing; a mapped type would strip the call signature."},{"text":"Because keyof of a function type is an error.","why":"keyof of a function type is fine (it is mostly never). The problem is what the mapped type produces."}],"answer":0},{"q":"MyAwaited<T> = T extends Promise<infer V> ? MyAwaited<V> : T. What is MyAwaited<Promise<Promise<Order>>>?
Promise<Order>","why":"That is one level of unwrapping. The recursive call keeps going while the type is still a promise."},{"text":"Order","why":"Correct. The recursion unwraps one promise per step and stops when the type is no longer a promise."},{"text":"never, because nested promises do not exist at runtime","why":"The type is about what the declaration says; at runtime a resolved promise never contains another promise, which is why unwrapping all levels is right."},{"text":"An error, because a conditional type cannot refer to itself","why":"Recursive conditional types have been allowed since TypeScript 4.1."}],"answer":1},{"q":"A teammate adds a Paths<T> type that generates every dot path of the 40-field checkout state, and the editor becomes sluggish. What is the most pragmatic fix?
NoInfer so it is not computed at call sites.","why":"NoInfer only affects inference candidates; the type still has to be expanded to check arguments."},{"text":"Replace it with a narrower type, such as typed accessors for the few paths the code actually uses.","why":"Correct. A smaller, explicit type gives the same protection where it matters and costs the compiler almost nothing."}],"answer":3}],"exercise":{"kind":"web","mode":"ts","starter":{"ts":"type Checkout = {\n id: number;\n customer: { email: string; country: string };\n shipping: { method: 'standard' | 'express'; address: { line1: string; city: string } };\n lines: { sku: string; quantity: number }[];\n onSubmit: () => void;\n};\n\ntype MyAwaitedImplement three recursive types (do not use the built-in Awaited):
MyAwaited<T>: unwrap nested promises until the type is not a promise.DeepReadonly<T>: make every property at every level readonly, turn arrays into readonly arrays of deeply readonly elements, and leave functions untouched (still callable).DeepPartial<T>: make every property at every level optional, but keep arrays as they are (a fixture replaces a whole array).checkoutFixture already merges overrides at runtime; once DeepPartial is right, the nested override in the example compiles.
T), then objects (map and recurse), then everything else (return T). Arrays are objects, and a homomorphic mapped type keeps them arrays.","For DeepPartial, add a first case T extends readonly unknown[] ? T : … so arrays are not made partial."],"explanation":"MyAwaited recurses in tail position, peeling one promise per step. DeepReadonly needs a function branch because a mapped type keeps properties but drops call signatures, so onSubmit would otherwise stop being callable; arrays need no extra case because mapping over an array type yields a readonly array. DeepPartial deliberately stops at arrays, which matches how mergeDeep treats them: an override replaces the whole array. The casts in checkoutFixture are local and commented: the merge works on untyped records, and the fixture’s type is restored once at the boundary.
checkoutFixture merges nested overrides into the defaults"}},"words":728,"readMinutes":3}