Skip to content
Changelog Hub

zod 3.20.0

npm / zod / 3.20.0 source ↗

Breaking changes

There are no breaking API changes, however TypeScript versions 4.4 and earlier are no longer officially supported.

New features

The most feature-packed release since Zod 3.0!

.pipe()

A new schema method .pipe() is now available on all schemas. which can be used to chain multiple schemas into a "validation pipeline". Typically this will be used in conjunction with .transform().

z.string()
  .transform(val => val.length)
  .pipe(z.number().min(5))

The .pipe() method returns a ZodPipeline instance.

z.coerce

Zod now provides a more convenient way to coerce primitive values.

const schema = z.coerce.string();
schema.parse("tuna"); // => "tuna"
schema.parse(12); // => "12"
schema.parse(true); // => "true"

During the parsing step, the input is passed through the String() function, which is a JavaScript built-in for coercing data into strings. Note that the returned schema is a ZodString instance so you can use all string methods.

z.coerce.string().email().min(5);

All primitive types support coercion.

z.coerce.string();   // String(input)
z.coerce.number();   // Number(input)
z.coerce.boolean();  // Boolean(input)
z.coerce.bigint();   // BigInt(input)
z.coerce.date();     // new Date(input)

.catch()

A new schema method .catch() is now available on all schemas. It can be used to provide a "catchall" value that will be returned in the event of a parsing error.

const schema = z.string().catch("fallback");

schema.parse("kate"); // => "kate"
schema.parse(4); // => "fallback"

The .catch() method returns a ZodCatch instance.

z.symbol()

A long-missing hole in Zod's type system is finally filled! Thanks @santosmarco-caribou.

const schema = z.symbol();
schema.parse(Symbol('asdf'));

Relatedly, you can also pass symbols into z.literal().

const TUNA = Symbol("tuna");
const schema = z.literal(TUNA);

schema.parse(TUNA); // Symbol(tuna)
schema.parse(Symbol("nottuna")); // Error

z.string().datetime()

A new method has been added to ZodString to validate ISO datetime strings. Thanks @samchungy!

z.string().datetime();

This method defaults to only allowing UTC datetimes (the ones that end in "Z"). No timezone offsets are allowed; arbitrary sub-second precision is supported.

const dt = z.string().datetime();
dt.parse("2020-01-01T00:00:00Z"); // 🟢
dt.parse("2020-01-01T00:00:00.123Z"); // 🟢
dt.parse("2020-01-01T00:00:00.123456Z"); // 🟢 (arbitrary precision)
dt.parse("2020-01-01T00:00:00+02:00"); // 🔴 (no offsets allowed)

Offsets can be supported with the offset parameter.

const a = z.string().datetime({ offset: true });
a.parse("2020-01-01T00:00:00+02:00"); // 🟢 offset allowed

You can additionally constrain the allowable precision. This specifies the number of digits that should follow the decimal point.

const b = z.string().datetime({ precision: 3 })
b.parse("2020-01-01T00:00:00.123Z"); // 🟢 precision of 3 decimal points
b.parse("2020-01-01T00:00:00Z"); // 🔴 invalid precision

z.number().finite()

Restrict a number schema to finite values. Thanks @igalklebanov.

const schema = z.number().finite();
schema.parse(5); 🟢
schema.parse(Infinity); 🔴
schema.parse(-Infinity); 🔴

What's Changed

New Contributors

Full Changelog: https://github.com/colinhacks/zod/compare/v3.19.1...v3.20.0