Immutable configuration
Expose validated configuration without allowing callers to mutate the parsed object.
Zod · Module
.readonly
.readonly() marks a schema’s inferred output as readonly and freezes the parsed result at runtime. It supports objects, arrays, tuples, Set, and Map.
How it works
Calling .readonly() wraps a schema so its parsed output receives a readonly TypeScript type and is frozen at runtime with Object.freeze(). The input is validated by the underlying schema first, then the resulting object, array, tuple, Set, or Map is made non-modifiable.
Syntax
schema.readonly() => readonly schemaReturns
A readonly schema whose parsed result is frozen.
Key points
- Call
.readonly()on a schema when its parsed output should be readonly. - Zod exposes readonly semantics in the inferred TypeScript type.
- Readonly arrays infer as readonly element arrays.
- Readonly tuples retain their positions and element types while becoming readonly.
- Readonly maps preserve the key and value types through a ReadonlyMap result.
- Readonly sets infer as ReadonlySet with the original element type.
Common mistakes
- The readonly type treatment applies only to objects, arrays, tuples, Set, and Map.
- Freezing happens after normal parsing, so readonly does not replace validation.
Example: Readonly object schema
import { z } from "zod";
const ReadonlyUser = z.object({ name: z.string() }).readonly();
const user = ReadonlyUser.parse({ name: "Ada" });
console.log(user.name); // Ada
// user.name = "Grace"; // TypeScript error; the parsed object is frozen
Creates a readonly object schema, parses valid input, and returns a frozen result.
When to use it
Readonly collections
Return validated collections whose TypeScript types and runtime values discourage modification.
Interview questions
QWhat does .readonly() do?
.readonly() returns a schema whose inferred output is marked readonly. It parses with the base schema and then freezes the result with Object.freeze().
Follow-up: Which output types does the documentation specifically call out? Objects, arrays, tuples, Set, and Map receive the readonly treatment.
QHow does readonly affect types and runtime values?
For an object schema, the inferred output uses readonly properties, such as Readonly<{ name: string }>. At runtime, the parsed object is frozen to prevent modifications.
Follow-up: Does it validate before freezing? Yes; parsing uses the underlying schema first, and freezing is applied to the parsed result.
QWhich schema shapes can be made readonly?
The method can be applied to arrays, tuples, maps, and sets as well as objects. The documentation shows outputs such as readonly string[], readonly [string, number], ReadonlyMap<string, Date>, and ReadonlySet<string>.
Follow-up: What happens to invalid input? The base schema still rejects it during normal parsing before any freezing occurs.
Related
z.objectz.arrayz.tuplez.mapz.setObject.freeze