readonly() freezes parsed objects at runtime
When parsing with .readonly(), the result is frozen with Object.freeze() to prevent modifications. Attempts to modify the result throw TypeError.
schema basics
13 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
Primitive types in Zod
Zod provides the following primitive type schemas: z.string(), z.number(), z.bigint(), z.boolean(), z.symbol(), z.undefined(), z.null().
z.coerce for type coercion
Use z.coerce instead of primitive types to coerce input data to the appropriate type. Available coerce schemas: z.coerce.string() (uses String(input)), z.coerce.number() (uses Number(input)), z.coerce.boolean() (uses Boolean(input)), z.coerce.bigint() (uses BigInt(input)), z.coerce.date() (uses new Date(input)). The input type of coerce schemas is unknown by default; specify a generic parameter to customize it, e.g., z.coerce.number<number>().
z.coerce.boolean() coerces using truthiness rules
z.coerce.boolean() uses Boolean(input) which converts any truthy value to true and any falsy value to false. Truthy values like 'tuna', 'true', 'false', 1, and [] all coerce to true. Falsy values like 0, '', undefined, and null coerce to false.
z.optional() and z.nullable() for null/undefined handling
z.optional(schema) or schema.optional() makes a schema accept undefined inputs. z.nullable(schema) or schema.nullable() makes a schema accept null inputs. Both return wrapper instances. Extract inner schema with .unwrap() in Zod or .def.innerType in Zod Mini.
z.nullish() combines optional and nullable
z.nullish(schema) makes a schema both optional and nullable, accepting undefined and null inputs.
z.any() and z.unknown() special types
z.any() and z.unknown() mirror TypeScript's type system. Both allow any values. As object properties, their keys are required (matching { a: any } in TypeScript). Use z.any().optional() or z.unknown().optional() to make them truly optional.
z.never() rejects all values
z.never() no value will pass validation. Inferred type is never.
default() shortcircuits parsing
Setting a default value with .default() will shortcircuit the parsing process. If the input is undefined, the default value is eagerly returned without running the rest of validation. The default value must be assignable to the output type of the schema.
default() accepts function for re-execution
The .default() method can accept a function instead of a value. The function will be re-executed whenever a default value needs to be generated. Example: z.number().default(Math.random) will generate a new random number each time.
prefault() vs default() for transforms
prefault() ("pre-parse default") differs from default(): prefault() is used when input is undefined but the value still goes through the parsing process. The prefault value must be assignable to the input type. Example: z.string().transform(val => val.length).prefault("tuna") returns 4, while .default("tuna") would return "tuna".
prefault() useful for refinements like trim
prefault() is useful when you want to pass an input value through mutating refinements. Example: z.string().trim().toUpperCase().prefault(" tuna ") returns "TUNA" because the prefault value goes through trim() and toUpperCase().
readonly() marks schema as readonly
Use .readonly() to mark a schema as readonly. The inferred type becomes readonly. Example: z.object({ name: z.string() }).readonly() infers to Readonly<{ name: string }>. In TypeScript, readonly only affects objects, arrays, tuples, Set, and Map.