In TypeScript, what does the `readonly` modifier on an object-type property such as `readonly db: { url: string }` actually prevent, and what does it leave untouched?

## What the modifier restricts ```ts interface Config { readonly db: { url: string }; readonly retries: number; } declare const config: Config; config.retries = 5; // error: Cannot assign to 'retries' because it is a read-only property. config.db.url = 'other'; // no error ``` The modifier attaches to the *property slot* as seen through this type. Writing to the slot is rejected; doing anything to the value stored in the slot is not the modifier's business. ## Shallow, and deliberately so This is the single most-tested consequence. `readonly` does not recurse. Everything reachable through the property remains mutable: ```ts interface Session { readonly user: { name: string }; readonly tags: string[]; } declare const s: Session; s.user.name = 'mallory'; // ok — the nested object is not readonly s.tags.push('admin'); // ok — the array itself is mutable s.tags = []; // error — this writes the slot ``` To lock the contents you must say so at each level: `readonly user: { readonly name: string }` and `readonly tags: readonly string[]`. There is no flag that makes `readonly` deep. ## `readonly` versus `const` They solve different problems and are not alternatives. `const` fixes a *binding*: the variable cannot be pointed at another value, though the object it holds can be mutated. `readonly` fixes a *property* of a type: any variable holding a value of that type cannot write that property. `const` is a JavaScript declaration with runtime meaning; `readonly` is a type-layer annotation with none. You commonly want both, and they do not overlap. ## It emits nothing After compilation there is no trace. No `Object.defineProperty` with `writable: false`, no `Object.freeze`, no throwing setter. Two consequences follow. First, the guarantee only covers code the checker inspects. A value handed to plain JavaScript, or reached through `any`, or produced by a type assertion, can be written to without complaint: ```ts (config as { retries: number }).retries = 99; // compiles, and mutates ``` Second, `readonly` costs nothing at runtime — there is no property-descriptor lookup, no defensive copy, no allocation. It is free documentation with a checker behind it, which is why marking public API surfaces `readonly` is cheap and worth doing. ## Where it is genuinely load-bearing The modifier earns its keep in three places. In shared configuration or dependency objects, it stops a distant module from reaching in and reassigning a field that everything else has already read. In function parameters, declaring a parameter type with `readonly` properties states that the function will not write through it, which is a real part of the signature's meaning. And in inferred literal types produced by a `const` assertion, `readonly` appears automatically on every property, which is how those types stay stable enough to be used as sources of literal types. ## The parts candidates get wrong The two classic mistakes are believing the modifier is deep and believing it does something at runtime. A third, subtler one: `readonly` is not consulted when the checker decides whether one object type is assignable to another, so the property can be written through an alias of a mutable type. That hole is worth knowing about in its own right, and it is why `readonly` is best described as "a read-only *view*" rather than "an immutable value". ## A working mental model Treat `readonly` as a promise your own code makes to itself, enforced only where types are honoured, only one level deep, and only until someone writes an assertion. That framing gets every downstream question right: use it liberally for intent, use `readonly` recursively when the contents matter, and reach for a runtime mechanism when the data genuinely must not change.