zod 3.16.0 → 3.16.1

package/README.md

@@ -1,7 +1,13 @@
 <p align="center">
-  <img src="logo.svg" width="200px" align="center" />
+  <img src="logo.svg" width="200px" align="center" alt="Zod logo" />
   <h1 align="center">Zod</h1>
+  <p align="center">
+    ✨ <a href="https://zod.dev">https://zod.dev</a> ✨
+    <br/>
+    TypeScript-first schema validation with static type inference
+  </p>
 </p>
+<br/>
 <p align="center">
 <a href="https://github.com/colinhacks/zod/actions?query=branch%3Amaster"><img src="https://github.com/colinhacks/zod/actions/workflows/test.yml/badge.svg?event=push&branch=master" alt="Zod CI status" /></a>
 <a href="https://twitter.com/colinhacks" rel="nofollow"><img src="https://img.shields.io/badge/created%20by-@colinhacks-4BBAAB.svg" alt="Created by Colin McDonnell"></a>
@@ -12,6 +18,8 @@
 </p>
 
 <div align="center">
+  <a href="https://zod.dev">Documentation</a>
+  <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
   <a href="https://discord.gg/RcG33DQJdf">Discord</a>
   <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
   <a href="https://www.npmjs.com/package/zod">NPM</a>
@@ -24,61 +32,62 @@
   <br />
 </div>
 
+<br/>
 <br/>
 
-These docs have been translated into [Chinese](./README_ZH.md).
+> These docs have been translated into [Chinese](./README_ZH.md).
 
