TypeScript `ReadonlyDeep<T>` Without a Library: Writing the Recursive Utility Type Once and Never Again

A developer has published a self-contained TypeScript utility type, ReadonlyDeep<T>, that recursively applies readonly modifiers to every property at every nesting depth, closing the gap left by the built-in Readonly<T>, which only protects top-level properties. The implementation branches on primitives, functions, arrays (via infer and ReadonlyArray), and objects, using a mapped type that recurses into each key. The writeup notes the basic version breaks down for Map and Set, which require ReadonlyMap and ReadonlySet, and demonstrates compile-time errors on nested mutations without any runtime checks or library dependency.

ReadonlyDeep<T Without a Library: Writing the Recursive Utility Type Once and Never Again This article was written with the assistance of AI, under human supervision and review. TypeScript's built-in Readonly<T type applies immutability to top-level properties but stops there. Nested objects remain mutable. When a developer marks a configuration object as readonly and a teammate mutates a nested property three levels deep, the compiler stays silent. The bug appears in production. Problem flow showing built-in Readonly allowing nested mutations A recursive readonly type solves this. Every property at every depth becomes immutable. The compiler catches mutations before they ship. Solution flow showing ReadonlyDeep preventing all mutations Readonly<T only protects top-level properties; nested objects remain mutable and cause silent bugs. The type signature needs to handle every TypeScript construct. Primitives like string , number , and boolean pass through unchanged. Functions preserve their signatures. Arrays become readonly arrays. Objects recurse into their properties. Type hierarchy showing ReadonlyDeep branching by input type The recursive case is where the type earns its place. For each property K in object T , the type constructs a new object with K mapped to ReadonlyDeep<T K . The recursion stops when it hits a primitive or function. TypeScript's conditional types make this possible. The pattern T extends Primitive ? T : ... lets the type branch based on structure. Each branch handles a different category. The built-in Readonly<T handles the shallow case. ReadonlyDeep<T wraps it with recursion. The combination creates a type that descends through arbitrarily nested structures. The implementation starts with a type alias for primitives. This includes string , number , boolean , symbol , bigint , undefined , and null . Functions count as primitives here because their internal structure does not require recursion. type Primitive = | string | number | boolean | symbol | bigint | undefined | null; type ReadonlyDeep<T = T extends Primitive ? T : T extends Function ? T : T extends infer U ? ReadonlyArray<ReadonlyDeep<U : { readonly K in keyof T : ReadonlyDeep<T K ; }; The first condition checks if T is a primitive. If so, the type returns T unchanged. The second condition handles functions. The third condition matches arrays using the infer pattern and wraps them in ReadonlyArray . The final case handles objects. The mapped type iterates over every key K in T . Each property becomes readonly , and the value type becomes ReadonlyDeep<T K . The recursion happens here. This version works for most cases. A configuration object with nested arrays and objects becomes fully immutable: interface Config { database: { host: string; port: number; credentials: { username: string; password: string; }; }; features: string ; } type ImmutableConfig = ReadonlyDeep<Config ; const config: ImmutableConfig = { database: { host: "localhost", port: 5432, credentials: { username: "admin", password: "secret", }, }, features: "caching", "logging" , }; // All of these produce compile-time errors: config.database.port = 3306; // Error: Cannot assign to 'port' config.database.credentials.password = "newpass"; // Error config.features.push "metrics" ; // Error: Property 'push' does not exist config.features 0 = "telemetry"; // Error: Index signature is readonly The compiler blocks every mutation attempt. No runtime checks. No library dependency. TypeScript error panel showing blocked mutations on deeply nested readonly properties The basic implementation breaks down with Map and Set . These types have methods like set and add that mutate internal state. TypeScript's ReadonlyMap and ReadonlySet types exist for this reason. The extended version adds conditions for these collections: type Primitive = | string | number | boolean | symbol | bigint | undefined | null; type ReadonlyDeep<T = T extends Primitive ? T : T extends Function ? T : T extends Map<infer K, infer V ? ReadonlyMap<K, ReadonlyDeep<V : T extends Set<infer U ? ReadonlySet<ReadonlyDeep<U : T extends infer U ? ReadonlyArray<ReadonlyDeep<U : { readonly K in keyof T : ReadonlyDeep<T K ; }; The Map branch infers key and value types, wraps the value in ReadonlyDeep , and returns ReadonlyMap . The Set branch does the same with ReadonlySet . Both prevent mutations while preserving read operations. Functions with properties require careful handling. A function can have properties attached to it, and those properties should become readonly: interface Logger { message: string : void; level: string; } type ReadonlyLogger = ReadonlyDeep<Logger ; const logger: ReadonlyLogger = Object.assign message: string = console.log message , { level: "info" } ; logger "test" ; // Works logger.level = "debug"; // Error: Cannot assign to 'level' The function condition in the type needs to come after the primitive check but before the object recursion. This preserves the function signature while applying readonly to any attached properties. Arrays of arrays require the recursion to work properly. The type string becomes ReadonlyArray<ReadonlyArray<string . Each level of nesting applies both ReadonlyArray and ReadonlyDeep to the inner type. For more on working with readonly collections, see ReadonlyMap and ReadonlySet in TypeScript https://jsmanifest.com/readonlymap-readonlyset-typescript . The type-fest library provides a ReadonlyDeep implementation with additional features. It handles classes, preserves function properties, and includes special cases for built-in types. The tradeoff is complexity. Comparison of three ReadonlyDeep approaches The custom implementation covers objects, arrays, functions, Maps, and Sets. This handles 95% of use cases in application code. Type-fest adds support for classes with private fields, WeakMaps, Promises, and other specialized types. Here's the comparison on a complex type: interface APISchema { users: Map< string, { profile: { name: string; tags: string ; }; settings: Set<string ; } ; metadata: { version: number; handlers: Array< data: unknown = void ; }; } // Custom implementation handles this correctly: type ImmutableSchema = ReadonlyDeep<APISchema ; // type-fest adds these guarantees: // - Class instances preserve private field types // - WeakMap and WeakSet get readonly versions // - Promise values become readonly // - Tuple types preserve length and ordering For most codebases, the custom version works. The compiler errors guide you when edge cases appear. Adding type-fest as a dependency makes sense when you hit repeated gaps in coverage. The maintenance burden differs. A custom utility type lives in the codebase and requires updates when TypeScript adds new built-in types. Type-fest tracks these changes and ships updates. Teams building component libraries or TypeScript tooling benefit from type-fest's thoroughness. Application developers building features on a known stack rarely need that level of coverage. For related patterns on partial immutability, see Partial, Required, and DeepPartial in TypeScript https://jsmanifest.com/partial-required-deeppartial-typescript-2026 . API response types become safer with ReadonlyDeep . A response handler receives data from the network and should not modify it. The readonly constraint prevents accidental mutations that break caching or introduce race conditions. interface UserResponse { user: { id: string; profile: { name: string; email: string; preferences: { theme: string; notifications: string ; }; }; }; metadata: { timestamp: number; version: string; }; } async function fetchUser id: string : Promise<ReadonlyDeep<UserResponse { const response = await fetch /api/users/${id} ; return response.json ; } async function displayUser id: string { const data = await fetchUser id ; // All mutation attempts blocked: data.user.profile.name = "Modified"; // Error data.user.profile.preferences.notifications.push "email" ; // Error data.metadata.timestamp = Date.now ; // Error // Reading works normally: console.log data.user.profile.name ; console.log data.user.profile.preferences.theme ; } Data flow showing readonly API response preventing mutations Configuration objects gain the same protection. Application config loads once at startup and should never change. Making it readonly catches bugs where code tries to modify settings based on runtime conditions. interface AppConfig { server: { port: number; host: string; ssl: { enabled: boolean; certPath: string; }; }; database: { connections: Array<{ name: string; url: string; poolSize: number; } ; }; features: Map<string, boolean ; } let config: ReadonlyDeep<AppConfig ; function loadConfig : ReadonlyDeep<AppConfig { // Load from environment or config file return { server: { port: 3000, host: "0.0.0.0", ssl: { enabled: true, certPath: "/etc/ssl/cert.pem", }, }, database: { connections: { name: "primary", url: "postgresql://localhost/db", poolSize: 10, }, , }, features: new Map "caching", true , "telemetry", false , , }; } function initializeApp { config = loadConfig ; // Runtime modifications blocked: config.server.port = 4000; // Error config.database.connections 0 .poolSize = 20; // Error config.features.set "logging", true ; // Error } IDE tooltip showing readonly error when attempting to modify nested config property Form validation schemas work well with readonly types. The schema defines structure and constraints. Validators read from it but should not modify it. See Custom Form Validators in TypeScript https://jsmanifest.com/typescript-form-validators-custom for validator patterns. State management libraries benefit from readonly types. Redux state, Zustand stores, and React context values all gain safety when typed as ReadonlyDeep . The compiler prevents direct mutations and forces proper update patterns. TypeScript's type checker has recursion limits. Deep nesting or large object types can hit these limits and cause compilation errors. The practical limit sits around 10 levels of nesting for complex types. Type checking performance showing degradation with nesting depth A type with 100 properties at 3 levels deep creates 100^3 = 1,000,000 type instantiations. The compiler caches these, but initial compilation takes time. Watch for slow type checking during development. The workaround is to limit recursion depth. Add a depth parameter that decrements with each recursion: type Primitive = | string | number | boolean | symbol | bigint | undefined | null; type ReadonlyDeep<T, Depth extends number = 10 = Depth extends 0 ? Readonly<T : T extends Primitive ? T : T extends Function ? T : T extends Map<infer K, infer V ? ReadonlyMap<K, ReadonlyDeep<V, Prev<Depth : T extends Set<infer U ? ReadonlySet<ReadonlyDeep<U, Prev<Depth : T extends infer U ? ReadonlyArray<ReadonlyDeep<U, Prev<Depth : { readonly K in keyof T : ReadonlyDeep<T K , Prev<Depth ; }; type Prev<N extends number = N extends 0 ? 0 : N extends 1 ? 0 : N extends 2 ? 1 : N extends 3 ? 2 : N extends 4 ? 3 : N extends 5 ? 4 : N extends 6 ? 5 : N extends 7 ? 6 : N extends 8 ? 7 : N extends 9 ? 8 : N extends 10 ? 9 : never; This version stops recursing after 10 levels and falls back to shallow Readonly . The Prev helper decrements the depth counter. When depth reaches zero, recursion stops. Measure compilation time with tsc --diagnostics . Look for the "Type checking time" metric. If it exceeds one second, investigate which types cause the slowness. Large codebases should apply ReadonlyDeep selectively. Configuration objects, API responses, and constants benefit from it. Internal implementation types that change frequently create unnecessary compilation overhead. The type system overhead is zero at runtime. ReadonlyDeep is purely a compile-time construct. The JavaScript output contains no traces of it. Const assertions make literal types as narrow as possible and add shallow readonly to objects. ReadonlyDeep applies deep immutability to existing type definitions. Use const assertions for inline objects and ReadonlyDeep for reusable types. No. Circular type references cause infinite recursion in TypeScript's type checker. The depth-limited version prevents compiler hangs but does not make circular structures readonly. Avoid circular references or use shallow Readonly for those cases. Yes. Pass generic types to ReadonlyDeep like any other type. The recursion applies to whatever type the generic resolves to at usage time. No. TypeScript types disappear at runtime. ReadonlyDeep provides compile-time safety only. Use Object.freeze for runtime immutability or combine both approaches for defense in depth. No. Apply it to data that should not change: configuration, API responses, constants. Internal implementation types that undergo frequent mutations benefit from normal mutability. Overuse creates friction without safety gains. The ReadonlyDeep<T utility type solves the nested mutability problem that built-in Readonly<T leaves open. Thirty lines of code eliminate an entire class of bugs. The compiler catches mutations at every depth before they reach production. The implementation handles objects, arrays, functions, Maps, and Sets. Edge cases exist but rarely matter in application code. Teams that need comprehensive coverage can reach for type-fest. Teams building features on standard types can write this once and never think about it again. Configuration objects and API responses gain immediate safety benefits. State management becomes more predictable. The type system enforces immutability contracts that previously existed only in documentation. Compilation time matters for large schemas. Measure performance and limit recursion depth when needed. The tradeoff between safety and build speed is concrete and measurable. Adding this utility type to a codebase takes five minutes and prevents mutations that take hours to debug.