Skip to content

Releases: colinhacks/zod

v3.21.1

06 Mar 02:52
@github-actions github-actions
v3.21.1
942e2db
Compare
Choose a tag to compare
v3.21.1

Features

Support for ULID validation

z.string().ulid();

Commits:

Assets 2
Loading

v3.21.0

04 Mar 10:33
@github-actions github-actions
v3.21.0
0aa6021
Compare
Choose a tag to compare
v3.21.0

Features

z.string().emoji()

Thanks @joseph-lozano for #2045! To validate that all characters in a string are emoji:

z.string().emoji()

...if that's something you want to do for some reason.

z.string().cuid2()

Thanks @joulev for #1813! To validate CUIDv2:

z.string().cuid2()

z.string().ip()

Thanks @fvckDesa for #2066. To validate that a string is a valid IP address:

const v4IP = "122.122.122.122";
const v6IP = "6097:adfa:6f0b:220d:db08:5021:6191:7990";

// matches both IPv4 and IPv6 by default
const ipSchema = z.string().ip();
ipSchema.parse(v4IP) //  pass
ipSchema.parse(v6IP) //  pass

To specify a particular version:

const ipv4Schema = z.string().ip({ version: "v4" });
const ipv6Schema = z.string().ip({ version: "v6" });

z.bigint().{gt|gte|lt|lte}()

Thanks @igalklebanov for #1711! ZodBigInt gets the same set of methods found on ZodNumber:

z.bigint().gt(BigInt(5));
z.bigint().gte(BigInt(5));
z.bigint().lt(BigInt(5));
z.bigint().lte(BigInt(5));
z.bigint().positive();
z.bigint().negative();
z.bigint().nonnegative();
z.bigint().nonpositive();
z.bigint().multipleOf(BigInt(5));

z.enum(...).extract() and z.enum(...).exclude()

Thanks @santosmarco-caribou for #1652! To add or remove elements from a ZodEnum:

const FoodEnum = z.enum(["Pasta", "Pizza", "Tacos", "Burgers", "Salad"]);
const ItalianEnum = FoodEnum.extract(["Pasta", "Pizza"]); // ZodEnum<["Pasta", "Pizza"]>
const UnhealthyEnum = FoodEnum.exclude(["Salad"]); // ZodEnum<["Pasta", "Pizza", "Tacos", "Burgers"]>

This API is inspired by the Exclude and Extract TypeScript built-ins.

Pass a function to .catch()

Thanks @0xWryth for #2087! The .catch() method now accepts a function that receives the caught error:

const numberWithErrorCatch = z.number().catch((ctx) => {
  ctx.error; // ZodError
  return 42;
});

Compiler performance

Zod 3.20.2 introduced an accidental type recursion that caused long compilation times for some users. These kinds of bugs are very hard to diagnose. Big shoutout to @gydroperit for some heroic efforts here: #2107 Zod 3.21 resolves these issues:

Commits:

Contributors

0xWryth, gydroperit, and 5 other contributors
Assets 2
Loading

v3.20.6

09 Feb 09:15
@github-actions github-actions
v3.20.6
e693919
Compare
Choose a tag to compare
v3.20.6

Commits:

Assets 2
Loading

v3.20.5

08 Feb 19:50
@github-actions github-actions
v3.20.5
e71c7be
Compare
Choose a tag to compare
v3.20.5

Commits:

  • e71c7be Fix extract/exclude type error
Assets 2
Loading

v3.20.4

08 Feb 19:34
@github-actions github-actions
v3.20.4
c8ce27e
Compare
Choose a tag to compare
v3.20.4

Commits:

Assets 2
Loading

v3.20.3

08 Feb 08:04
@github-actions github-actions
v3.20.3
fee81ca
Compare
Choose a tag to compare
v3.20.3

Features

Fixes and documentation

New Contributors

Full Changelog: v3.20.2...v3.20.3

Contributors

matthewfallshaw, mitchwd, and 28 other contributors
Assets 2
Loading

v3.20.2

12 Dec 21:13
@github-actions github-actions
v3.20.2
c9e4ed4
Compare
Choose a tag to compare
v3.20.2

Commits:

Assets 2
Loading

v3.20.1

12 Dec 20:09
@github-actions github-actions
v3.20.1
1161b8f
Compare
Choose a tag to compare
v3.20.1

Commits:

Assets 2
Loading

v3.20

12 Dec 09:45
@colinhacks colinhacks
v3.20
f19c0f2
Compare
Choose a tag to compare
v3.20

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: v3.20.0...v3.20

Contributors

maxArturo, aiji42, and 12 other contributors
Assets 2
Loading

v3.20.0-beta

04 Dec 07:42
@colinhacks colinhacks
v3.20.0
0ffeb4d
This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
GPG key ID: 4AEE18F83AFDEB23
Expired
Learn about vigilant mode.
Compare
Choose a tag to compare
v3.20.0-beta Pre-release
Pre-release

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: v3.19.1...v3.20.0

Contributors

diogob, KATT, and 18 other contributors
Assets 2
Loading