-# Table of contents
+## Table of contents
 
 <!-- The full documentation is available both on the [official documentation site](https://zod.js.org/) (recommended) and in `README.md`.
 
-### Go to [zod.js.org](https://zod.js.org) >> -->
+#### Go to [zod.js.org](https://zod.js.org) >> -->
 
-- [What is Zod](#what-is-zod)
+- [Introduction](#introduction)
+  - [Sponsors](#sponsors)
+  - [Ecosystem](#ecosystem)
 - [Installation](#installation)
-- [Ecosystem](#ecosystem)
 - [Basic usage](#basic-usage)
-- [Defining schemas](#defining-schemas)
-  - [Primitives](#primitives)
-  - [Literals](#literals)
-  - [Strings](#strings)
-  - [Numbers](#numbers)
-  - [NaNs](#nans)
-  - [Booleans](#booleans)
-  - [Dates](#dates)
-  - [Zod enums](#zod-enums)
-  - [Native enums](#native-enums)
-  - [Optionals](#optionals)
-  - [Nullables](#nullables)
-  - [Objects](#objects)
-    - [.shape](#shape)
-    - [.extend](#extend)
-    - [.merge](#merge)
-    - [.pick/.omit](#pickomit)
-    - [.partial](#partial)
-    - [.deepPartial](#deepPartial)
-    - [.passthrough](#passthrough)
-    - [.strict](#strict)
-    - [.strip](#strip)
-    - [.catchall](#catchall)
-  - [Arrays](#arrays)
-    - [.element](#element)
-    - [.nonempty](#nonempty)
-    - [.min/.max/.length](#minmaxlength)
-  - [Tuples](#tuples)
-  - [Records](#records)
-  - [Maps](#maps)
-  - [Sets](#sets)
-  - [Unions](#unions)
-    - [Discriminated Unions](#discriminated-unions)
-  - [Recursive types](#recursive-types)
-    - [JSON type](#json-type)
-    - [Cyclical data](#cyclical-objects)
-  - [Promises](#promises)
-  - [Instanceof](#instanceof)
-  - [Function schemas](#function-schemas)
-  - [Preprocess](#preprocess)
-- [Schema methods](#zodtype-methods-and-properties)
+- [Primitives](#primitives)
+- [Literals](#literals)
+- [Strings](#strings)
+- [Numbers](#numbers)
+- [NaNs](#nans)
+- [Booleans](#booleans)
+- [Dates](#dates)
+- [Zod enums](#zod-enums)
+- [Native enums](#native-enums)
+- [Optionals](#optionals)
+- [Nullables](#nullables)
+- [Objects](#objects)
+  - [.shape](#shape)
+  - [.extend](#extend)
+  - [.merge](#merge)
+  - [.pick/.omit](#pickomit)
+  - [.partial](#partial)
+  - [.deepPartial](#deepPartial)
+  - [.passthrough](#passthrough)
+  - [.strict](#strict)
+  - [.strip](#strip)
+  - [.catchall](#catchall)
+- [Arrays](#arrays)
+  - [.element](#element)
+  - [.nonempty](#nonempty)
+  - [.min/.max/.length](#minmaxlength)
+- [Tuples](#tuples)
+- [Unions](#unions)
+- [Discriminated Unions](#discriminated-unions)
+- [Records](#records)
+- [Maps](#maps)
+- [Sets](#sets)
+- [Recursive types](#recursive-types)
+  - [JSON type](#json-type)
+  - [Cyclical data](#cyclical-objects)
+- [Promises](#promises)
+- [Instanceof](#instanceof)
+- [Function schemas](#function-schemas)
+- [Preprocess](#preprocess)
+- [Schema methods](#schema-methods)
   - [.parse](#parse)
   - [.parseAsync](#parseasync)
   - [.safeParse](#safeparse)
@@ -98,6 +107,7 @@ These docs have been translated into [Chinese](./README_ZH.md).
   - [Type inference](#type-inference)
   - [Writing generic functions](#writing-generic-functions)
   - [Error handling](#error-handling)
+  - [Error formatting](#error-formatting)
 - [Comparison](#comparison)
   - [Joi](#joi)
   - [Yup](#yup)
@@ -107,7 +117,7 @@ These docs have been translated into [Chinese](./README_ZH.md).
 
 <!-- **Zod 2 is coming! Follow [@colinhacks](https://twitter.com/colinhacks) to stay updated and discuss the future of Zod.** -->
 
-# What is Zod
+## 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.
 
@@ -123,17 +133,17 @@ Some other great aspects:
 - Functional approach: [parse, don't validate](https://lexi-lambda.github.io/blog/2019/11/05/parse-don-t-validate/)
 - Works with plain JavaScript too! You don't need to use TypeScript.
 
-# Sponsorship
+### Sponsors
 
 Sponsorship at any level is appreciated and encouraged. For individual developers, consider the [Cup of Coffee tier](https://github.com/sponsors/colinhacks). If you built a paid product using Zod, consider one of the [podium tiers](https://github.com/sponsors/colinhacks).
 
-### Gold
+#### Gold
 
 <table>
   <tr>
     <td align="center">
       <a href="https://astro.build/">
-        <img src="https://avatars.githubusercontent.com/u/44914786?s=200&v=4" width="200px;" alt="" />
+        <img src="https://avatars.githubusercontent.com/u/44914786?s=200&v=4" width="200px;" alt="Astro" />
       </a>
       <br />
       <b>Astro</b>
@@ -173,7 +183,7 @@ Sponsorship at any level is appreciated and encouraged. For individual developer
   </tr>
 </table>
 
-### Silver
+#### Silver
 
 <table>
   <tr>
@@ -205,7 +215,7 @@ Sponsorship at any level is appreciated and encouraged. For individual developer
   </tr>
 </table>
 
-### Bronze
+#### Bronze
 
 <table>
   <tr>
@@ -242,34 +252,7 @@ Sponsorship at any level is appreciated and encouraged. For individual developer
   </tr>
 </table>
 
-# Installation
-
-To install Zod v3:
-
-```sh
-npm install zod
-```
-
-⚠️ IMPORTANT: You must enable `strict` mode in your `tsconfig.json`. This is a best practice for all TypeScript projects.
-
-```ts
-// tsconfig.json
-{
-  // ...
-  "compilerOptions": {
-    // ...
-    "strict": true
-  }
-}
-```
-
-#### TypeScript requirements
-
-- Zod 3.x requires TypeScript 4.1+
-- Zod 2.x requires TypeScript 3.7+
-- Zod 1.x requires TypeScript 3.3+
-
-# Ecosystem
+### Ecosystem
 
 There are a growing number of tools that are built atop or support Zod natively! If you've built a tool or library on top of Zod, tell me about it [on Twitter](https://twitter.com/colinhacks) or [start a Discussion](https://github.com/colinhacks/zod/discussions). I'll add it below and tweet it out.
 
@@ -284,8 +267,8 @@ There are a growing number of tools that are built atop or support Zod natively!
 - [`zod-endpoints`](https://github.com/flock-community/zod-endpoints): Contract-first strictly typed endpoints with Zod. OpenAPI compatible.
 - [`express-zod-api`](https://github.com/RobinTail/express-zod-api): Build Express-based APIs with I/O schema validation and custom middlewares.
 - [`zod-to-json-schema`](https://github.com/StefanTerdell/zod-to-json-schema): Convert your Zod schemas into [JSON Schemas](https://json-schema.org/).
-- [`json-schema-to-zod`](https://github.com/StefanTerdell/json-schema-to-zod): Convert your [JSON Schemas](https://json-schema.org/) into Zod schemas. Use it live [here](https://StefanTerdell.github.io/json-schema-to-zod-react/).
-- [`json-to-zod`](https://github.com/rsinohara/json-to-zod): Convert JSON objects into Zod schemas. Use it live [here](https://rsinohara.github.io/json-to-zod-react/).
+- [`json-schema-to-zod`](https://github.com/StefanTerdell/json-schema-to-zod): Convert your [JSON Schemas](https://json-schema.org/) into Zod schemas. [Live demo](https://StefanTerdell.github.io/json-schema-to-zod-react/).
+- [`json-to-zod`](https://github.com/rsinohara/json-to-zod): Convert JSON objects into Zod schemas. [Live demo](https://rsinohara.github.io/json-to-zod-react/).
 - [`zod-dto`](https://github.com/kbkk/abitia/tree/master/packages/zod-dto): Generate Nest.js DTOs from a Zod schema.
 - [`soly`](https://github.com/mdbetancourt/soly): Create CLI applications with zod.
 - [`graphql-codegen-typescript-validation-schema`](https://github.com/Code-Hex/graphql-codegen-typescript-validation-schema): GraphQL Code Generator plugin to generate form validation schema from your GraphQL schema
@@ -297,13 +280,40 @@ There are a growing number of tools that are built atop or support Zod natively!
 - [`prisma-trpc-generator`](https://github.com/omar-dulaimi/prisma-trpc-generator): Emit fully implemented tRPC routers and their validation schemas using Zod.
 - [`nestjs-graphql-zod`](https://github.com/incetarik/nestjs-graphql-zod): Generates NestJS GraphQL model classes from Zod schemas dynamically and provides GraphQL method decorators working with Zod schemas.
 
-### Form integrations
+#### Form integrations
 
 - [`react-hook-form`](https://github.com/react-hook-form/resolvers#zod): A first-party Zod resolver for React Hook Form
 - [`zod-formik-adapter`](https://github.com/robertLichtnow/zod-formik-adapter): A community-maintained Formik adapter for Zod
 - [`react-zorm`](https://github.com/esamattis/react-zorm): Standalone `<form>` generation and validation for React using Zod
 
-# Basic usage
+## Installation
+
+To install Zod v3:
+
+```sh
+npm install zod
+```
+
+⚠️ IMPORTANT: You must enable `strict` mode in your `tsconfig.json`. This is a best practice for all TypeScript projects.
+
+```ts
+// tsconfig.json
+{
+  // ...
+  "compilerOptions": {
+    // ...
+    "strict": true
+  }
+}
+```
+
+> **TypeScript requirements**
+>
+> - Zod 3.x requires TypeScript 4.1+
+> - Zod 2.x requires TypeScript 3.7+
+> - Zod 1.x requires TypeScript 3.3+
+
+## Basic usage
 
 Creating a simple string schema
 
@@ -338,8 +348,6 @@ type User = z.infer<typeof User>;
 // { username: string }
 ```
 
-# Defining schemas
-
 ## Primitives
 
 ```ts
@@ -403,9 +411,7 @@ z.string().nonempty({ message: "Can't be empty" });
 
 > Check out [validator.js](https://github.com/validatorjs/validator.js) for a bunch of other useful string validation functions.
 
-#### Custom error messages
-
-You can customize certain errors when creating a string schema.
+You can customize some common errors messages when creating a string schema.
 
 ```ts
 const name = z.string({
@@ -551,7 +557,7 @@ FishEnum.options; // ["Salmon", "Tuna", "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()` .
+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()`.
 
 **Numeric enums**
 
@@ -619,7 +625,7 @@ FruitEnum.enum.Apple; // "apple"
 
 ## Optionals
 
-You can make any schema optional with `z.optional()`:
+You can make any schema optional with `z.optional()`. This wraps the schema in a `ZodOptional` instance and returns the result.
 
 ```ts
 const schema = z.optional(z.string());
@@ -628,7 +634,7 @@ schema.parse(undefined); // => returns undefined
 type A = z.infer<typeof schema>; // string | undefined
 ```
 
-You can make an existing schema optional with the `.optional()` method:
+For convenience, you can also call the `.optional()` method on an existing schema.
 
 ```ts
 const user = z.object({
@@ -637,7 +643,7 @@ const user = z.object({
 type C = z.infer<typeof user>; // { username?: string | undefined };
 ```
 
-#### `.unwrap`
+You can extract the wrapped schema from a `ZodOptional` instance with `.unwrap()`.
 
 ```ts
 const stringSchema = z.string();
@@ -647,7 +653,7 @@ optionalString.unwrap() === stringSchema; // true
 
 ## Nullables
 
-Similarly, you can create nullable types like so:
+Similarly, you can create nullable types with `z.nullable()`.
 
 ```ts
 const nullableString = z.nullable(z.string());
@@ -655,14 +661,14 @@ nullableString.parse("asdf"); // => "asdf"
 nullableString.parse(null); // => null
 ```
 
-You can make an existing schema nullable with the `nullable` method:
+Or use the `.nullable()` method.
 
 ```ts
 const E = z.string().nullable(); // equivalent to D
 type E = z.infer<typeof E>; // string | null
 ```
 
-#### `.unwrap`
+Extract the inner schema with `.unwrap()`.
 
 ```ts
 const stringSchema = z.string();
@@ -818,7 +824,7 @@ const deepPartialUser = user.deepPartial();
 
 > Important limitation: deep partials only work as expected in hierarchies of objects, arrays, and tuples.
 
-#### Unrecognized keys
+### `.passthrough`
 
 By default Zod objects schemas strip out unrecognized keys during parsing.
 
@@ -835,8 +841,6 @@ person.parse({
 // extraKey has been stripped
 ```
 
-### `.passthrough`
-
 Instead, if you want to pass through unknown keys, use `.passthrough()` .
 
 ```ts
@@ -849,7 +853,7 @@ person.passthrough().parse({
 
 ### `.strict`
 
-You can _disallow_ unknown keys with `.strict()` . If there are any unknown keys in the input, Zod will throw an error.
+By default Zod objects schemas strip out unrecognized keys during parsing. You can _disallow_ unknown keys with `.strict()` . If there are any unknown keys in the input, Zod will throw an error.
 
 ```ts
 const person = z
@@ -986,7 +990,7 @@ For convenience, you can also use the `.or` method:
 const stringOrNumber = z.string().or(z.number());
 ```
 
-### Discriminated unions
+## Discriminated unions
 
 If the union consists of object schemas all identifiable by a common property, it is possible to use
 the `z.discriminatedUnion` method.
@@ -1032,7 +1036,7 @@ userStore["77d2586b-9e8e-4ecf-8b21-ea7e0530eadd"] = {
 }; // TypeError
 ```
 
-#### A note on numerical keys
+**A note on numerical keys**
 
 You may have expected `z.record()` to accept two arguments, one for the keys and one for the values. After all, TypeScript's built-in Record type does: `Record<KeyType, ValueType>` . Otherwise, how do you represent the TypeScript type `Record<number, any>` in Zod?
 
@@ -1049,9 +1053,7 @@ for (const key in testMap) {
 // prints: `1: string`
 ```
 
-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.
+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
 
@@ -1070,7 +1072,7 @@ type NumberSet = z.infer<typeof numberSet>;
 // type NumberSet = Set<number>
 ```
 
-### `.nonempty/.min/.max/.size`
+Set schemas can be further contrainted with the following utility methods.
 
 ```ts
 z.set(z.string()).nonempty(); // must contain at least one item
@@ -1081,8 +1083,6 @@ z.set(z.string()).size(5); // must contain 5 items exactly
 
 ## Intersections
 
-<!-- > ⚠️ Intersections are deprecated. If you are trying to merge objects, use the `.merge` method instead. -->
-
 Intersections are useful for creating "logical AND" types. This is useful for intersecting two object types.
 
 ```ts
@@ -1184,7 +1184,7 @@ const Category: z.ZodType<Category> = BaseCategory.merge(
 );
 ``` -->
 
-#### JSON type
+### JSON type
 
 If you want to validate any JSON value, you can use the snippet below.
 
@@ -1201,7 +1201,7 @@ jsonSchema.parse(data);
 
 Thanks to [ggoodman](https://github.com/ggoodman) for suggesting this.
 
-#### Cyclical objects
+### Cyclical objects
 
 Despite supporting recursive schemas, passing cyclical data into Zod will cause an infinite loop.
 
@@ -1265,7 +1265,7 @@ type myFunction = z.infer<typeof myFunction>;
 // => ()=>unknown
 ```
 
-**Define inputs and output**
+Define inputs and outputs.
 
 ```ts
 const myFunction = z
@@ -1276,24 +1276,6 @@ type myFunction = z.infer<typeof myFunction>;
 // => (arg0: string, arg1: number)=>boolean
 ```
 
-**Extract the input and output schemas**
-You can extract the parameters and return type of a function schema.
-
-```ts
-myFunction.parameters();
-// => ZodTuple<[ZodString, ZodNumber]>
-
-myFunction.returnType();
-// => ZodBoolean
-```
-
-<!-- `z.function()` accepts two arguments:
-
-* `args: ZodTuple` The first argument is a tuple (created with `z.tuple([...])` and defines the schema of the arguments to your function. If the function doesn't accept arguments, you can pass an empty tuple (`z.tuple([])`).
-* `returnType: any Zod schema` The second argument is the function's return type. This can be any Zod schema. -->
-
-> You can use the special `z.void()` option if your function doesn't return anything. This will let Zod properly infer the type of void-returning functions. (Void-returning functions actually return undefined.)
-
 <!--
 
 ``` ts
@@ -1322,7 +1304,9 @@ trimmedLength("sandwich"); // => 8
 trimmedLength(" asdf "); // => 4
 ```
 
-If you only care about validating inputs, that's fine:
+If you only care about validating inputs, just don't call the `.returns()` method. The output type will be inferred from the implementation.
+
+> You can use the special `z.void()` option if your function doesn't return anything. This will let Zod properly infer the type of void-returning functions. (Void-returning functions actually return undefined.)
 
 ```ts
 const myFunction = z
@@ -1334,6 +1318,21 @@ const myFunction = z
 myFunction; // (arg: string)=>number[]
 ```
 
+Extract the input and output schemas from a function schema.
+
+```ts
+myFunction.parameters();
+// => ZodTuple<[ZodString, ZodNumber]>
+
+myFunction.returnType();
+// => ZodBoolean
+```
+
+<!-- `z.function()` accepts two arguments:
+
+* `args: ZodTuple` The first argument is a tuple (created with `z.tuple([...])` and defines the schema of the arguments to your function. If the function doesn't accept arguments, you can pass an empty tuple (`z.tuple([])`).
+* `returnType: any Zod schema` The second argument is the function's return type. This can be any Zod schema. -->
+
 ## Preprocess
 
 Typically Zod operates under a "parse then transform" paradigm. Zod validates the input first, then passes it through a chain of transformation functions. (For more information about transforms, read the [.transform docs](#transform).)
@@ -1346,7 +1345,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.
 
-# ZodType: methods and properties
+## Schema methods
 
 All Zod schemas contain certain methods.
 
@@ -1371,8 +1370,11 @@ stringSchema.parse(12); // throws Error('Non-string type: number');
 If you use asynchronous [refinements](#refine) or [transforms](#transform) (more on those later), you'll need to use `.parseAsync`
 
 ```ts
-const stringSchema = z.string().refine(async (val) => val.length > 20);
-const value = await stringSchema.parseAsync("hello"); // => hello
+const stringSchema1 = z.string().refine(async (val) => val.length < 20);
+const value1 = await stringSchema.parseAsync("hello"); // => hello
+
+const stringSchema2 = z.string().refine(async (val) => val.length > 20);
+const value2 = await stringSchema.parseAsync("hello"); // => throws
 ```
 
 ### `.safeParse`
@@ -1607,27 +1609,6 @@ stringToNumber.parse("string"); // => 6
 
 > ⚠️ Transform functions must not throw. Make sure to use refinements before the transform or addIssue within the transform to make sure the input can be parsed by the transform.
 
-#### Validating during transform
-
-Similar to `superRefine`, `transform` can optionally take a `ctx`. This allows you to simultaneously
-validate and transform the value, which can be simpler than chaining `refine` and `validate`. 
-When calling `ctx.addIssue` make sure to still return a value of the correct type otherwise the inferred type will include `undefined`.
-
-```ts
-const Strings = z
-  .string()
-  .transform((val, ctx) => {
-    const parsed = parseInt(val);
-    if (isNaN(parsed)) {
-      ctx.addIssue({
-        code: z.ZodIssueCode.custom,
-        message: "Not a number",
-      });
-    }
-    return parsed;
-  });
-```
-
 #### Chaining order
 
 Note that `stringToNumber` above is an instance of the `ZodEffects` subclass. It is NOT an instance of `ZodString`. If you want to use the built-in methods of `ZodString` (e.g. `.email()`) you must apply those methods _before_ any transforms.
@@ -1641,14 +1622,33 @@ const emailToDomain = z
 emailToDomain.parse("colinhacks@example.com"); // => example.com
 ```
 
+#### Validating during transform
+
+Similar to `superRefine`, `transform` can optionally take a `ctx`. This allows you to simultaneously validate and transform the value, which can be simpler than chaining `refine` and `validate`. When calling `ctx.addIssue` make sure to still return a value of the correct type otherwise the inferred type will include `undefined`.
+
+```ts
+const Strings = z.string().transform((val, ctx) => {
+  const parsed = parseInt(val);
+  if (isNaN(parsed)) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: "Not a number",
+    });
+  }
+  return parsed;
+});
+```
+
 #### Relationship to refinements
 
-Transforms and refinements can be interleaved:
+Transforms and refinements can be interleaved. These will be executed in the order they are declared.
 
 ```ts
 z.string()
-  .transform((val) => val.length)
-  .refine((val) => val > 25);
+  .transform((val) => val.toUpperCase())
+  .refine((val) => val.length > 15)
+  .transform((val) => `Hello ${val}`)
+  .refine((val) => val.indexOf("!") === -1);
 ```
 
 #### Async transforms
@@ -1710,7 +1710,7 @@ z.nullable(z.string());
 
 ### `.nullish`
 
-A convenience method that returns a "nullish" version of a schema. Nullish schemas will accept both `undefined` and `null`. Read more about the concept of "nullish" [here](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#nullish-coalescing).
+A convenience method that returns a "nullish" version of a schema. Nullish schemas will accept both `undefined` and `null`. Read more about the concept of "nullish" [in the TypeScript 3.7 release notes](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#nullish-coalescing).
 
 ```ts
 const nullishString = z.string().nullish(); // string | null | undefined
@@ -1763,9 +1763,9 @@ z.object({ name: z.string() }).and(z.object({ age: z.number() })); // { name: st
 z.intersection(z.object({ name: z.string() }), z.object({ age: z.number() }));
 ```
 
-# Guides and concepts
+## Guides and concepts
 
-## Type inference
+### Type inference
 
 You can extract the TypeScript type of any schema with `z.infer<typeof mySchema>` .
 
@@ -1777,7 +1777,7 @@ const u: A = 12; // TypeError
 const u: A = "asdf"; // compiles
 ```
 
-#### What about transforms?
+**What about transforms?**
 
 In reality each Zod schema internally tracks **two** types: an input and an output. For most schemas (e.g. `z.string()`) these two are the same. But once you add transforms into the mix, these two values can diverge. For instance `z.string().transform(val => val.length)` has an input of `string` and an output of `number`.
 
@@ -1794,7 +1794,7 @@ type output = z.output<typeof stringToNumber>; // number
 type inferred = z.infer<typeof stringToNumber>; // number
 ```
 
-## Writing generic functions
+### Writing generic functions
 
 When attempting to write a functions that accepts a Zod schemas as an input, it's common to try something like this:
 
@@ -1828,13 +1828,13 @@ const arg = makeSchemaOptional(z.string());
 arg.unwrap(); // ZodString
 ```
 
-### Restricting valid schemas
+#### Constraining allowable inputs
 
 The `ZodType` class has three generic parameters.
 
 ```ts
 class ZodType<
-  Output,
+  Output = any,
   Def extends ZodTypeDef = ZodTypeDef,
   Input = Output
 > { ... }
@@ -1854,12 +1854,16 @@ makeSchemaOptional(z.number());
 // Error: 'ZodNumber' is not assignable to parameter of type 'ZodType<string, ZodTypeDef, string>'
 ```
 
-## Error handling
+### Error handling
 
 Zod provides a subclass of Error called `ZodError`. ZodErrors contain an `issues` array containing detailed information about the validation problems.
 
 ```ts
-const data = z.object({ name: z.string() }).safeParse({ name: 12 });
+const data = z
+  .object({
+    name: z.string(),
+  })
+  .safeParse({ name: 12 });
 
 if (!data.success) {
   data.error.issues;
@@ -1875,20 +1879,31 @@ if (!data.success) {
 }
 ```
 
-#### Error formatting
+> For detailed information about the possible error codes and how to customize error messages, check out the dedicated error handling guide: [ERROR_HANDLING.md](ERROR_HANDLING.md)
+
+### Error formatting
 
 You can use the `.format()` method to convert this error into a nested object.
 
 ```ts
-data.error.format();
-/* {
-  name: { _errors: [ 'Expected string, received number' ] }
-} */
-```
+const data = z
+  .object({
+    name: z.string(),
+  })
+  .safeParse({ name: 12 });
 
-For detailed information about the possible error codes and how to customize error messages, check out the dedicated error handling guide: [ERROR_HANDLING.md](ERROR_HANDLING.md)
+if (!data.success) {
+  const formatted = data.error.format();
+  /* {
+    name: { _errors: [ 'Expected string, received number' ] }
+  } */
 
-# Comparison
+  formatted.name?._errors;
+  // => ["Expected string, received number"]
+}
+```
+
+## 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.
 
@@ -1940,20 +1955,18 @@ Branded -->
 * Missing support for parsing cyclical data (maybe)
 * Missing error customization -->
 
-#### Joi
+**Joi**
 
 [https://github.com/hapijs/joi](https://github.com/hapijs/joi)
 
 Doesn't support static type inference 😕
 
-#### Yup
+**Yup**
 
 [https://github.com/jquense/yup](https://github.com/jquense/yup)
 
 Yup is a full-featured library that was implemented first in vanilla JS, and later rewritten in TypeScript.
 
-Differences
-
 - Supports casting and transforms
 - All object fields are optional by default
 - Missing object methods: (partial, deepPartial)
@@ -1964,7 +1977,7 @@ Differences
 
 <!-- ¹Yup has a strange interpretation of the word `required`. Instead of meaning "not undefined", Yup uses it to mean "not empty". So `yup.string().required()` will not accept an empty string, and `yup.array(yup.string()).required()` will not accept an empty array. Instead, Yup us Zod arrays there is a dedicated `.nonempty()` method to indicate this, or you can implement it with a custom refinement. -->
 
-#### io-ts
+**io-ts**
 
 [https://github.com/gcanti/io-ts](https://github.com/gcanti/io-ts)
 
@@ -2015,7 +2028,7 @@ This more declarative API makes schema definitions vastly more concise.
 - Missing promise schemas
 - Missing function schemas
 
-#### Runtypes
+**Runtypes**
 
 [https://github.com/pelotom/runtypes](https://github.com/pelotom/runtypes)
 
@@ -2028,7 +2041,7 @@ Good type inference support, but limited options for object type masking (no `.p
 - Missing promise schemas
 - Missing error customization
 
-#### Ow
+**Ow**
 
 [https://github.com/sindresorhus/ow](https://github.com/sindresorhus/ow)
 
@@ -2036,6 +2049,6 @@ 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
+## Changelog
 
 View the changelog at [CHANGELOG.md](CHANGELOG.md)

package/lib/index.mjs

@@ -709,8 +709,8 @@ class ZodString extends ZodType {
             ...errorUtil.errToObj(message),
         });
         /**
-         * Deprecated.
-         * Use z.string().min(1) instead.
+         * @deprecated Use z.string().min(1) instead.
+         * @see {@link ZodString.min}
          */
         this.nonempty = (message) => this.min(1, errorUtil.errToObj(message));
     }
@@ -2721,9 +2721,15 @@ ZodNaN.create = (params) => {
         ...processCreateParams(params),
     });
 };
-const custom = (check, params) => {
+const custom = (check, params = {}, fatal) => {
     if (check)
-        return ZodAny.create().refine(check, params);
+        return ZodAny.create().superRefine((data, ctx) => {
+            if (!check(data)) {
+                const p = typeof params === "function" ? params(data) : params;
+                const p2 = typeof p === "string" ? { message: p } : p;
+                ctx.addIssue({ code: "custom", ...p2, fatal });
+            }
+        });
     return ZodAny.create();
 };
 const late = {
@@ -2765,7 +2771,7 @@ var ZodFirstPartyTypeKind;
 })(ZodFirstPartyTypeKind || (ZodFirstPartyTypeKind = {}));
 const instanceOfType = (cls, params = {
     message: `Input not instance of ${cls.name}`,
-}) => custom((data) => data instanceof cls, params);
+}) => custom((data) => data instanceof cls, params, true);
 const stringType = ZodString.create;
 const numberType = ZodNumber.create;
 const nanType = ZodNaN.create;

package/lib/index.umd.js

@@ -715,8 +715,8 @@
                 ...errorUtil.errToObj(message),
             });
             /**
-             * Deprecated.
-             * Use z.string().min(1) instead.
+             * @deprecated Use z.string().min(1) instead.
+             * @see {@link ZodString.min}
              */
             this.nonempty = (message) => this.min(1, errorUtil.errToObj(message));
         }
@@ -2727,9 +2727,15 @@
             ...processCreateParams(params),
         });
     };
-    const custom = (check, params) => {
+    const custom = (check, params = {}, fatal) => {
         if (check)
-            return ZodAny.create().refine(check, params);
+            return ZodAny.create().superRefine((data, ctx) => {
+                if (!check(data)) {
+                    const p = typeof params === "function" ? params(data) : params;
+                    const p2 = typeof p === "string" ? { message: p } : p;
+                    ctx.addIssue({ code: "custom", ...p2, fatal });
+                }
+            });
         return ZodAny.create();
     };
     const late = {
@@ -2771,7 +2777,7 @@
     })(exports.ZodFirstPartyTypeKind || (exports.ZodFirstPartyTypeKind = {}));
     const instanceOfType = (cls, params = {
         message: `Input not instance of ${cls.name}`,
-    }) => custom((data) => data instanceof cls, params);
+    }) => custom((data) => data instanceof cls, params, true);
     const stringType = ZodString.create;
     const numberType = ZodNumber.create;
     const nanType = ZodNaN.create;

package/lib/types.d.ts

@@ -120,8 +120,8 @@ export declare class ZodString extends ZodType<string, ZodStringDef> {
     max(maxLength: number, message?: errorUtil.ErrMessage): ZodString;
     length(len: number, message?: errorUtil.ErrMessage): ZodString;
     /**
-     * Deprecated.
-     * Use z.string().min(1) instead.
+     * @deprecated Use z.string().min(1) instead.
+     * @see {@link ZodString.min}
      */
     nonempty: (message?: errorUtil.ErrMessage | undefined) => ZodString;
     get isEmail(): boolean;
@@ -625,7 +625,7 @@ export declare class ZodNaN extends ZodType<number, ZodNaNDef> {
     _parse(input: ParseInput): ParseReturnType<any>;
     static create: (params?: RawCreateParams) => ZodNaN;
 }
-export declare const custom: <T>(check?: ((data: unknown) => any) | undefined, params?: Parameters<ZodTypeAny["refine"]>[1]) => ZodType<T, ZodTypeDef, T>;
+export declare const custom: <T>(check?: ((data: unknown) => any) | undefined, params?: Parameters<ZodTypeAny["refine"]>[1], fatal?: boolean | undefined) => ZodType<T, ZodTypeDef, T>;
 export { ZodType as Schema, ZodType as ZodSchema };
 export declare const late: {
     object: <T extends ZodRawShape>(shape: () => T, params?: RawCreateParams) => ZodObject<T, "strip", ZodTypeAny, { [k_1 in keyof objectUtil.addQuestionMarks<{ [k in keyof T]: T[k]["_output"]; }>]: objectUtil.addQuestionMarks<{ [k in keyof T]: T[k]["_output"]; }>[k_1]; }, { [k_3 in keyof objectUtil.addQuestionMarks<{ [k_2 in keyof T]: T[k_2]["_input"]; }>]: objectUtil.addQuestionMarks<{ [k_2 in keyof T]: T[k_2]["_input"]; }>[k_3]; }>;

package/lib/types.js

@@ -291,8 +291,8 @@ class ZodString extends ZodType {
             ...errorUtil_1.errorUtil.errToObj(message),
         });
         /**
-         * Deprecated.
-         * Use z.string().min(1) instead.
+         * @deprecated Use z.string().min(1) instead.
+         * @see {@link ZodString.min}
          */
         this.nonempty = (message) => this.min(1, errorUtil_1.errorUtil.errToObj(message));
     }
@@ -2336,9 +2336,15 @@ ZodNaN.create = (params) => {
         ...processCreateParams(params),
     });
 };
-const custom = (check, params) => {
+const custom = (check, params = {}, fatal) => {
     if (check)
-        return ZodAny.create().refine(check, params);
+        return ZodAny.create().superRefine((data, ctx) => {
+            if (!check(data)) {
+                const p = typeof params === "function" ? params(data) : params;
+                const p2 = typeof p === "string" ? { message: p } : p;
+                ctx.addIssue({ code: "custom", ...p2, fatal });
+            }
+        });
     return ZodAny.create();
 };
 exports.custom = custom;
@@ -2381,7 +2387,7 @@ var ZodFirstPartyTypeKind;
 })(ZodFirstPartyTypeKind = exports.ZodFirstPartyTypeKind || (exports.ZodFirstPartyTypeKind = {}));
 const instanceOfType = (cls, params = {
     message: `Input not instance of ${cls.name}`,
-}) => (0, exports.custom)((data) => data instanceof cls, params);
+}) => (0, exports.custom)((data) => data instanceof cls, params, true);
 exports.instanceof = instanceOfType;
 const stringType = ZodString.create;
 exports.string = stringType;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zod",
-  "version": "3.16.0",
+  "version": "3.16.1",
   "description": "TypeScript-first schema declaration and validation library with static type inference",
   "main": "./lib/index.js",
   "types": "./index.d.ts",