Zod · all subjects

transforms

9 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Transform changes input and output types

The .transform() API can convert the input type to a different output type. When using transforms, the input and output types of a schema can diverge, requiring use of z.input<> and z.output<> to extract them separately.

Mutating transforms work in both directions

Mutating transforms like z.string().trim() or z.string().toLowerCase() work in both decode and encode directions. schema.decode(" hello ") and schema.encode(" hello ") both return "hello".

.transform() is unidirectional, cannot be encoded

.transform() API implements unidirectional transformation. If any .transform() exists anywhere in a schema, attempting z.encode() will throw a runtime error (not ZodError): "Encountered unidirectional transform during encode: ZodTransform".

Pipes chain schemas together

Schemas can be chained into pipes using .pipe(). Example: z.string().pipe(z.transform(val => val.length)). Pipes are primarily useful with transforms to perform initial validation then transform the parsed data.

z.transform() convenience method

Zod provides a convenience .transform() method on schemas as syntactic sugar for piping into a transform. Example: z.string().transform(val => val.length) instead of z.string().pipe(z.transform(val => val.length)). This method is not available in Zod Mini.

async transforms require parseAsync

If you use async transforms, you must use .parseAsync() or .safeParseAsync() when parsing data. Otherwise Zod will throw an error. Example: const idToUser = z.string().transform(async (id) => { return db.getUserById(id); }); const user = await idToUser.parseAsync("abc123");

Transform functions should never throw

Transform functions should not throw errors as thrown errors are not caught by Zod. Instead, use ctx to push validation issues if needed.

z.transform() accepts ctx parameter for validation issues

Transform functions can receive a second ctx parameter to report validation issues. Example: z.transform((val, ctx) => { if (error) { ctx.issues.push({ code: "custom", message: "Not a number", input: val }); return z.NEVER; } return parsed; }). Use z.NEVER as a special constant to exit the transform without impacting the inferred return type.

z.preprocess() utility for common pipe pattern

z.preprocess() is a convenience function for piping a transform into another schema. Example: z.preprocess((val) => { if (typeof val === "string") { return Number.parseInt(val); } return val; }, z.int()). By default, input type is unknown, but you can narrow it by annotating the parameter: (val: string | null | undefined) => val?.trim() ?? "".

Give your agent this brain