zod 3.14.2 → 3.14.5

package/README.md

@@ -3,7 +3,7 @@
   <h1 align="center">Zod</h1>
 </p>
 <p align="center">
-<a href="https://github.com/edgedb/edgedb-js/actions"><img src="https://github.com/colinhacks/zod/workflows/test.yml/badge.svg?event=push&branch=master" alt="Zod CI status" /></a>
+<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>
 <a href="https://opensource.org/licenses/MIT" rel="nofollow"><img src="https://img.shields.io/github/license/colinhacks/zod" alt="License"></a>
 <a href="https://www.npmjs.com/package/zod" rel="nofollow"><img src="https://img.shields.io/npm/dw/zod.svg" alt="npm"></a>
@@ -94,8 +94,10 @@ These docs have been translated into [Chinese](./README_ZH.md).
   - [.promise](#promise)
   - [.or](#or)
   - [.and](#and)
-- [Type inference](#type-inference)
-- [Errors](#errors)
+- [Guides and concepts](#guides-and-concepts)
+  - [Type inference](#type-inference)
+  - [Writing generic functions](#writing-generic-functions)
+  - [Error handling](#error-handling)
 - [Comparison](#comparison)
   - [Joi](#joi)
   - [Yup](#yup)
@@ -123,76 +125,123 @@ Some other great aspects:
 
 # Sponsorship
 
-Sponsorship at any level is appreciated and encouraged. Zod is maintained by a solo developer ([hi!](https://twitter.com/colinhacks)). For individual developers, consider the [Cup of Coffee tier](https://github.com/sponsors/colinhacks). If you built a paid product using Zod, consider the [Startup tier](https://github.com/sponsors/colinhacks). You can learn more about the tiers at [github.com/sponsors/colinhacks](https://github.com/sponsors/colinhacks).
+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).
 
-### Sponsors
+### Gold
 
 <table>
   <tr>
-   <td align="center">
+    <td align="center">
+      <a href="https://astro.build/">
+        <img src="https://avatars.githubusercontent.com/u/44914786?s=200&v=4" width="200px;" alt="" />
+      </a>
+      <br />
+      <b>Astro</b>
+      <br />
+      <a href="https://astro.build">astro.build</a>
+      <br />
+      <p width="200px">
+        Astro is a new kind of static <br/>
+        site builder for the modern web. <br/>
+        Powerful developer experience meets <br/>
+        lightweight output.</p>
+    </td>
+    <td align="center">
+      <a href="https://glow.app/">
+        <img src="https://i.imgur.com/R0R43S2.jpg" width="200px;" alt="" />
+      </a>
+      <br />
+      <b>Glow Wallet</b>
+      <br />
+      <a href="https://glow.app/">glow.app</a>
+      <br />
+      <p width="200px">Your new favorite
+        <br/>
+      Solana wallet.</p>
+    </td>
+  </tr>
+  <tr>
+    <td align="center">
       <a href="https://deletype.com/">
-        <img src="https://avatars0.githubusercontent.com/u/15068039?s=200&v=4" width="100px;" alt="" />
+        <img src="https://avatars0.githubusercontent.com/u/15068039?s=200&v=4" width="200px;" alt="" />
       </a>
-      <br>
+      <br />
       <b>Deletype</b>
-      <br>
-      <a href="https://deletype.com/">deletype.com/</a>
+      <br />
+      <a href="https://deletype.com">deletype.com</a>
     </td>
-  <td align="center">
-      <a href="https://github.com/kevinsimper">
-        <img src="https://avatars1.githubusercontent.com/u/1126497?s=460&v=4" width="100px;" alt="" />
+  </tr>
+</table>
+
+### Silver
+
+<table>
+  <tr>
+    <td align="center">
+      <a href="https://snaplet.dev">
+        <img src="https://avatars.githubusercontent.com/u/69029941?s=200&v=4" width="150px;" alt="" />
       </a>
-      <br>
-      <b>Kevin Simper</b>
-      <br>
-      <a href="https://github.com/kevinsimper">@kevinsimper</a>
+      <br />
+      <b>Snaplet</b>
+      <br />
+      <a href="https://snaplet.dev">snaplet.dev</a>
+    </td>
+     <td align="center">
+      <a href="https://marcatopartners.com/">
+        <img src="https://avatars.githubusercontent.com/u/84106192?s=200&v=4" width="150px;" alt="Marcato Partners" />
+      </a>
+      <br />
+      <b>Marcato Partners</b>
+      <br />
+      <a href="https://marcatopartners.com/">marcatopartners.com</a>
+    </td>
+     <td align="center">
+      <a href="https://github.com/macandcheese-spaghetticode">
+        <img src="https://avatars.githubusercontent.com/u/76997592?v=4" width="150px;" alt="Trip" />
+      </a>
+      <br />
+      <b>Trip</b>
     </td>
+  </tr>
+</table>
+
+### Bronze
+
+<table>
+  <tr>
     <td align="center">
       <a href="https://twitter.com/flybayer">
         <img src="https://avatars2.githubusercontent.com/u/8813276?s=460&u=4ff8beb9a67b173015c4b426a92d89cab960af1b&v=4" width="100px;" alt=""/>
       </a>
-      <br>
+      <br />
       <b>Brandon Bayer</b>
       <br/>
       <a href="https://twitter.com/flybayer">@flybayer</a>,
       <span>creator of <a href="https://blitzjs.com">Blitz.js</a></span>
       <br />
     </td>
-
-  </tr>
-  <tr>
-    <td align="center">
-      <a href="https://www.bamboocreative.nz/">
-        <img src="https://avatars1.githubusercontent.com/u/41406870?s=460&v=4" width="100px;" alt="" />
-      </a>
-      <br>
-      <b>Bamboo Creative</b>
-      <br>
-      <a href="https://www.bamboocreative.nz/">bamboocreative.nz</a>
-    </td>
     <td align="center">
-      <a href="https://github.com/jeremyBanks">
-        <img src="https://avatars.githubusercontent.com/u/18020?s=400&u=dba6c1402ae1746a276a5d256e01d68e774a0e9d&v=4" width="100px;" alt="" />
+      <a href="https://github.com/brabeji">
+        <img src="https://avatars.githubusercontent.com/u/2237954?v=4" width="100px;" alt=""/>
       </a>
-      <br>
-      <b>Jeremy Banks</b>
-      <br>
-      <a href="https://github.com/jeremyBanks">github.com/jeremyBanks</a>
+      <br />
+      <b>Jiří Brabec</b>
+      <br/>
+      <a href="https://github.com/brabeji">@brabeji</a>
+      <br />
     </td>
      <td align="center">
-      <a href="https://marcatopartners.com/">
-        <img src="https://avatars.githubusercontent.com/u/84106192?s=200&v=4" width="100px;" alt="Marcato Partners" />
+      <a href="https://twitter.com/alexdotjs">
+        <img src="https://avatars.githubusercontent.com/u/459267?v=4" width="100px;" alt="" />
       </a>
-      <br>
-      <b>Marcato Partners</b>
-      <br>
-      <a href="https://marcatopartners.com/">marcatopartners.com</a>
+      <br />
+      <b>Alex Johansson</b>
+      <br />
+      <a href="https://twitter.com/alexdotjs">@alexdotjs</a>
     </td>
   </tr>
 </table>
 
-_To get your name + Twitter + website here, sponsor Zod at the [Freelancer](https://github.com/sponsors/colinhacks) or [Consultancy](https://github.com/sponsors/colinhacks) tier._
-
 # Installation
 
 To install Zod v3:
@@ -241,6 +290,9 @@ There are a growing number of tools that are built atop or support Zod natively!
 - [`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
 - [`zod-prisma`](https://github.com/CarterGrimmeisen/zod-prisma): Generate Zod schemas from your Prisma schema.
+- [`fastify-type-provider-zod`](https://github.com/turkerdev/fastify-type-provider-zod): Create Fastify type providers from Zod schemas
+- [`Supervillain`](https://github.com/Southclaws/supervillain): Generate Zod schemas from your Go structs
+- [`zod-to-openapi`](https://github.com/asteasolutions/zod-to-openapi): Generate full OpenAPI (Swagger) docs from Zod, including schemas, endpoints & parameters
 
 ### Form integrations
 
@@ -1134,9 +1186,9 @@ const Category: z.ZodType<Category> = BaseCategory.merge(
 If you want to validate any JSON value, you can use the snippet below.
 
 ```ts
-type Literal = boolean | null | number | string;
-type Json = Literal | { [key: string]: Json } | Json[];
 const literalSchema = z.union([z.string(), z.number(), z.boolean(), z.null()]);
+type Literal = z.infer<typeof literalSchema>;
+type Json = Literal | { [key: string]: Json } | Json[];
 const jsonSchema: z.ZodType<Json> = z.lazy(() =>
   z.union([literalSchema, z.array(jsonSchema), z.record(jsonSchema)])
 );
@@ -1687,7 +1739,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() }));
 ```
 
-# Type inference
+# Guides and concepts
+
+## Type inference
 
 You can extract the TypeScript type of any schema with `z.infer<typeof mySchema>` .
 
@@ -1716,16 +1770,72 @@ type output = z.output<typeof stringToNumber>; // number
 type inferred = z.infer<typeof stringToNumber>; // number
 ```
 
-# Errors
+## 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:
+
+```ts
+function makeSchemaOptional<T>(schema: z.ZodType<T>) {
+  return schema.optional();
+}
+```
+
+This approach has some issues. The `schema` variable in this function is typed as an instance of `ZodType`, which is an abstract class that all Zod schemas inherit from. This approach loses type information, namely _which subclass_ the input actually is.
+
+```ts
+const arg = makeSchemaOptional(z.string());
+arg.unwrap();
+```
+
+A better approach is for the generate parameter to refer to _the schema as a whole_.
+
+```ts
+function makeSchemaOptional<T extends z.ZodTypeAny>(schema: T) {
+  return schema.optional();
+}
+```
+
+> `ZodTypeAny` is just a shorthand for `ZodType<any, any, any>`, a type that is broad enough to match any Zod schema.
+
+As you can see, `schema` is now fully and properly typed.
+
+```ts
+const arg = makeSchemaOptional(z.string());
+arg.unwrap(); // ZodString
+```
+
+### Restricting valid schemas
+
+The `ZodType` class has three generic parameters.
+
+```ts
+class ZodType<
+  Output,
+  Def extends ZodTypeDef = ZodTypeDef,
+  Input = Output
+> { ... }
+```
+
+By constraining these in your generic input, you can limit what schemas are allowable as inputs to your function:
+
+```ts
+function makeSchemaOptional<T extends z.ZodType<string>>(schema: T) {
+  return schema.optional();
+}
+
+makeSchemaOptional(z.string());
+// works fine
+
+makeSchemaOptional(z.number());
+// Error: 'ZodNumber' is not assignable to parameter of type 'ZodType<string, ZodTypeDef, string>'
+```
+
+## 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;

package/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./lib";
+export as namespace Zod;

package/lib/ZodError.d.ts

@@ -1,8 +1,18 @@
+import type { TypeOf, ZodType } from ".";
 import { ZodParsedType } from "./helpers/parseUtil";
 import { Primitive } from "./helpers/typeAliases";
 import { util } from "./helpers/util";
+declare type allKeys<T> = T extends any ? keyof T : never;
+export declare type inferFlattenedErrors<T extends ZodType<any, any, any>, U = string> = typeToFlattenedError<TypeOf<T>, U>;
+export declare type typeToFlattenedError<T, U = string> = {
+    formErrors: U[];
+    fieldErrors: {
+        [P in allKeys<T>]?: U[];
+    };
+};
 export declare const ZodIssueCode: {
     invalid_type: "invalid_type";
+    invalid_literal: "invalid_literal";
     custom: "custom";
     invalid_union: "invalid_union";
     invalid_union_discriminator: "invalid_union_discriminator";
@@ -27,6 +37,10 @@ export interface ZodInvalidTypeIssue extends ZodIssueBase {
     expected: ZodParsedType;
     received: ZodParsedType;
 }
+export interface ZodInvalidLiteralIssue extends ZodIssueBase {
+    code: typeof ZodIssueCode.invalid_literal;
+    expected: unknown;
+}
 export interface ZodUnrecognizedKeysIssue extends ZodIssueBase {
     code: typeof ZodIssueCode.unrecognized_keys;
     keys: string[];
@@ -87,47 +101,34 @@ export interface ZodCustomIssue extends ZodIssueBase {
 export declare type DenormalizedError = {
     [k: string]: DenormalizedError | string[];
 };
-export declare type ZodIssueOptionalMessage = ZodInvalidTypeIssue | ZodUnrecognizedKeysIssue | ZodInvalidUnionIssue | ZodInvalidUnionDiscriminatorIssue | ZodInvalidEnumValueIssue | ZodInvalidArgumentsIssue | ZodInvalidReturnTypeIssue | ZodInvalidDateIssue | ZodInvalidStringIssue | ZodTooSmallIssue | ZodTooBigIssue | ZodInvalidIntersectionTypesIssue | ZodNotMultipleOfIssue | ZodCustomIssue;
+export declare type ZodIssueOptionalMessage = ZodInvalidTypeIssue | ZodInvalidLiteralIssue | ZodUnrecognizedKeysIssue | ZodInvalidUnionIssue | ZodInvalidUnionDiscriminatorIssue | ZodInvalidEnumValueIssue | ZodInvalidArgumentsIssue | ZodInvalidReturnTypeIssue | ZodInvalidDateIssue | ZodInvalidStringIssue | ZodTooSmallIssue | ZodTooBigIssue | ZodInvalidIntersectionTypesIssue | ZodNotMultipleOfIssue | ZodCustomIssue;
 export declare type ZodIssue = ZodIssueOptionalMessage & {
     message: string;
 };
 export declare const quotelessJson: (obj: any) => string;
-export declare type ZodFormattedError<T> = {
-    _errors: string[];
+export declare type ZodFormattedError<T, U = string> = {
+    _errors: U[];
 } & (T extends [any, ...any[]] ? {
     [K in keyof T]?: ZodFormattedError<T[K]>;
 } : T extends any[] ? ZodFormattedError<T[number]>[] : T extends object ? {
     [K in keyof T]?: ZodFormattedError<T[K]>;
 } : unknown);
+export declare type inferFormattedError<T extends ZodType<any, any, any>, U = string> = ZodFormattedError<TypeOf<T>, U>;
 export declare class ZodError<T = any> extends Error {
     issues: ZodIssue[];
     get errors(): ZodIssue[];
     constructor(issues: ZodIssue[]);
-    format: () => ZodFormattedError<T>;
+    format(): ZodFormattedError<T>;
+    format<U>(mapper: (issue: ZodIssue) => U): ZodFormattedError<T, U>;
     static create: (issues: ZodIssue[]) => ZodError<any>;
     toString(): string;
     get message(): string;
     get isEmpty(): boolean;
     addIssue: (sub: ZodIssue) => void;
     addIssues: (subs?: ZodIssue[]) => void;
-    flatten(mapper?: (issue: ZodIssue) => string): {
-        formErrors: string[];
-        fieldErrors: {
-            [k: string]: string[];
-        };
-    };
-    flatten<U>(mapper?: (issue: ZodIssue) => U): {
-        formErrors: U[];
-        fieldErrors: {
-            [k: string]: U[];
-        };
-    };
-    get formErrors(): {
-        formErrors: string[];
-        fieldErrors: {
-            [k: string]: string[];
-        };
-    };
+    flatten(): typeToFlattenedError<T>;
+    flatten<U>(mapper?: (issue: ZodIssue) => U): typeToFlattenedError<T, U>;
+    get formErrors(): typeToFlattenedError<T, string>;
 }
 declare type stripPath<T extends object> = T extends any ? util.OmitKeys<T, "path"> : never;
 export declare type IssueData = stripPath<ZodIssueOptionalMessage> & {

package/lib/ZodError.js

@@ -4,6 +4,7 @@ exports.setErrorMap = exports.overrideErrorMap = exports.defaultErrorMap = expor
 const util_1 = require("./helpers/util");
 exports.ZodIssueCode = util_1.util.arrayToEnum([
     "invalid_type",
+    "invalid_literal",
     "custom",
     "invalid_union",
     "invalid_union_discriminator",
@@ -27,51 +28,6 @@ class ZodError extends Error {
     constructor(issues) {
         super();
         this.issues = [];
-        this.format = () => {
-            const fieldErrors = { _errors: [] };
-            const processError = (error) => {
-                for (const issue of error.issues) {
-                    if (issue.code === "invalid_union") {
-                        issue.unionErrors.map(processError);
-                    }
-                    else if (issue.code === "invalid_return_type") {
-                        processError(issue.returnTypeError);
-                    }
-                    else if (issue.code === "invalid_arguments") {
-                        processError(issue.argumentsError);
-                    }
-                    else if (issue.path.length === 0) {
-                        fieldErrors._errors.push(issue.message);
-                    }
-                    else {
-                        let curr = fieldErrors;
-                        let i = 0;
-                        while (i < issue.path.length) {
-                            const el = issue.path[i];
-                            const terminal = i === issue.path.length - 1;
-                            if (!terminal) {
-                                if (typeof el === "string") {
-                                    curr[el] = curr[el] || { _errors: [] };
-                                }
-                                else if (typeof el === "number") {
-                                    const errorArray = [];
-                                    errorArray._errors = [];
-                                    curr[el] = curr[el] || errorArray;
-                                }
-                            }
-                            else {
-                                curr[el] = curr[el] || { _errors: [] };
-                                curr[el]._errors.push(issue.message);
-                            }
-                            curr = curr[el];
-                            i++;
-                        }
-                    }
-                }
-            };
-            processError(this);
-            return fieldErrors;
-        };
         this.addIssue = (sub) => {
             this.issues = [...this.issues, sub];
         };
@@ -92,6 +48,55 @@ class ZodError extends Error {
     get errors() {
         return this.issues;
     }
+    format(_mapper) {
+        const mapper = _mapper ||
+            function (issue) {
+                return issue.message;
+            };
+        const fieldErrors = { _errors: [] };
+        const processError = (error) => {
+            for (const issue of error.issues) {
+                if (issue.code === "invalid_union") {
+                    issue.unionErrors.map(processError);
+                }
+                else if (issue.code === "invalid_return_type") {
+                    processError(issue.returnTypeError);
+                }
+                else if (issue.code === "invalid_arguments") {
+                    processError(issue.argumentsError);
+                }
+                else if (issue.path.length === 0) {
+                    fieldErrors._errors.push(mapper(issue));
+                }
+                else {
+                    let curr = fieldErrors;
+                    let i = 0;
+                    while (i < issue.path.length) {
+                        const el = issue.path[i];
+                        const terminal = i === issue.path.length - 1;
+                        if (!terminal) {
+                            if (typeof el === "string") {
+                                curr[el] = curr[el] || { _errors: [] };
+                            }
+                            else if (typeof el === "number") {
+                                const errorArray = [];
+                                errorArray._errors = [];
+                                curr[el] = curr[el] || errorArray;
+                            }
+                        }
+                        else {
+                            curr[el] = curr[el] || { _errors: [] };
+                            curr[el]._errors.push(mapper(issue));
+                        }
+                        curr = curr[el];
+                        i++;
+                    }
+                }
+            }
+        };
+        processError(this);
+        return fieldErrors;
+    }
     toString() {
         return this.message;
     }
@@ -135,6 +140,9 @@ const defaultErrorMap = (issue, _ctx) => {
                 message = `Expected ${issue.expected}, received ${issue.received}`;
             }
             break;
+        case exports.ZodIssueCode.invalid_literal:
+            message = `Invalid literal value, expected ${JSON.stringify(issue.expected)}`;
+            break;
         case exports.ZodIssueCode.unrecognized_keys:
             message = `Unrecognized key(s) in object: ${issue.keys
                 .map((k) => `'${k}'`)

package/lib/helpers/parseUtil.d.ts

@@ -42,7 +42,6 @@ export interface ParseContext {
         readonly issues: ZodIssue[];
         readonly contextualErrorMap?: ZodErrorMap;
         readonly async: boolean;
-        readonly typeCache: Map<any, ZodParsedType> | undefined;
     };
     readonly path: ParsePath;
     readonly schemaErrorMap?: ZodErrorMap;