zod 3.24.1 → 3.24.3

package/README.md

@@ -1,13 +1,12 @@
 <p align="center">
-  <img src="logo.svg" width="200px" align="center" alt="Zod logo" />
+  <img src="https://raw.githubusercontent.com/colinhacks/zod/main/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/>
+  <a href="https://zod.dev">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%3Amain"><img src="https://github.com/colinhacks/zod/actions/workflows/test.yml/badge.svg?event=push&branch=main" 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>
@@ -17,34 +16,47 @@
 </p>
 
 <div align="center">
-  <a href="https://zod.dev">Documentation</a>
+  <a href="https://zod.dev">Website</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>
-  <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
-  <a href="https://deno.land/x/zod">deno</a>
+  <a href="https://twitter.com/colinhacks">𝕏</a>
   <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
-  <a href="https://github.com/colinhacks/zod/issues/new">Issues</a>
-  <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
-  <a href="https://twitter.com/colinhacks">@colinhacks</a>
-  <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
-  <a href="https://trpc.io">tRPC</a>
+  <a href="https://bsky.app/profile/zod.dev">Bluesky</a>
   <br />
 </div>
 
+<br/><br/>
+
+<table align="center" style="justify-content:center;align-items:center;display:flex;"><td>
+  <p align="center">Zod 4 is now in beta!
+  <br/>
+  <a target="_blank" rel="noopener noreferrer" href="https://v4.zod.dev/v4">Read the announcement 👉</a></p></td>
+</table>
+
 <br/>
 <br/>
 
-<!-- <p><strong>Announcement ✨</strong> Zod has recieved the <a href="https://go.clerk.com/zod-clerk">Clerk</a> OSS Fellowship!<br/>Read the announcement post 👉 <a href="https://go.clerk.com/zod-clerk">clerk.com/blog/zod-fellowship</a></p> -->
+<h2 align="center">Featured sponsor: Fern</h2>
 
