diff --git a/README.md b/README.md
index d7f6f504a..442c817a6 100644
--- a/README.md
+++ b/README.md
@@ -56,6 +56,7 @@
+
Table of contents
> These docs have been translated into [Chinese](./README_ZH.md) and [Korean](./README_KO.md).
@@ -180,6 +181,7 @@
- [Changelog](#changelog)
+
Introduction
Zod is a TypeScript-first schema declaration and validation library. I'm using the term "schema" to broadly refer to any data type, from a simple `string` to a complex nested object.
@@ -197,6 +199,7 @@ Some other great aspects:
- Works with plain JavaScript too! You don't need to use TypeScript.
+
Sponsors
Sponsorship at any level is appreciated and encouraged. If you built a paid product using Zod, consider one of the [corporate tiers](https://github.com/sponsors/colinhacks).
@@ -616,6 +619,7 @@ There are a growing number of tools that are built atop or support Zod natively!
- [`zod-accelerator`](https://github.com/duplojs/duplojs-zod-accelerator): Accelerates Zod's throughput up to ~100x.
+
Installation
### Requirements
@@ -657,6 +661,7 @@ pnpm add zod@canary # pnpm
> The rest of this README assumes you are using npm and importing directly from the `"zod"` package.
+
Basic usage
Creating a simple string schema
@@ -693,6 +698,7 @@ type User = z.infer;
```
+
Primitives
```ts
@@ -722,6 +728,7 @@ z.never();
```
+
Coercion for primitives
Zod now provides a more convenient way to coerce primitive values.
@@ -779,6 +786,7 @@ schema.parse(null); // => false
For more control over coercion logic, consider using [`z.preprocess`](#preprocess) or [`z.pipe()`](#pipe).
+
Literals
Literal schemas represent a [literal type](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types), like `"hello world"` or `5`.
@@ -799,6 +807,7 @@ tuna.value; // "tuna"
> Currently there is no support for Date literals in Zod. If you have a use case for this feature, please file an issue.
+
Strings
Zod includes a handful of string-specific validations.
@@ -998,6 +1007,7 @@ ipv6Cidr.parse("192.168.1.1"); // fail
```
+
Numbers
You can customize certain error messages when creating a number schema.
@@ -1037,6 +1047,7 @@ z.number().lte(5, { message: "this👏is👏too👏big" });
```
+
BigInts
Zod includes a handful of bigint-specific validations.
@@ -1056,6 +1067,7 @@ z.bigint().multipleOf(5n); // Evenly divisible by 5n.
```
+
NaNs
You can customize certain error messages when creating a nan schema.
@@ -1068,6 +1080,7 @@ const isNaN = z.nan({
```
+
Booleans
You can customize certain error messages when creating a boolean schema.
@@ -1080,6 +1093,7 @@ const isActive = z.boolean({
```
+
Dates
Use z.date() to validate `Date` instances.
@@ -1128,6 +1142,7 @@ console.log(dateSchema.safeParse("0000-00-00").success); // false
For older zod versions, use [`z.preprocess`](#preprocess) like [described in this thread](https://github.com/colinhacks/zod/discussions/879#discussioncomment-2036276).
+
Zod enums
```ts
@@ -1184,6 +1199,7 @@ const TunaOnly = FishEnum.exclude(["Salmon", "Trout"]);
```
+
Native enums
Zod enums are the recommended approach to defining and validating enums. But if you need to validate against an enum from a third-party library (or you don't want to rewrite your existing enums) you can use `z.nativeEnum()`.
@@ -1253,6 +1269,7 @@ FruitEnum.enum.Apple; // "apple"
```
+
Optionals
You can make any schema optional with `z.optional()`. This wraps the schema in a `ZodOptional` instance and returns the result.
@@ -1282,6 +1299,7 @@ optionalString.unwrap() === stringSchema; // true
```
+
Nullables
Similarly, you can create nullable types with `z.nullable()`.
@@ -1308,6 +1326,7 @@ nullableString.unwrap() === stringSchema; // true
```
+
Objects
```ts
@@ -1577,6 +1596,7 @@ person.parse({
Using `.catchall()` obviates `.passthrough()` , `.strip()` , or `.strict()`. All keys are now considered "known".
+
Arrays
```ts
@@ -1634,6 +1654,7 @@ z.string().array().length(5); // must contain 5 items exactly
Unlike `.nonempty()` these methods do not change the inferred type.
+
Tuples
Unlike arrays, tuples have a fixed number of elements and each element can have a different type.
@@ -1660,6 +1681,7 @@ const result = variadicTuple.parse(["hello", 1, 2, 3]);
```
+
Unions
Zod includes a built-in `z.union` method for composing "OR" types.
@@ -1696,6 +1718,7 @@ console.log(optionalUrl.safeParse("not a valid url").success); // false
```
+
Discriminated unions
A discriminated union is a union of object schemas that all share a particular key.
@@ -1739,6 +1762,7 @@ const AB = z.discriminatedUnion("status", [...A.options, ...B.options]);
```
+
Records
Record schemas are used to validate types such as `Record`. This is particularly useful for storing or caching items by ID.
@@ -1794,6 +1818,7 @@ for (const key in testMap) {
As you can see, JavaScript automatically casts all object keys to strings under the hood. Since Zod is trying to bridge the gap between static and runtime types, it doesn't make sense to provide a way of creating a record schema with numerical keys, since there's no such thing as a numerical key in runtime JavaScript.
+
Maps
```ts
@@ -1804,6 +1829,7 @@ type StringNumberMap = z.infer;
```
+
Sets
```ts
@@ -1822,6 +1848,7 @@ z.set(z.string()).size(5); // must contain 5 items exactly
```
+
Intersections
Intersections are useful for creating "logical AND" types. This is useful for intersecting two object types.
@@ -1871,6 +1898,7 @@ type Teacher = z.infer;
``` -->
+
Recursive types
You can define a recursive schema in Zod, but because of a limitation of TypeScript, their type can't be statically inferred. Instead you'll need to define the type definition manually, and provide it to Zod as a "type hint".
@@ -1962,6 +1990,7 @@ Despite supporting recursive schemas, passing cyclical data into Zod will cause
> To detect cyclical objects before they cause problems, consider [this approach](https://gist.github.com/colinhacks/d35825e505e635df27cc950776c5500b).
+
Promises
```ts
@@ -1994,6 +2023,7 @@ const test = async () => {
When "parsing" a promise, Zod checks that the passed value is an object with `.then` and `.catch` methods — that's it. So you should be able to pass non-native Promises (Bluebird, etc) into `z.promise(...).parse` with no trouble. One gotcha: the return type of the parse function will be a _native_ `Promise` , so if you have downstream logic that uses non-standard Promise methods, this won't work. -->
+
Instanceof
You can use `z.instanceof` to check that the input is an instance of a class. This is useful to validate inputs against classes that are exported from third-party libraries.
@@ -2011,6 +2041,7 @@ TestSchema.parse(blob); // throws
```
+
Functions
Zod also lets you define "function schemas". This makes it easy to validate the inputs and outputs of a function without intermixing your validation code and "business logic".
@@ -2095,6 +2126,7 @@ myFunction.returnType();
* `returnType: any Zod schema` The second argument is the function's return type. This can be any Zod schema. -->
+
Preprocess
> Zod now supports primitive coercion without the need for `.preprocess()`. See the [coercion docs](#coercion-for-primitives) for more information.
@@ -2110,6 +2142,7 @@ const castToString = z.preprocess((val) => String(val), z.string());
This returns a `ZodEffects` instance. `ZodEffects` is a wrapper class that contains all logic pertaining to preprocessing, refinements, and transforms.
+
Custom schemas
You can create a Zod schema for any TypeScript type by using `z.custom()`. This is useful for creating schemas for types that are not supported by Zod out of the box, such as template string literals.
@@ -2138,6 +2171,7 @@ z.custom<...>((val) => ..., "custom error message");
```
+
Schema methods
All Zod schemas contain certain methods.
@@ -2780,6 +2814,7 @@ console.log(toBigInt.safeParse(null).success); // false
```
+
Guides and concepts
### Type inference
@@ -2950,6 +2985,7 @@ if (!result.success) {
```
+
Comparison
There are a handful of other widely-used validation libraries, but all of them have certain design limitations that make for a non-ideal developer experience.
@@ -3097,6 +3133,7 @@ Ow is focused on function input validation. It's a library that makes it easy to
If you want to validate function inputs, use function schemas in Zod! It's a much simpler approach that lets you reuse a function type declaration without repeating yourself (namely, copy-pasting a bunch of ow assertions at the beginning of every function). Also Zod lets you validate your return types as well, so you can be sure there won't be any unexpected data passed downstream.
+
Changelog
View the changelog at [CHANGELOG.md](CHANGELOG.md)
diff --git a/deno/lib/README.md b/deno/lib/README.md
index d7f6f504a..442c817a6 100644
--- a/deno/lib/README.md
+++ b/deno/lib/README.md
@@ -56,6 +56,7 @@
+
Table of contents
> These docs have been translated into [Chinese](./README_ZH.md) and [Korean](./README_KO.md).
@@ -180,6 +181,7 @@
- [Changelog](#changelog)
+
Introduction
Zod is a TypeScript-first schema declaration and validation library. I'm using the term "schema" to broadly refer to any data type, from a simple `string` to a complex nested object.
@@ -197,6 +199,7 @@ Some other great aspects:
- Works with plain JavaScript too! You don't need to use TypeScript.
+
Sponsors
Sponsorship at any level is appreciated and encouraged. If you built a paid product using Zod, consider one of the [corporate tiers](https://github.com/sponsors/colinhacks).
@@ -616,6 +619,7 @@ There are a growing number of tools that are built atop or support Zod natively!
- [`zod-accelerator`](https://github.com/duplojs/duplojs-zod-accelerator): Accelerates Zod's throughput up to ~100x.
+
Installation
### Requirements
@@ -657,6 +661,7 @@ pnpm add zod@canary # pnpm
> The rest of this README assumes you are using npm and importing directly from the `"zod"` package.
+
Basic usage
Creating a simple string schema
@@ -693,6 +698,7 @@ type User = z.infer;
```
+
Primitives
```ts
@@ -722,6 +728,7 @@ z.never();
```
+
Coercion for primitives
Zod now provides a more convenient way to coerce primitive values.
@@ -779,6 +786,7 @@ schema.parse(null); // => false
For more control over coercion logic, consider using [`z.preprocess`](#preprocess) or [`z.pipe()`](#pipe).
+
Literals
Literal schemas represent a [literal type](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types), like `"hello world"` or `5`.
@@ -799,6 +807,7 @@ tuna.value; // "tuna"
> Currently there is no support for Date literals in Zod. If you have a use case for this feature, please file an issue.
+
Strings
Zod includes a handful of string-specific validations.
@@ -998,6 +1007,7 @@ ipv6Cidr.parse("192.168.1.1"); // fail
```
+
Numbers
You can customize certain error messages when creating a number schema.
@@ -1037,6 +1047,7 @@ z.number().lte(5, { message: "this👏is👏too👏big" });
```
+
BigInts
Zod includes a handful of bigint-specific validations.
@@ -1056,6 +1067,7 @@ z.bigint().multipleOf(5n); // Evenly divisible by 5n.
```
+
NaNs
You can customize certain error messages when creating a nan schema.
@@ -1068,6 +1080,7 @@ const isNaN = z.nan({
```
+
Booleans
You can customize certain error messages when creating a boolean schema.
@@ -1080,6 +1093,7 @@ const isActive = z.boolean({
```
+
Dates
Use z.date() to validate `Date` instances.
@@ -1128,6 +1142,7 @@ console.log(dateSchema.safeParse("0000-00-00").success); // false
For older zod versions, use [`z.preprocess`](#preprocess) like [described in this thread](https://github.com/colinhacks/zod/discussions/879#discussioncomment-2036276).
+
Zod enums
```ts
@@ -1184,6 +1199,7 @@ const TunaOnly = FishEnum.exclude(["Salmon", "Trout"]);
```
+
Native enums
Zod enums are the recommended approach to defining and validating enums. But if you need to validate against an enum from a third-party library (or you don't want to rewrite your existing enums) you can use `z.nativeEnum()`.
@@ -1253,6 +1269,7 @@ FruitEnum.enum.Apple; // "apple"
```
+
Optionals
You can make any schema optional with `z.optional()`. This wraps the schema in a `ZodOptional` instance and returns the result.
@@ -1282,6 +1299,7 @@ optionalString.unwrap() === stringSchema; // true
```
+
Nullables
Similarly, you can create nullable types with `z.nullable()`.
@@ -1308,6 +1326,7 @@ nullableString.unwrap() === stringSchema; // true
```
+
Objects
```ts
@@ -1577,6 +1596,7 @@ person.parse({
Using `.catchall()` obviates `.passthrough()` , `.strip()` , or `.strict()`. All keys are now considered "known".
+
Arrays
```ts
@@ -1634,6 +1654,7 @@ z.string().array().length(5); // must contain 5 items exactly
Unlike `.nonempty()` these methods do not change the inferred type.
+
Tuples
Unlike arrays, tuples have a fixed number of elements and each element can have a different type.
@@ -1660,6 +1681,7 @@ const result = variadicTuple.parse(["hello", 1, 2, 3]);
```
+
Unions
Zod includes a built-in `z.union` method for composing "OR" types.
@@ -1696,6 +1718,7 @@ console.log(optionalUrl.safeParse("not a valid url").success); // false
```
+
Discriminated unions
A discriminated union is a union of object schemas that all share a particular key.
@@ -1739,6 +1762,7 @@ const AB = z.discriminatedUnion("status", [...A.options, ...B.options]);
```
+
Records
Record schemas are used to validate types such as `Record`. This is particularly useful for storing or caching items by ID.
@@ -1794,6 +1818,7 @@ for (const key in testMap) {
As you can see, JavaScript automatically casts all object keys to strings under the hood. Since Zod is trying to bridge the gap between static and runtime types, it doesn't make sense to provide a way of creating a record schema with numerical keys, since there's no such thing as a numerical key in runtime JavaScript.
+
Maps
```ts
@@ -1804,6 +1829,7 @@ type StringNumberMap = z.infer;
```
+
Sets
```ts
@@ -1822,6 +1848,7 @@ z.set(z.string()).size(5); // must contain 5 items exactly
```
+
Intersections
Intersections are useful for creating "logical AND" types. This is useful for intersecting two object types.
@@ -1871,6 +1898,7 @@ type Teacher = z.infer;
``` -->
+
Recursive types
You can define a recursive schema in Zod, but because of a limitation of TypeScript, their type can't be statically inferred. Instead you'll need to define the type definition manually, and provide it to Zod as a "type hint".
@@ -1962,6 +1990,7 @@ Despite supporting recursive schemas, passing cyclical data into Zod will cause
> To detect cyclical objects before they cause problems, consider [this approach](https://gist.github.com/colinhacks/d35825e505e635df27cc950776c5500b).
+
Promises
```ts
@@ -1994,6 +2023,7 @@ const test = async () => {
When "parsing" a promise, Zod checks that the passed value is an object with `.then` and `.catch` methods — that's it. So you should be able to pass non-native Promises (Bluebird, etc) into `z.promise(...).parse` with no trouble. One gotcha: the return type of the parse function will be a _native_ `Promise` , so if you have downstream logic that uses non-standard Promise methods, this won't work. -->
+
Instanceof
You can use `z.instanceof` to check that the input is an instance of a class. This is useful to validate inputs against classes that are exported from third-party libraries.
@@ -2011,6 +2041,7 @@ TestSchema.parse(blob); // throws
```
+
Functions
Zod also lets you define "function schemas". This makes it easy to validate the inputs and outputs of a function without intermixing your validation code and "business logic".
@@ -2095,6 +2126,7 @@ myFunction.returnType();
* `returnType: any Zod schema` The second argument is the function's return type. This can be any Zod schema. -->
+
Preprocess
> Zod now supports primitive coercion without the need for `.preprocess()`. See the [coercion docs](#coercion-for-primitives) for more information.
@@ -2110,6 +2142,7 @@ const castToString = z.preprocess((val) => String(val), z.string());
This returns a `ZodEffects` instance. `ZodEffects` is a wrapper class that contains all logic pertaining to preprocessing, refinements, and transforms.
+
Custom schemas
You can create a Zod schema for any TypeScript type by using `z.custom()`. This is useful for creating schemas for types that are not supported by Zod out of the box, such as template string literals.
@@ -2138,6 +2171,7 @@ z.custom<...>((val) => ..., "custom error message");
```
+
Schema methods
All Zod schemas contain certain methods.
@@ -2780,6 +2814,7 @@ console.log(toBigInt.safeParse(null).success); // false
```
+
Guides and concepts
### Type inference
@@ -2950,6 +2985,7 @@ if (!result.success) {
```
+
Comparison
There are a handful of other widely-used validation libraries, but all of them have certain design limitations that make for a non-ideal developer experience.
@@ -3097,6 +3133,7 @@ Ow is focused on function input validation. It's a library that makes it easy to
If you want to validate function inputs, use function schemas in Zod! It's a much simpler approach that lets you reuse a function type declaration without repeating yourself (namely, copy-pasting a bunch of ow assertions at the beginning of every function). Also Zod lets you validate your return types as well, so you can be sure there won't be any unexpected data passed downstream.
+
Changelog
View the changelog at [CHANGELOG.md](CHANGELOG.md)