-[![clerk announcement](https://github.com/colinhacks/zod/assets/3084745/6327cf99-8d82-4b44-a5b1-ba2b5c2ff6ad)](https://go.clerk.com/hqN4rp7)
+<div align="center">
+  <a href="https://link.buildwithfern.com/zod-partnership">
+    <picture width="95%" >
+      <source media="(prefers-color-scheme: dark)" srcset="https://i.imgur.com/ntvK08h.png">
+      <img alt="fern logo" src="https://i.imgur.com/pqyEkg5.png" width="95%">
+    </picture>
+  </a>
+  <br/>
+  <p><sub>Learn more about <a target="_blank" rel="noopener noreferrer" href="mailto:sponsorship@colinhacks.com">featured sponsorships</a></sub></p>
+</div>
 
+<!-- <hr/> -->
 <br/>
-
+<br/>
+ 
 ## Table of contents
 
-> These docs have been translated into [Chinese](./README_ZH.md).
+> These docs have been translated into [Chinese](./README_ZH.md) and [Korean](./README_KO.md).
 
 - [Table of contents](#table-of-contents)
 - [Introduction](#introduction)
@@ -165,6 +177,8 @@
   - [Ow](#ow)
 - [Changelog](#changelog)
 
+<br/>
+
 ## 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.
@@ -181,38 +195,59 @@ 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.
 
+<br/>
+
 ## 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).
 
 <br/>
-<h3 align="center">Diamond</h3>
 
-<br/>
+<h3 align="center">Platinum</h3>
 
-<div align="center">
-  <a href="https://go.clerk.com/PKHrcwh">
-    <picture width="100%">
-      <source media="(prefers-color-scheme: dark)" srcset="https://github.com/colinhacks/zod/assets/3084745/15c8c8be-189d-44ed-b3db-59bf2a21cbe3">
-      <img alt="clerk logo" src="https://github.com/colinhacks/zod/assets/3084745/15c8c8be-189d-44ed-b3db-59bf2a21cbe3">
-    </picture>
-  </a>
-  <br/>
-  <br/>
-  <p>
-    The most comprehensive User Management Platform
-    <br/>
-    <a style="text-decoration:none;" href="https://go.clerk.com/PKHrcwh" target="_blank">clerk.com</a>
-  </p>
-</div>
+<table align="center" style="justify-content: center;align-items: center;display: flex;">
+  <tr>
+    <td align="center">
+      <p></p>
+      <p>
+      <a href="https://www.coderabbit.ai/">
+        <picture height="80px">
+          <source media="(prefers-color-scheme: dark)" srcset="https://github.com/user-attachments/assets/eea24edb-ff20-4532-b57c-e8719f455d6d">
+          <img alt="CodeRabbit logo" height="80px" src="https://github.com/user-attachments/assets/d791bc7d-dc60-4d55-9c31-97779839cb74">
+        </picture>
+      </a>
+      <br  />   
+      Cut code review time & bugs in half
+      <br/>
+      <a href="https://www.coderabbit.ai/" style="text-decoration:none;">coderabbit.ai</a>
+      </p>
+      <p></p>
+    </td>
+  </tr>
+</table>
 
-<br/>
 <br/>
 
-<h3 align="center">Platinum</h3>
+<h3 align="center">Gold</h3>
 
 <table align="center" style="justify-content: center;align-items: center;display: flex;">
   <tr>
+    <td align="center">
+      <p></p>
+      <p>
+      <a href="https://www.courier.com/?utm_source=zod&utm_campaign=osssponsors">
+        <picture height="62px">
+          <source media="(prefers-color-scheme: dark)" srcset="https://github.com/user-attachments/assets/6b09506a-78de-47e8-a8c1-792efe31910a">
+          <img alt="Courier logo" height="62px" src="https://github.com/user-attachments/assets/6b09506a-78de-47e8-a8c1-792efe31910a">
+        </picture>
+      </a>
+      <br  />   
+      The API platform for sending notifications
+      <br/>
+      <a href="https://www.courier.com/?utm_source=zod&utm_campaign=osssponsors" style="text-decoration:none;">courier.com</a>
+      </p>
+      <p></p>
+    </td>
     <td align="center">
       <p></p>
       <p>
@@ -247,15 +282,13 @@ Sponsorship at any level is appreciated and encouraged. If you built a paid prod
       </p>
       <p></p>
     </td>
-  </tr>
-  <tr>
     <td align="center">
       <p></p>
       <p>
       <a href="https://retool.com/?utm_source=github&utm_medium=referral&utm_campaign=zod">
         <picture height="45px">
           <source media="(prefers-color-scheme: dark)" srcset="https://github.com/colinhacks/zod/assets/3084745/ac65013f-aeb4-48dd-a2ee-41040b69cbe6">
-          <img alt="stainless" height="45px" src="https://github.com/colinhacks/zod/assets/3084745/5ef4c11b-efeb-4495-90a8-41b83f798600">
+          <img alt="Retool" height="45px" src="https://github.com/colinhacks/zod/assets/3084745/5ef4c11b-efeb-4495-90a8-41b83f798600">
         </picture>
       </a>
       <br  />   
@@ -270,7 +303,7 @@ Sponsorship at any level is appreciated and encouraged. If you built a paid prod
     <td align="center">
       <p></p>
       <p>
-      <a href="https://stainlessapi.com">
+      <a href="https://stainless.com">
         <picture height="45px">
           <source media="(prefers-color-scheme: dark)" srcset="https://github.com/colinhacks/zod/assets/3084745/f20759c1-3e51-49d0-a31e-bbc43abec665">
           <img alt="stainless" height="45px" src="https://github.com/colinhacks/zod/assets/3084745/e9444e44-d991-4bba-a697-dbcfad608e47">
@@ -279,12 +312,10 @@ Sponsorship at any level is appreciated and encouraged. If you built a paid prod
       <br  />   
       Generate best-in-class SDKs
       <br/>
-      <a href="https://stainlessapi.com" style="text-decoration:none;">stainlessapi.com</a>
+      <a href="https://stainless.com" style="text-decoration:none;">stainless.com</a>
       </p>
       <p></p>
     </td>
-  </tr>
-  <tr>
     <td align="center">
       <p></p>
       <p>
@@ -306,10 +337,15 @@ Sponsorship at any level is appreciated and encouraged. If you built a paid prod
 
 <br/>
 
-<h3 align="center">Gold</h3>
+<h3 align="center">Silver</h3>
 
 <table align="center" style="justify-content: center;align-items: center;display: flex;">
   <tr>
+    <td align="center">
+      <img src="https://avatars.githubusercontent.com/u/72055470?s=200&v=4" height="50px;" alt="Nitric" />
+      <br />
+      <a style="text-decoration:none;" href="https://nitric.io/" target="_blank">Nitric</a>
+    </td>
     <td align="center">
       <img src="https://avatars.githubusercontent.com/u/89474619?s=200&v=4" height="50px;" alt="PropelAuth" />
       <br />
@@ -325,12 +361,12 @@ Sponsorship at any level is appreciated and encouraged. If you built a paid prod
       <br />
       <a style="text-decoration:none;" href="https://scalar.com/" target="_blank">Scalar</a>
     </td>
+    </tr><tr>
     <td align="center">
       <img src="https://avatars.githubusercontent.com/u/95297378?s=200&v=4" height="50px;" alt="Trigger.dev logo" />
       <br />
       <a style="text-decoration:none;" href="https://trigger.dev" target="_blank">Trigger.dev</a>
     </td>
-    </tr><tr>
     <td align="center">
       <img src="https://avatars.githubusercontent.com/u/125754?s=200&v=4" height="50px;" alt="Transloadit logo" />
       <br />
@@ -347,12 +383,12 @@ Sponsorship at any level is appreciated and encouraged. If you built a paid prod
       <br />
       <a style="text-decoration:none;" href="https://whop.com/" target="_blank">Whop</a>
     </td>
+    </tr><tr>
     <td align="center">
       <img src="https://avatars.githubusercontent.com/u/36402888?s=200&v=4" height="50px;" alt="CryptoJobsList logo" />
       <br />
       <a style="text-decoration:none;" href="https://cryptojobslist.com/" target="_blank">CryptoJobsList</a>
     </td>
-    </tr><tr>
     <td align="center">
       <img src="https://avatars.githubusercontent.com/u/70170949?s=200&v=4" height="50px;" alt="Plain logo" />
       <br />
@@ -368,6 +404,7 @@ Sponsorship at any level is appreciated and encouraged. If you built a paid prod
       <br />
       <a style="text-decoration:none;" href="https://storyblok.com/" target="_blank">Storyblok</a>
     </td>
+    </tr><tr>
     <td align="center">
       <img src="https://avatars.githubusercontent.com/u/16199997?s=200&v=4" height="50px;" alt="Mux logo" />
       <br />
@@ -378,7 +415,7 @@ Sponsorship at any level is appreciated and encouraged. If you built a paid prod
 
 <br/>
 
-<h3 align="center">Silver</h3>
+<h3 align="center">Bronze</h3>
 
 <table align="center" style="justify-content: center;align-items: center;display: flex;">
   <tr>
@@ -442,7 +479,7 @@ Sponsorship at any level is appreciated and encouraged. If you built a paid prod
   </tr>
 </table>
 
-<h3 align="center">Bronze</h3>
+<!-- <h3 align="center">Bronze</h3>
 
 <table align="center" style="justify-content: center;align-items: center;display: flex;">
   <tr>
@@ -469,7 +506,7 @@ Sponsorship at any level is appreciated and encouraged. If you built a paid prod
     <td>Mohammad-Ali A'râbi</td>
     <td>Supatool</td>
   </tr>
-</table>
+</table> -->
 
 ### Ecosystem
 
@@ -493,10 +530,13 @@ There are a growing number of tools that are built atop or support Zod natively!
 - [`koa-zod-router`](https://github.com/JakeFenley/koa-zod-router): Create typesafe routes in Koa with I/O validation using Zod.
 - [`zod-sockets`](https://github.com/RobinTail/zod-sockets): Zod-powered Socket.IO microframework with I/O validation and built-in AsyncAPI specs
 - [`oas-tszod-gen`](https://github.com/inkognitro/oas-tszod-gen): Client SDK code generator to convert OpenApi v3 specifications into TS endpoint caller functions with Zod types.
+- [`GQLoom`](https://github.com/modevol-com/gqloom): Weave GraphQL schema and resolvers using Zod.
+- [`oRPC`](https://github.com/unnoq/orpc): Typesafe APIs Made Simple
 
 #### Form integrations
 
 - [`react-hook-form`](https://github.com/react-hook-form/resolvers#zod): A first-party Zod resolver for React Hook Form.
+- [`TanStack Form`](https://github.com/TanStack/form): Headless, performant, and type-safe form state management for TS/JS, React, Vue, Angular, Solid, and Lit
 - [`zod-validation-error`](https://github.com/causaly/zod-validation-error): Generate user-friendly error messages from `ZodError`s.
 - [`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.
@@ -520,7 +560,7 @@ There are a growing number of tools that are built atop or support Zod natively!
 - [`zod-to-json-schema`](https://github.com/StefanTerdell/zod-to-json-schema): Convert your Zod schemas into [JSON Schemas](https://json-schema.org/).
 - [`@anatine/zod-openapi`](https://github.com/anatine/zod-plugins/tree/main/packages/zod-openapi): Converts a Zod schema to an OpenAPI v3.x `SchemaObject`.
 - [`zod-fast-check`](https://github.com/DavidTimms/zod-fast-check): Generate `fast-check` arbitraries from Zod schemas.
-- [`zod-dto`](https://github.com/kbkk/abitia/tree/main/packages/zod-dto): Generate Nest.js DTOs from a Zod schema.
+- [`zod-dto`](https://github.com/kbkk/abitia/tree/master/packages/zod-dto): Generate Nest.js DTOs from a Zod schema.
 - [`fastify-type-provider-zod`](https://github.com/turkerdev/fastify-type-provider-zod): Create Fastify type providers from Zod schemas.
 - [`zod-to-openapi`](https://github.com/asteasolutions/zod-to-openapi): Generate full OpenAPI (Swagger) docs from Zod, including schemas, endpoints & parameters.
 - [`nestjs-graphql-zod`](https://github.com/incetarik/nestjs-graphql-zod): Generates NestJS GraphQL model classes from Zod schemas. Provides GraphQL method decorators working with Zod schemas.
@@ -532,7 +572,7 @@ There are a growing number of tools that are built atop or support Zod natively!
 #### X to Zod
 
 - [`ts-to-zod`](https://github.com/fabien0102/ts-to-zod): Convert TypeScript definitions into Zod schemas.
-- [`@runtyping/zod`](https://github.com/johngeorgewright/runtyping/tree/main/packages/zod): Generate Zod from static types & JSON schema.
+- [`@runtyping/zod`](https://github.com/johngeorgewright/runtyping): Generate Zod from static types & JSON schema.
 - [`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/).
 - [`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.
@@ -568,6 +608,9 @@ There are a growing number of tools that are built atop or support Zod natively!
 - [`znv`](https://github.com/lostfictions/znv): Type-safe environment parsing and validation for Node.js with Zod schemas.
 - [`zod-config`](https://github.com/alexmarqs/zod-config): Load configurations across multiple sources with flexible adapters, ensuring type safety with Zod.
 - [`unplugin-environment`](https://github.com/r17x/js/tree/main/packages/unplugin-environment#readme): A plugin for loading enviroment variables safely with schema validation, simple with virtual module, type-safe with intellisense, and better DX 🔥 🚀 👷. Powered by Zod.
+- [`zod-struct`](https://codeberg.org/reesericci/zod-struct): Create runtime-checked structs with Zod.
+- [`zod-csv`](https://github.com/bartoszgolebiowski/zod-csv): Validation helpers for zod for parsing CSV data.
+- [`fullproduct.dev`](https://fullproduct.dev?identity=freelancers&v=z3): Universal Expo + Next.js App Starter that uses Zod schemas as the single source of truth to keep generated MDX docs, GraphQL, database models, forms, and fetcher functions in sync.
 
 #### Utilities for Zod
 
@@ -577,6 +620,8 @@ There are a growing number of tools that are built atop or support Zod natively!
 - [`zod-dev`](https://github.com/schalkventer/zod-dev): Conditionally disables Zod runtime parsing in production.
 - [`zod-accelerator`](https://github.com/duplojs/duplojs-zod-accelerator): Accelerates Zod's throughput up to ~100x.
 
+<br/>
+
 ## Installation
 
 ### Requirements
@@ -617,6 +662,8 @@ pnpm add zod@canary          # pnpm
 
 > The rest of this README assumes you are using npm and importing directly from the `"zod"` package.
 
+<br/>
+
 ## Basic usage
 
 Creating a simple string schema
@@ -652,6 +699,8 @@ type User = z.infer<typeof User>;
 // { username: string }
 ```
 
+<br/>
+
 ## Primitives
 
 ```ts
@@ -680,6 +729,8 @@ z.unknown();
 z.never();
 ```
 
+<br/>
+
 ## Coercion for primitives
 
 Zod now provides a more convenient way to coerce primitive values.
@@ -736,6 +787,8 @@ schema.parse(null); // => false
 
 For more control over coercion logic, consider using [`z.preprocess`](#preprocess) or [`z.pipe()`](#pipe).
 
+<br/>
+
 ## Literals
 
 Literal schemas represent a [literal type](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types), like `"hello world"` or `5`.
@@ -755,6 +808,8 @@ 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.
 
+<br/>
+
 ## Strings
 
 Zod includes a handful of string-specific validations.
@@ -953,6 +1008,8 @@ const ipv6Cidr = z.string().cidr({ version: "v6" });
 ipv6Cidr.parse("192.168.1.1"); // fail
 ```
 
+<br/>
+
 ## Numbers
 
 You can customize certain error messages when creating a number schema.
@@ -991,6 +1048,8 @@ Optionally, you can pass in a second argument to provide a custom error message.
 z.number().lte(5, { message: "this👏is👏too👏big" });
 ```
 
+<br/>
+
 ## BigInts
 
 Zod includes a handful of bigint-specific validations.
@@ -1009,6 +1068,8 @@ z.bigint().nonpositive(); // <= 0n
 z.bigint().multipleOf(5n); // Evenly divisible by 5n.
 ```
 
+<br/>
+
 ## NaNs
 
 You can customize certain error messages when creating a nan schema.
@@ -1020,6 +1081,8 @@ const isNaN = z.nan({
 });
 ```
 
+<br/>
+
 ## Booleans
 
 You can customize certain error messages when creating a boolean schema.
@@ -1031,6 +1094,8 @@ const isActive = z.boolean({
 });
 ```
 
+<br/>
+
 ## Dates
 
 Use z.date() to validate `Date` instances.
@@ -1078,6 +1143,8 @@ 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).
 
+<br/>
+
 ## Zod enums
 
 ```ts
@@ -1133,6 +1200,8 @@ const SalmonAndTrout = FishEnum.extract(["Salmon", "Trout"]);
 const TunaOnly = FishEnum.exclude(["Salmon", "Trout"]);
 ```
 
+<br/>
+
 ## 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()`.
@@ -1201,6 +1270,8 @@ You can access the underlying object with the `.enum` property:
 FruitEnum.enum.Apple; // "apple"
 ```
 
+<br/>
+
 ## Optionals
 
 You can make any schema optional with `z.optional()`. This wraps the schema in a `ZodOptional` instance and returns the result.
@@ -1229,6 +1300,8 @@ const optionalString = stringSchema.optional();
 optionalString.unwrap() === stringSchema; // true
 ```
 
+<br/>
+
 ## Nullables
 
 Similarly, you can create nullable types with `z.nullable()`.
@@ -1254,6 +1327,8 @@ const nullableString = stringSchema.nullable();
 nullableString.unwrap() === stringSchema; // true
 ```
 
+<br/>
+
 ## Objects
 
 ```ts
@@ -1522,6 +1597,8 @@ person.parse({
 
 Using `.catchall()` obviates `.passthrough()` , `.strip()` , or `.strict()`. All keys are now considered "known".
 
+<br/>
+
 ## Arrays
 
 ```ts
@@ -1578,6 +1655,8 @@ z.string().array().length(5); // must contain 5 items exactly
 
 Unlike `.nonempty()` these methods do not change the inferred type.
 
+<br/>
+
 ## Tuples
 
 Unlike arrays, tuples have a fixed number of elements and each element can have a different type.
@@ -1603,6 +1682,8 @@ const result = variadicTuple.parse(["hello", 1, 2, 3]);
 // => [string, ...number[]];
 ```
 
+<br/>
+
 ## Unions
 
 Zod includes a built-in `z.union` method for composing "OR" types.
@@ -1638,6 +1719,8 @@ console.log(optionalUrl.safeParse("https://zod.dev").success); // true
 console.log(optionalUrl.safeParse("not a valid url").success); // false
 ```
 
+<br/>
+
 ## Discriminated unions
 
 A discriminated union is a union of object schemas that all share a particular key.
@@ -1680,6 +1763,8 @@ const B = z.discriminatedUnion("status", [
 const AB = z.discriminatedUnion("status", [...A.options, ...B.options]);
 ```
 
+<br/>
+
 ## Records
 
 Record schemas are used to validate types such as `Record<string, number>`. This is particularly useful for storing or caching items by ID.
@@ -1734,6 +1819,8 @@ 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.
 
+<br/>
+
 ## Maps
 
 ```ts
@@ -1743,6 +1830,8 @@ type StringNumberMap = z.infer<typeof stringNumberMap>;
 // type StringNumberMap = Map<string, number>
 ```
 
+<br/>
+
 ## Sets
 
 ```ts
@@ -1760,6 +1849,8 @@ z.set(z.string()).max(5); // must contain 5 or fewer items
 z.set(z.string()).size(5); // must contain 5 items exactly
 ```
 
+<br/>
+
 ## Intersections
 
 Intersections are useful for creating "logical AND" types. This is useful for intersecting two object types.
@@ -1808,6 +1899,8 @@ type Teacher = z.infer<typeof Teacher>;
 // { id:string; name:string };
 ```  -->
 
+<br/>
+
 ## 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".
@@ -1898,6 +1991,8 @@ 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).
 
+<br/>
+
 ## Promises
 
 ```ts
@@ -1929,6 +2024,8 @@ 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. -->
 
+<br/>
+
 ## 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.
@@ -1945,6 +2042,8 @@ TestSchema.parse(new Test()); // passes
 TestSchema.parse(blob); // throws
 ```
 
+<br/>
+
 ## 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".
@@ -2028,6 +2127,8 @@ myFunction.returnType();
 * `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. -->
 
+<br/>
+
 ## Preprocess
 
 > Zod now supports primitive coercion without the need for `.preprocess()`. See the [coercion docs](#coercion-for-primitives) for more information.
@@ -2042,6 +2143,8 @@ 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.
 
+<br/>
+
 ## 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.
@@ -2069,6 +2172,8 @@ You can customize the error message and other options by passing a second argume
 z.custom<...>((val) => ..., "custom error message");
 ```
 
+<br/>
+
 ## Schema methods
 
 All Zod schemas contain certain methods.
@@ -2654,61 +2759,7 @@ z.string()
 
 The `.pipe()` method returns a `ZodPipeline` instance.
 
-#### You can use `.pipe()` to fix common issues with `z.coerce`.
-
-You can constrain the input to types that work well with your chosen coercion. Then use `.pipe()` to apply the coercion.
-
-without constrained input:
-
-```ts
-const toDate = z.coerce.date();
-
-// works intuitively
-console.log(toDate.safeParse("2023-01-01").success); // true
-
-// might not be what you want
-console.log(toDate.safeParse(null).success); // true
-```
-
-with constrained input:
-
-```ts
-const datelike = z.union([z.number(), z.string(), z.date()]);
-const datelikeToDate = datelike.pipe(z.coerce.date());
-
-// still works intuitively
-console.log(datelikeToDate.safeParse("2023-01-01").success); // true
-
-// more likely what you want
-console.log(datelikeToDate.safeParse(null).success); // false
-```
-
-You can also use this technique to avoid coercions that throw uncaught errors.
-
-without constrained input:
-
-```ts
-const toBigInt = z.coerce.bigint();
-
-// works intuitively
-console.log(toBigInt.safeParse("42")); // true
-
-// probably not what you want
-console.log(toBigInt.safeParse(null)); // throws uncaught error
-```
-
-with constrained input:
-
-```ts
-const toNumber = z.number().or(z.string()).pipe(z.coerce.number());
-const toBigInt = z.bigint().or(toNumber).pipe(z.coerce.bigint());
-
-// still works intuitively
-console.log(toBigInt.safeParse("42").success); // true
-
-// error handled by zod, more likely what you want
-console.log(toBigInt.safeParse(null).success); // false
-```
+<br/>
 
 ## Guides and concepts
 
@@ -2879,6 +2930,8 @@ if (!result.success) {
 }
 ```
 
+<br/>
+
 ## 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.
@@ -3005,13 +3058,15 @@ This more declarative API makes schema definitions vastly more concise.
 
 ### Runtypes
 
-[https://github.com/pelotom/runtypes](https://github.com/pelotom/runtypes)
+[https://github.com/runtypes/runtypes](https://github.com/runtypes/runtypes)
 
-Good type inference support.
+Runtypes is focused on ergonomics, with good type inference support.
 
 - Supports "pattern matching": computed properties that distribute over unions
+- Supports branded types
+- Supports template literals
+- Supports conformance to predefined static types
 - Missing object methods: (deepPartial, merge)
-- Missing nonempty arrays with proper typing (`[T, ...T[]]`)
 - Missing promise schemas
 - Missing error customization
 
@@ -3023,6 +3078,8 @@ 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.
 
+<br/>
+
 ## Changelog
 
 View the changelog at [CHANGELOG.md](CHANGELOG.md)

package/lib/helpers/util.d.ts

@@ -22,7 +22,7 @@ export declare namespace util {
     export {};
 }
 export declare namespace objectUtil {
-    export type MergeShapes<U, V> = {
+    export type MergeShapes<U, V> = keyof U & keyof V extends never ? U & V : {
         [k in Exclude<keyof U, keyof V>]: U[k];
     } & V;
     type optionalKeys<T extends object> = {
@@ -49,7 +49,7 @@ export declare namespace objectUtil {
         [k in noNeverKeys<T>]: k extends keyof T ? T[k] : never;
     }>;
     export const mergeShapes: <U, T>(first: U, second: T) => T & U;
-    export type extendShape<A extends object, B extends object> = {
+    export type extendShape<A extends object, B extends object> = keyof A & keyof B extends never ? A & B : {
         [K in keyof A as K extends keyof B ? never : K]: A[K];
     } & {
         [K in keyof B]: B[K];

package/lib/index.mjs

@@ -4144,7 +4144,23 @@ ZodReadonly.create = (type, params) => {
         ...processCreateParams(params),
     });
 };
-function custom(check, params = {}, 
+////////////////////////////////////////
+////////////////////////////////////////
+//////////                    //////////
+//////////      z.custom      //////////
+//////////                    //////////
+////////////////////////////////////////
+////////////////////////////////////////
+function cleanParams(params, data) {
+    const p = typeof params === "function"
+        ? params(data)
+        : typeof params === "string"
+            ? { message: params }
+            : params;
+    const p2 = typeof p === "string" ? { message: p } : p;
+    return p2;
+}
+function custom(check, _params = {}, 
 /**
  * @deprecated
  *
@@ -4159,16 +4175,23 @@ fatal) {
     if (check)
         return ZodAny.create().superRefine((data, ctx) => {
             var _a, _b;
-            if (!check(data)) {
-                const p = typeof params === "function"
-                    ? params(data)
-                    : typeof params === "string"
-                        ? { message: params }
-                        : params;
-                const _fatal = (_b = (_a = p.fatal) !== null && _a !== void 0 ? _a : fatal) !== null && _b !== void 0 ? _b : true;
-                const p2 = typeof p === "string" ? { message: p } : p;
-                ctx.addIssue({ code: "custom", ...p2, fatal: _fatal });
+            const r = check(data);
+            if (r instanceof Promise) {
+                return r.then((r) => {
+                    var _a, _b;
+                    if (!r) {
+                        const params = cleanParams(_params, data);
+                        const _fatal = (_b = (_a = params.fatal) !== null && _a !== void 0 ? _a : fatal) !== null && _b !== void 0 ? _b : true;
+                        ctx.addIssue({ code: "custom", ...params, fatal: _fatal });
+                    }
+                });
+            }
+            if (!r) {
+                const params = cleanParams(_params, data);
+                const _fatal = (_b = (_a = params.fatal) !== null && _a !== void 0 ? _a : fatal) !== null && _b !== void 0 ? _b : true;
+                ctx.addIssue({ code: "custom", ...params, fatal: _fatal });
             }
+            return;
         });
     return ZodAny.create();
 }

package/lib/index.umd.js

@@ -4150,7 +4150,23 @@
             ...processCreateParams(params),
         });
     };
-    function custom(check, params = {}, 
+    ////////////////////////////////////////
+    ////////////////////////////////////////
+    //////////                    //////////
+    //////////      z.custom      //////////
+    //////////                    //////////
+    ////////////////////////////////////////
+    ////////////////////////////////////////
+    function cleanParams(params, data) {
+        const p = typeof params === "function"
+            ? params(data)
+            : typeof params === "string"
+                ? { message: params }
+                : params;
+        const p2 = typeof p === "string" ? { message: p } : p;
+        return p2;
+    }
+    function custom(check, _params = {}, 
     /**
      * @deprecated
      *
@@ -4165,16 +4181,23 @@
         if (check)
             return ZodAny.create().superRefine((data, ctx) => {
                 var _a, _b;
-                if (!check(data)) {
-                    const p = typeof params === "function"
-                        ? params(data)
-                        : typeof params === "string"
-                            ? { message: params }
-                            : params;
-                    const _fatal = (_b = (_a = p.fatal) !== null && _a !== void 0 ? _a : fatal) !== null && _b !== void 0 ? _b : true;
-                    const p2 = typeof p === "string" ? { message: p } : p;
-                    ctx.addIssue({ code: "custom", ...p2, fatal: _fatal });
+                const r = check(data);
+                if (r instanceof Promise) {
+                    return r.then((r) => {
+                        var _a, _b;
+                        if (!r) {
+                            const params = cleanParams(_params, data);
+                            const _fatal = (_b = (_a = params.fatal) !== null && _a !== void 0 ? _a : fatal) !== null && _b !== void 0 ? _b : true;
+                            ctx.addIssue({ code: "custom", ...params, fatal: _fatal });
+                        }
+                    });
+                }
+                if (!r) {
+                    const params = cleanParams(_params, data);
+                    const _fatal = (_b = (_a = params.fatal) !== null && _a !== void 0 ? _a : fatal) !== null && _b !== void 0 ? _b : true;
+                    ctx.addIssue({ code: "custom", ...params, fatal: _fatal });
                 }
+                return;
             });
         return ZodAny.create();
     }

package/lib/types.d.ts

@@ -935,7 +935,7 @@ export declare class ZodReadonly<T extends ZodTypeAny> extends ZodType<MakeReado
 type CustomParams = CustomErrorParams & {
     fatal?: boolean;
 };
-export declare function custom<T>(check?: (data: any) => any, params?: string | CustomParams | ((input: any) => CustomParams), 
+export declare function custom<T>(check?: (data: any) => any, _params?: string | CustomParams | ((input: any) => CustomParams), 
 /**
  * @deprecated
  *

package/lib/types.js

@@ -3654,7 +3654,23 @@ ZodReadonly.create = (type, params) => {
         ...processCreateParams(params),
     });
 };
-function custom(check, params = {}, 
+////////////////////////////////////////
+////////////////////////////////////////
+//////////                    //////////
+//////////      z.custom      //////////
+//////////                    //////////
+////////////////////////////////////////
+////////////////////////////////////////
+function cleanParams(params, data) {
+    const p = typeof params === "function"
+        ? params(data)
+        : typeof params === "string"
+            ? { message: params }
+            : params;
+    const p2 = typeof p === "string" ? { message: p } : p;
+    return p2;
+}
+function custom(check, _params = {}, 
 /**
  * @deprecated
  *
@@ -3669,16 +3685,23 @@ fatal) {
     if (check)
         return ZodAny.create().superRefine((data, ctx) => {
             var _a, _b;
-            if (!check(data)) {
-                const p = typeof params === "function"
-                    ? params(data)
-                    : typeof params === "string"
-                        ? { message: params }
-                        : params;
-                const _fatal = (_b = (_a = p.fatal) !== null && _a !== void 0 ? _a : fatal) !== null && _b !== void 0 ? _b : true;
-                const p2 = typeof p === "string" ? { message: p } : p;
-                ctx.addIssue({ code: "custom", ...p2, fatal: _fatal });
+            const r = check(data);
+            if (r instanceof Promise) {
+                return r.then((r) => {
+                    var _a, _b;
+                    if (!r) {
+                        const params = cleanParams(_params, data);
+                        const _fatal = (_b = (_a = params.fatal) !== null && _a !== void 0 ? _a : fatal) !== null && _b !== void 0 ? _b : true;
+                        ctx.addIssue({ code: "custom", ...params, fatal: _fatal });
+                    }
+                });
+            }
+            if (!r) {
+                const params = cleanParams(_params, data);
+                const _fatal = (_b = (_a = params.fatal) !== null && _a !== void 0 ? _a : fatal) !== null && _b !== void 0 ? _b : true;
+                ctx.addIssue({ code: "custom", ...params, fatal: _fatal });
             }
+            return;
         });
     return ZodAny.create();
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zod",
-  "version": "3.24.1",
+  "version": "3.24.3",
   "author": "Colin McDonnell <colin@colinhacks.com>",
   "repository": {
     "type": "git",